activate_signal

activate_signal is the AdCP task for pushing audience segments to DSPs and sales agents. Supports async activation, deactivation for data governance, and returns platform-specific activation keys.

Task: Activate a signal for use on a specific platform/account.

Response Time: Minutes to days (asynchronous with potential human-in-the-loop)

Request Schema: https://adcontextprotocol.org/schemas/v3/signals/activate-signal-request.json Response Schema: https://adcontextprotocol.org/schemas/v3/signals/activate-signal-response.json

The activate_signal task handles the entire activation lifecycle, including:

• Initiating the activation request
• Monitoring activation progress
• Returning the final deployment status

Request Parameters

Parameter	Type	Required	Description
idempotency_key	string	Yes	Client-generated unique key for this request. Prevents duplicate activations on retries. MUST be unique per (seller, request) pair. Min 16 chars. See Idempotency for normative semantics.
signal_agent_segment_id	string	Yes	Opaque signal handle from get_signals for the signal to activate
action	string	No	"activate" (default) or "deactivate". Deactivating removes segments from downstream platforms for data governance compliance (GDPR, CCPA).
destinations	Destination[]	Yes	Target destination(s) for activation (see Destination Object below)
account	AccountRef	No	Account for this activation. Associates with a commercial relationship established via sync_accounts.
pricing_option_id	string	Yes (if signal has pricing options)	The pricing option selected from pricing_options in the get_signals response. Records the buyer’s pricing commitment at activation time. Pass this same value in subsequent report_usage calls.

Destination Object

Each deployment target uses a type field to discriminate between platform-based and agent-based deployments:

Parameter	Type	Required	Description
type	string	Yes	Discriminator: “platform” for DSPs, “agent” for sales agents
platform	string	Conditional*	Platform identifier (e.g., ‘the-trade-desk’, ‘amazon-dsp’). Required when type=“platform”
agent_url	string (URI)	Conditional*	URL identifying the sales agent. Required when type=“agent”
account	string	No	Account identifier on the platform or agent

*platform is required when type="platform", agent_url is required when type="agent".

Activation Keys: If the authenticated caller has access to any of the deployment targets in the request, the signal agent will include activation_key in the response for those deployments.

Permission Model: The signal agent determines key inclusion based on the caller’s authentication and authorization. For example:

• A sales agent receives keys for deployments matching its agent_url
• A buyer with credentials for multiple DSP platforms receives keys for all those deployments
• Access is determined by the signal agent’s permission system, not by flags in the request

Response Structure

All AdCP responses include:

• message: Human-readable summary of the activation status
• context_id: Session continuity identifier for tracking progress
• data: Task-specific payload (see Response Data below)

The response structure is identical across protocols, with only the transport wrapper differing:

• MCP: Returns complete response as flat JSON
• A2A: Returns as artifacts with message in text part, data in data part

For asynchronous operations like activation, both protocols support:

• Status tracking: Check completion status via task_id
• Progress updates: Real-time updates on activation progress

Response Data

{
  "deployments": [
    {
      "type": "platform",
      "platform": "string",
      "account": "string",
      "activation_key": {
        "type": "segment_id",
        "segment_id": "string"
      },
      "estimated_activation_duration_minutes": "number",
      "deployed_at": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string",
      "field": "string",
      "suggestion": "string",
      "details": {}
    }
  ]
}

Field Descriptions

• deployments: Array of deployment results for each deployment target
  • platform: Platform identifier for DSPs (either platform or agent_url will be present)
  • agent_url: URL identifying the deployment agent (either platform or agent_url will be present)
  • account: Account identifier if applicable
  • activation_key: The key to use for targeting (see Activation Key below). Only present if the authenticated caller has access to this deployment.
  • estimated_activation_duration_minutes: Estimated completion time for async operations
  • deployed_at: ISO 8601 timestamp when activation completed
• errors: Optional array of errors and warnings encountered during activation
  • code: Standardized error code for programmatic handling
  • message: Human-readable error description with context
  • field: Field path associated with the error (optional)
  • suggestion: Suggested fix for the error (optional)
  • details: Additional activation-specific error details (optional)

Activation Key Object

The activation key represents how to use the signal on a deployment target. It can be either a segment ID or a key-value pair:

Segment ID format (typical for DSP platforms):

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

Using Activation Keys

The activation key tells the buyer how to reference the signal on the destination. The execution path depends on the destination type:

Platform destinations — The activation_key contains a segment_id, a platform-native identifier. The signal agent pushed segment data to the DSP; the buyer references this key when configuring campaign targeting on that platform. The buyer is responsible for ensuring the activation platform matches where it will run campaigns.

Agent destinations — The activation_key confirms the signal is live on the sales agent. The SA records the activation internally and can apply signal-based targeting when fulfilling media buys through create_media_buy. When the seller exposes selectable signals through inline Product.signal_targeting_options or through get_signals for wholesale products that omit inline options, the buyer selects those signals in packages[].targeting_overlay.signal_targeting_groups, carrying the selected signal_ref, pricing_option_id when required, and any separate seller execution handle required by the product option or signal result. The buyer does not need to know which DSP the SA uses — downstream platform coordination is the SA’s responsibility.

Choosing a destination type: Use type: "platform" when buying directly on a DSP. Use type: "agent" when buying through a Sales Agent — the SA coordinates its own DSP targeting as an implementation detail.

Protocol-Specific Examples

The AdCP payload is identical across protocols. Only the request/response wrapper differs.

MCP Request - Sales Agent Activation

{
  "tool": "activate_signal",
  "arguments": {
    "signal_agent_segment_id": "luxury_auto_intenders",
    "pricing_option_id": "po_cpm_usd",
    "destinations": [{
      "type": "agent",
      "agent_url": "https://wonderstruck.salesagents.com"
    }]
  }
}

MCP Response - Synchronous (Key-Value)

Immediate response with activation key:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "completed",
  "message": "Signal successfully activated on Wonderstruck sales agent",
  "context_id": "ctx-signals-123",
  "deployments": [{
    "type": "agent",
    "agent_url": "https://wonderstruck.salesagents.com",
    "is_live": true,
    "activation_key": {
      "type": "key_value",
      "key": "audience_segment",
      "value": "luxury_auto_intenders_v2"
    },
    "deployed_at": "2025-01-15T14:30:00Z"
  }]
}

MCP Request - DSP Platform Activation

{
  "tool": "activate_signal",
  "arguments": {
    "signal_agent_segment_id": "luxury_auto_intenders",
    "pricing_option_id": "po_cpm_usd",
    "destinations": [{
      "type": "platform",
      "platform": "the-trade-desk",
      "account": "agency-123-ttd"
    }]
  }
}

MCP Response - Asynchronous (Segment ID)

Initial response:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "completed",
  "message": "Initiating activation of 'Luxury Auto Intenders' on The Trade Desk",
  "context_id": "ctx-signals-123",
  "deployments": [{
    "type": "platform",
    "platform": "the-trade-desk",
    "account": "agency-123-ttd",
    "is_live": false,
    "estimated_activation_duration_minutes": 30
  }]
}

After polling for completion:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "completed",
  "message": "Signal successfully activated on The Trade Desk",
  "context_id": "ctx-signals-123",
  "deployments": [{
    "type": "platform",
    "platform": "the-trade-desk",
    "account": "agency-123-ttd",
    "is_live": true,
    "activation_key": {
      "type": "segment_id",
      "segment_id": "ttd_agency123_lux_auto"
    },
    "deployed_at": "2025-01-15T14:30:00Z"
  }]
}

A2A Request

Natural Language Invocation

await a2a.send({
  message: {
    parts: [{
      kind: "text",
      text: "Please activate the luxury_auto_intenders signal on The Trade Desk for account agency-123-ttd."
    }]
  }
});

Explicit Skill Invocation

await a2a.send({
  message: {
    parts: [{
      kind: "data",
      data: {
        skill: "activate_signal",
        parameters: {
          signal_agent_segment_id: "luxury_auto_intenders",
          pricing_option_id: "po_cpm_usd",
          destinations: [{
            type: "platform",
            platform: "the-trade-desk",
            account: "agency-123-ttd"
          }]
        }
      }
    }]
  }
});

A2A Response (with streaming)

Initial response:

{
  "taskId": "task-signal-001",
  "status": { "state": "working" }
}

Then via Server-Sent Events:

data: {"message": "Validating signal access permissions..."}
data: {"message": "Configuring deployment on The Trade Desk..."}
data: {"message": "Finalizing activation..."}
data: {"status": {"state": "completed"}, "artifacts": [{
  "artifactId": "artifact-signal-activation-abc123",
  "name": "signal_activation_result",
  "parts": [
    {"kind": "text", "text": "Signal successfully activated on The Trade Desk"},
    {"kind": "data", "data": {
      "context_id": "ctx-signals-123",
      "deployments": [{
        "type": "platform",
        "platform": "the-trade-desk",
        "account": "agency-123-ttd",
        "activation_key": {
          "type": "segment_id",
          "segment_id": "ttd_agency123_lux_auto"
        },
        "deployed_at": "2025-01-15T14:30:00Z"
      }]
    }}
  ]
}]}

Protocol Transport

• MCP: Returns task_id for polling-based asynchronous operation tracking or webhook-based push notifications
• A2A: Uses Server-Sent Events for real-time progress updates and completion
• Data Consistency: Both protocols contain identical AdCP data structures and version information

Webhook Support

For long-running activations (when initial response is submitted), configure a webhook to receive the complete response when activation completes:

const response = await session.call('activate_signal',
  {
    signal_agent_segment_id: "luxury_auto_intenders",
    pricing_option_id: "po_cpm_usd",
    destinations: [{
      type: "platform",
      platform: "the-trade-desk",
      account: "agency-123-ttd"
    }]
  },
  {
    webhook_url: "https://buyer.com/webhooks/adcp/activate_signal/agent_id/op_id",
    webhook_auth: { type: "bearer", credentials: "secret-token" }
  }
);

When activation completes, you receive the full activate_signal response:

POST /webhooks/adcp/activate_signal/agent_id/op_id HTTP/1.1
Content-Type: application/json
Authorization: Bearer secret-token

{
  "deployments": [{
    "type": "platform",
    "platform": "the-trade-desk",
    "account": "agency-123-ttd",
    "activation_key": {
      "type": "segment_id",
      "segment_id": "ttd_agency123_lux_auto"
    },
    "deployed_at": "2025-01-15T14:30:00Z"
  }]
}

See Webhooks for complete details on webhook configuration and reliability.

Scenarios

Async Activation - Initial Response (Pending)

Message: “I’ve initiated activation of ‘Luxury Automotive Context’ on PubMatic for account brand-456-pm. This typically takes about 60 minutes. I’ll monitor the progress and notify you when it’s ready to use.”

Complete Response:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "completed",
  "message": "I've initiated activation of 'Luxury Automotive Context' on PubMatic for account brand-456-pm. This typically takes about 60 minutes. I'll monitor the progress and notify you when it's ready to use.",
  "context_id": "ctx-signals-def456",
  "deployments": [{
    "type": "platform",
    "platform": "pubmatic",
    "account": "brand-456-pm",
    "is_live": false,
    "estimated_activation_duration_minutes": 60
  }]
}

Async Activation - Final Response (Deployed)

Message: “Excellent! The ‘Luxury Automotive Context’ signal is now live on PubMatic. You can start using it immediately with the activation key provided. The activation completed faster than expected - just 52 minutes.”

Complete Response:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "completed",
  "message": "Excellent! The 'Luxury Automotive Context' signal is now live on PubMatic. You can start using it immediately with the activation key provided. The activation completed faster than expected - just 52 minutes.",
  "context_id": "ctx-signals-def456",
  "deployments": [{
    "type": "platform",
    "platform": "pubmatic",
    "account": "brand-456-pm",
    "is_live": true,
    "activation_key": {
      "type": "segment_id",
      "segment_id": "pm_brand456_peer39_lux_auto"
    },
    "deployed_at": "2025-01-15T14:30:00Z"
  }]
}

Sync Activation - Sales Agent (Immediate)

Message: “Signal successfully activated on Wonderstruck sales agent. Use the key-value pair in your targeting configuration.”

Complete Response:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "completed",
  "message": "Signal successfully activated on Wonderstruck sales agent. Use the key-value pair in your targeting configuration.",
  "context_id": "ctx-signals-ghi789",
  "deployments": [{
    "type": "agent",
    "agent_url": "https://wonderstruck.salesagents.com",
    "is_live": true,
    "activation_key": {
      "type": "key_value",
      "key": "audience_segment",
      "value": "luxury_auto_context_v2"
    },
    "deployed_at": "2025-01-15T14:31:00Z"
  }]
}

Success with Warnings

Message: “Successfully activated ‘Luxury Automotive Context’ on PubMatic, but noted some configuration issues. The signal is live and ready to use, though performance may be sub-optimal until the account settings are updated.”

Complete Response:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "completed",
  "message": "Successfully activated 'Luxury Automotive Context' on PubMatic, but noted some configuration issues. The signal is live and ready to use, though performance may be sub-optimal until the account settings are updated.",
  "context_id": "ctx-signals-def456",
  "deployments": [{
    "type": "platform",
    "platform": "pubmatic",
    "account": "brand-456-pm",
    "is_live": true,
    "activation_key": {
      "type": "segment_id",
      "segment_id": "pm_brand456_peer39_lux_auto"
    },
    "deployed_at": "2025-01-15T14:30:00Z"
  }]
}

Warnings about suboptimal configuration are conveyed in the message field. The errors array is reserved for actual failures — the activate_signal response uses a strict success/error discriminated union where deployments and errors are mutually exclusive.

Error Response (Failed)

Message: “I couldn’t activate the signal on PubMatic. Your account ‘brand-456-pm’ doesn’t have permission to use Peer39 data. Please contact your PubMatic account manager to enable Peer39 access, then we can try again.”

Complete Response:

{
  "$schema": "/schemas/signals/activate-signal-response.json",
  "status": "failed",
  "message": "I couldn't activate the signal on PubMatic. Your account 'brand-456-pm' doesn't have permission to use Peer39 data. Please contact your PubMatic account manager to enable Peer39 access, then we can try again.",
  "context_id": "ctx-signals-def456",
  "errors": [
    {
      "code": "DEPLOYMENT_UNAUTHORIZED",
      "message": "Account brand-456-pm not authorized for Peer39 data on PubMatic",
      "field": "deployment.account",
      "suggestion": "Contact your PubMatic account manager to enable Peer39 data access for your account",
      "details": {
        "account_id": "brand-456-pm",
        "deployment_url": "https://pubmatic.com",
        "data_provider": "peer39",
        "required_permission": "third_party_data_access"
      }
    }
  ]
}

Error Codes

Activation Errors

• REFERENCE_NOT_FOUND: Referenced signal_agent_segment_id doesn’t exist or is not accessible to the calling account (error.field identifies the failing parameter)
• ACTIVATION_FAILED: Could not activate signal for unspecified reasons
• ALREADY_ACTIVATED: Signal already active on the specified platform/account
• DEPLOYMENT_UNAUTHORIZED: Can’t deploy to platform/account due to permissions
• INVALID_PRICING_MODEL: Requested pricing model not available for this signal

Configuration Warnings

• SUBOPTIMAL_CONFIGURATION: Signal activated but account settings may impact performance
• SLOW_ACTIVATION: Activation taking longer than expected but still in progress
• FREQUENCY_CAP_RESTRICTIVE: Signal activated but account frequency caps may reduce performance

Error Handling Philosophy

Status vs Errors

• Task Status: Indicates overall activation outcome (deployed, failed, etc.)
• Errors Array: Contains specific issues, warnings, and remediation steps
• Partial Success: Signal can be deployed while still having warnings in errors array

Error Types

• Fatal Errors: Prevent activation (status = failed)
• Warnings: Signal activates successfully but with caveats (status = deployed + errors)
• Configuration Issues: Non-blocking problems that affect performance

Usage Notes

1. Account-Specific: Include the account parameter for account-specific activations
2. Platform-Wide: Omit the account parameter for platform-wide activations
3. Async Operation: This is a long-running task that provides status updates
4. Monitoring: Use task ID to monitor progress via polling or SSE
5. Idempotent: Safe to retry if activation fails

Implementation Guide

Generating Activation Messages

The message field should provide clear status updates and actionable information:

def generate_activation_message(status, signal_info, request):
    if status == "pending":
        return f"I've initiated activation of '{signal_info.name}' on {request.platform} for account {request.account}. This typically takes about {signal_info.estimated_duration} minutes. I'll monitor the progress and notify you when it's ready to use."
    
    elif status == "processing":
        progress_details = get_progress_details()
        time_remaining = calculate_time_remaining()
        return f"Good progress on the activation. {progress_details}. About {time_remaining} minutes remaining."
    
    elif status == "deployed":
        actual_duration = calculate_actual_duration()
        timing_note = "faster than expected" if actual_duration < signal_info.estimated_duration else "as expected"
        return f"Excellent! The '{signal_info.name}' signal is now live on {request.platform}. You can start using it immediately in your campaigns with the ID '{signal_info.platform_id}'. The activation completed {timing_note} - just {actual_duration} minutes."
    
    elif status == "failed":
        error_explanation = explain_error_in_context(error_code)
        next_steps = get_remediation_steps(error_code)
        return f"I couldn't activate the signal on {request.platform}. {error_explanation}. {next_steps}"