adcontextprotocol/adcp-client-python/adcp-signals

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:

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

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