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 call_adcp_agent tool to send requests to signal agents.

Overview

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

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:

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

Request:

{
  "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"
    }
  ]
}