Signals Quick Reference

Compact reference for executing AdCP Signals Protocol tasks. Use this when interacting with signal agents via call_adcp_agent.

Use the call_adcp_agent tool to execute these tasks against any AdCP signal agent.

Task Overview

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.

{
  "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:

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

{
  "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:

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

Sales Agents:

{
  "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):

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

Key-Value format (typical for sales agents):

{
  "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:

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