adcp-signals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AdCP Signals Protocol

This skill enables you to execute the AdCP Signals Protocol with signal agents. Use the standard MCP tools (

get_signals

activate_signal

) exposed by the connected agent.

本Skill可让你借助信号代理执行AdCP Signals Protocol操作。使用已连接代理提供的标准MCP工具（

get_signals

、

activate_signal

）。

Overview

概述

The Signals Protocol provides 2 standardized tasks for discovering and activating targeting data:

Task	Purpose	Response Time
`get_signals`	Discover signals using natural language	~60s
`activate_signal`	Activate a signal on a platform/agent	Minutes-Hours

Signals Protocol提供两项标准化任务，用于发现和激活定向数据：

任务	用途	响应时间
`get_signals`	使用自然语言发现信号	约60秒
`activate_signal`	在平台/代理上激活信号	数分钟至数小时

Typical Workflow

典型工作流程

Discover signals:
```
get_signals
```
with a natural language description of targeting needs
Review options: Evaluate signals by coverage, pricing, and deployment status
Activate if needed:
```
activate_signal
```
for signals not yet live on your platform
Use in campaigns: Reference the activation key in your media buy targeting

发现信号：使用
```
get_signals
```
，输入定向需求的自然语言描述
评估选项：从覆盖范围、定价和部署状态等维度评估信号
按需激活：对尚未在你的平台上线的信号执行
```
activate_signal
```
用于广告活动：在媒体采购定向中引用激活密钥

Task Reference

任务参考

get_signals

Discover signals based on natural language description, with deployment status across platforms.

Request:

json

{
  "signal_spec": "High-income households interested in luxury goods",
  "deliver_to": {
    "deployments": [
      {
        "type": "platform",
        "platform": "the-trade-desk",
        "account": "agency-123"
      }
    ],
    "countries": ["US"]
  },
  "filters": {
    "max_cpm": 5.0,
    "catalog_types": ["marketplace"]
  },
  "max_results": 5
}

Key fields:

```
signal_spec
```
(string, required): Natural language description of desired signals
```
deliver_to
```
(object, required): Where signals will be used
- ```
deployments
```
  (array): Target platforms/agents with
```
type
```
  ,
```
platform
```
  /
```
agent_url
```
  , and optional
```
account
```
- ```
countries
```
  (array): ISO country codes where signals will be used

filters

(object, optional): Filter by

catalog_types

data_providers

max_cpm

min_coverage_percentage

```
max_results
```
(number, optional): Limit number of results

Deployment types:

json

// DSP platform
{ "type": "platform", "platform": "the-trade-desk", "account": "agency-123" }

// Sales agent
{ "type": "agent", "agent_url": "https://salesagent.example.com" }

Response contains:

```
signals
```
: Array of matching signals with:
- ```
signal_agent_segment_id
```
  : Use this in
```
activate_signal
```
- ```
name
```
  ,
```
description
```
  : Human-readable signal info
- ```
data_provider
```
  : Source of the signal data
- ```
coverage_percentage
```
  : Reach relative to agent's population
- ```
deployments
```
  : Status per platform with
```
is_live
```
  ,
```
activation_key
```
  ,
```
estimated_activation_duration_minutes
```
- ```
pricing
```
  : CPM and currency

根据自然语言描述发现信号，同时获取各平台的部署状态。

请求：

json

{
  "signal_spec": "High-income households interested in luxury goods",
  "deliver_to": {
    "deployments": [
      {
        "type": "platform",
        "platform": "the-trade-desk",
        "account": "agency-123"
      }
    ],
    "countries": ["US"]
  },
  "filters": {
    "max_cpm": 5.0,
    "catalog_types": ["marketplace"]
  },
  "max_results": 5
}

关键字段：

```
signal_spec
```
（字符串，必填）：所需信号的自然语言描述
```
deliver_to
```
（对象，必填）：信号的使用场景
- ```
deployments
```
  （数组）：目标平台/代理，包含
```
type
```
  、
```
platform
```
  /
```
agent_url
```
  ，可选
```
account
```
- ```
countries
```
  （数组）：信号将使用的ISO国家代码

filters

（对象，可选）：按

catalog_types

、

data_providers

、

max_cpm

、

min_coverage_percentage

筛选

```
max_results
```
（数字，可选）：限制结果数量

部署类型：

json

// DSP platform
{ "type": "platform", "platform": "the-trade-desk", "account": "agency-123" }

// Sales agent
{ "type": "agent", "agent_url": "https://salesagent.example.com" }

响应包含：

```
signals
```
: 匹配的信号数组，包含：
- ```
signal_agent_segment_id
```
  : 在
```
activate_signal
```
  中使用该ID
- ```
name
```
  ,
```
description
```
  : 便于人类阅读的信号信息
- ```
data_provider
```
  : 信号数据的来源
- ```
coverage_percentage
```
  : 相对于代理受众群体的触达比例
- ```
deployments
```
  : 各平台的状态，包含
```
is_live
```
  ,
```
activation_key
```
  ,
```
estimated_activation_duration_minutes
```
- ```
pricing
```
  : CPM和货币类型

activate_signal

Activate a signal for use on a specific platform or agent.

Request:

json

{
  "signal_agent_segment_id": "luxury_auto_intenders",
  "deployments": [
    {
      "type": "platform",
      "platform": "the-trade-desk",
      "account": "agency-123-ttd"
    }
  ]
}

Key fields:

```
signal_agent_segment_id
```
(string, required): From
```
get_signals
```
response
```
deployments
```
(array, required): Target deployment(s) with
```
type
```
,
```
platform
```
/
```
agent_url
```
, and optional
```
account
```

Response contains:

```
deployments
```
: Array with activation results per target
- ```
activation_key
```
  : The key to use for targeting (segment ID or key-value pair)
- ```
deployed_at
```
  : ISO timestamp when activation completed
- ```
estimated_activation_duration_minutes
```
  : Time remaining if async
```
errors
```
: Any warnings or errors encountered

在特定平台或代理上激活信号以供使用。

请求：

json

{
  "signal_agent_segment_id": "luxury_auto_intenders",
  "deployments": [
    {
      "type": "platform",
      "platform": "the-trade-desk",
      "account": "agency-123-ttd"
    }
  ]
}

关键字段：

```
signal_agent_segment_id
```
（字符串，必填）：来自
```
get_signals
```
的响应结果
```
deployments
```
（数组，必填）：目标部署项，包含
```
type
```
、
```
platform
```
/
```
agent_url
```
，可选
```
account
```

响应包含：

```
deployments
```
: 各目标的激活结果数组
- ```
activation_key
```
  : 用于定向的密钥（细分ID或键值对）
- ```
deployed_at
```
  : 激活完成的ISO时间戳
- ```
estimated_activation_duration_minutes
```
  : 异步操作的剩余时间
```
errors
```
: 遇到的任何警告或错误

Key Concepts

核心概念

Deployment Targets

部署目标

Signals can be activated on two types of targets:

DSP Platforms:

json

{
  "type": "platform",
  "platform": "the-trade-desk",
  "account": "agency-123"
}

Sales Agents:

json

{
  "type": "agent",
  "agent_url": "https://wonderstruck.salesagents.com"
}

信号可在两类目标上激活：

DSP平台：

json

{
  "type": "platform",
  "platform": "the-trade-desk",
  "account": "agency-123"
}

销售代理：

json

{
  "type": "agent",
  "agent_url": "https://wonderstruck.salesagents.com"
}

Activation Keys

激活密钥

When signals are live, the response includes an activation key for targeting:

Segment ID format (typical for DSPs):

json

{
  "type": "segment_id",
  "segment_id": "ttd_segment_12345"
}

Key-Value format (typical for sales agents):

json

{
  "type": "key_value",
  "key": "audience_segment",
  "value": "luxury_auto_intenders"
}

当信号上线后，响应结果会包含用于定向的激活密钥：

细分ID格式（DSP常用）：

json

{
  "type": "segment_id",
  "segment_id": "ttd_segment_12345"
}

键值对格式（销售代理常用）：

json

{
  "type": "key_value",
  "key": "audience_segment",
  "value": "luxury_auto_intenders"
}

Signal Types

信号类型

marketplace: Licensed from data providers (CPM pricing)
custom: Built for specific principal accounts
owned: Private signals from your own data (no cost)

marketplace: 从数据提供商处授权获取（按CPM定价）
custom: 为特定主账户定制
owned: 来自自有数据的私有信号（无成本）

Coverage Percentage

覆盖比例

Indicates signal reach relative to the agent's population:

99%: Very broad signal (matches most identifiers)
50%: Medium signal
1%: Very niche signal

表示信号相对于代理受众群体的触达范围：

99%：覆盖极广的信号（匹配大多数标识）
50%：中等覆盖信号
1%：非常小众的信号

Asynchronous Operations

异步操作

Signal activation may take time. Check the response:

```
is_live: true
```
+
```
activation_key
```
: Ready to use immediately

is_live: false

estimated_activation_duration_minutes

: Activation in progress

Poll or use webhooks to check completion status.

信号激活可能需要一定时间。请查看响应结果：

```
is_live: true
```
+
```
activation_key
```
: 可立即使用
```
is_live: false
```
+
```
estimated_activation_duration_minutes
```
: 激活中可通过轮询或webhook检查完成状态。

Error Handling

错误处理

Common error codes:

```
SIGNAL_AGENT_SEGMENT_NOT_FOUND
```
: Invalid signal_agent_segment_id
```
ACTIVATION_FAILED
```
: Could not activate signal
```
ALREADY_ACTIVATED
```
: Signal already active on target
```
DEPLOYMENT_UNAUTHORIZED
```
: Not authorized for platform/account
```
AGENT_NOT_FOUND
```
: Private agent not visible to this principal
```
AGENT_ACCESS_DENIED
```
: Not authorized for this signal agent

Error responses include:

json

{
  "errors": [
    {
      "code": "DEPLOYMENT_UNAUTHORIZED",
      "message": "Account not authorized for this data provider",
      "field": "deployment.account",
      "suggestion": "Contact your account manager to enable access"
    }
  ]
}

常见错误代码：

```
SIGNAL_AGENT_SEGMENT_NOT_FOUND
```
: 无效的signal_agent_segment_id
```
ACTIVATION_FAILED
```
: 无法激活信号
```
ALREADY_ACTIVATED
```
: 信号已在目标平台激活
```
DEPLOYMENT_UNAUTHORIZED
```
: 无平台/账户权限
```
AGENT_NOT_FOUND
```
: 无法找到该私有代理
```
AGENT_ACCESS_DENIED
```
: 无该信号代理的访问权限

错误响应示例：

json

{
  "errors": [
    {
      "code": "DEPLOYMENT_UNAUTHORIZED",
      "message": "Account not authorized for this data provider",
      "field": "deployment.account",
      "suggestion": "Contact your account manager to enable access"
    }
  ]
}