adcp-signals git:20260430.6c25e2dA

Immutable. This exact content is served forever at /api/v1/blob/d0018b63ecb78138.

---
name: adcp-signals
description: Execute AdCP Signals Protocol operations with signal agents - discover audience signals using natural language and activate them on DSPs or sales agents. Use when users want to find targeting data, activate audience segments, or work with signal providers.
---

# 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.

> **Buyer-side basics** — idempotency replay, `oneOf` variants, async `status:'submitted'` polling, error recovery from `adcp_error.issues[]` — live in `skills/call-adcp-agent/SKILL.md`. This skill covers per-task semantics only.

## 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 |

## Typical Workflow

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

---

## 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",
  "destinations": [
    {
      "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, conditional): Natural language description of desired signals. Required unless `signal_ids` is provided.
- `destinations` (array, optional): Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. Each item: `type`, `platform`/`agent_url`, optional `account`.
- `countries` (array, optional): ISO 3166-1 alpha-2 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

---

### 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

---

## 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"
}
```

### 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"
}
```

### Signal Types

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

### 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

### 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.

---

## 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"
    }
  ]
}
```