> ## Documentation Index > Fetch the complete documentation index at: https://agenticadvertisingorg-feature-feedback.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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`](https://adcontextprotocol.org/schemas/v3/signals/activate-signal-request.json) **Response Schema**: [`https://adcontextprotocol.org/schemas/v3/signals/activate-signal-response.json`](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](/docs/building/implementation/security#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](/docs/building/integration/accounts-and-agents#account-references) | 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`](/docs/signals/tasks/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 ```json theme={null} { "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):** ```json theme={null} { "type": "segment_id", "segment_id": "ttd_segment_12345" } ``` **Key-Value format (typical for sales agents):** ```json theme={null} { "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 ```json theme={null} { "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: ```json theme={null} { "$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 ```json theme={null} { "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: ```json theme={null} { "$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: ```json theme={null} { "$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 ```javascript theme={null} 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 ```javascript theme={null} 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: ```json theme={null} { "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: ```javascript theme={null} 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: ```http theme={null} 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](/docs/building/implementation/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**: ```json theme={null} { "$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**: ```json theme={null} { "$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**: ```json theme={null} { "$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**: ```json theme={null} { "$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**: ```json theme={null} { "$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: ```python theme={null} 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}" ```