activate_signal - AdCP - Ad Context Protocol

タスク: 特定のプラットフォーム/アカウントでシグナルを有効化します。 応答時間: 数分～数日（人手を伴う非同期処理の可能性あり） リクエストスキーマ: https://adcontextprotocol.org/schemas/v3/signals/activate-signal-request.json レスポンススキーマ: https://adcontextprotocol.org/schemas/v3/signals/activate-signal-response.json activate_signal は次を含む有効化ライフサイクル全体を扱います。

有効化リクエストの開始
進行状況の監視
最終的なデプロイステータスの返却

リクエストパラメーター

Parameter	Type	Required	Description
`idempotency_key`	string	Yes	このリクエストのクライアント生成一意キー。リトライ時の重複有効化を防ぐ。(seller, request) ペアごとに一意でなければならない。最小 16 文字。規範的セマンティクスは Idempotency を参照。
`signal_agent_segment_id`	string	Yes	有効化するシグナルの `get_signals` からの不透明なシグナルハンドル
`action`	string	No	`"activate"`（デフォルト）または `"deactivate"`。デアクティベートはデータガバナンスコンプライアンス（GDPR、CCPA）のためダウンストリームプラットフォームからセグメントを削除します。
`destinations`	Destination[]	Yes	有効化のターゲットデスティネーション（下記 Destination Object を参照）
`account`	AccountRef	No	この有効化のアカウント。`sync_accounts` で確立された商業関係に関連付けます。
`pricing_option_id`	string	Yes（シグナルに料金オプションがある場合）	`get_signals` レスポンスの `pricing_options` から選択した料金オプション。有効化時のバイヤーの価格コミットメントを記録します。後続の `report_usage` 呼び出しでこの同じ値を渡します。
`governance_context`	string	Conditional	`check_governance` がこの有効化に返す不透明な承認コンテキスト。有効化アカウントに登録されたガバナンスエージェントがある場合に必須。

Governance

シグナル有効化は、選択したシグナルがアクティベーション、利用、CPM 料金を運ぶとき、支出コミットイベントです。ガバナンス対象のアカウントでは、バイヤー側オーケストレーターは activate_signal の前に、purchase_type: "signal_activation" と、total_budget や budget のような支出基準を含む正規化された有効化ペイロードで check_governance を呼ばなければなりません（MUST）。 check_governance が有効化を承認したら、返された governance_context を activate_signal に渡します。アカウントに sync_governance で登録されたガバナンスエージェントがあり、リクエストが有効な governance_context を省略する場合、シグナルエージェントは PERMISSION_DENIED でリクエストを拒否しなければなりません（MUST）。check_governance が有効化を拒否した場合、バイヤーは activate_signal を呼んではなりません（MUST NOT）。

Destination Object

各デプロイ先は type フィールドでプラットフォームベースかエージェントベースかを区別します。

Parameter	Type	Required	Description
`type`	string	Yes	識別子。DSP なら “platform”、セールスエージェントなら “agent”
`platform`	string	Conditional*	プラットフォーム ID（例: ‘the-trade-desk’, ‘amazon-dsp’）。type=“platform” の場合必須
`agent_url`	string (URI)	Conditional*	セールスエージェントを識別する URL。type=“agent” の場合必須
`account`	string	No	プラットフォーム/エージェント上のアカウント ID

*platform は type=“platform” の場合必須、agent_url は type=“agent” の場合必須。 Activation Keys: 認証済みの呼び出し元がリクエスト中のいずれかのデプロイ先にアクセス権を持つ場合、シグナルエージェントはレスポンスにそのデプロイメント用の activation_key を含めます。 Permission Model: キーの付与はリクエストのフラグではなく、シグナルエージェント側の認証・認可に基づきます。

セールスエージェントは自分の agent_url に一致するデプロイメントのキーを受け取ります
複数 DSP への認証情報を持つバイヤーは、それらすべてのキーを受け取ります
アクセス可否はシグナルエージェントの権限モデルで決定されます

レスポンス構造

すべての AdCP レスポンスは次を含みます。

message: 有効化ステータスの概要
context_id: 進行状況追跡用のセッション ID
data: タスク固有のペイロード（下記 Response Data 参照）

レスポンス構造はプロトコル間で同一で、トランスポートのみ異なります。

MCP: 平坦な JSON を返却
A2A: アーティファクトで返却（text パートに message、data パートにデータ）

有効化のような非同期処理では、両プロトコルとも次をサポートします。

ステータス追跡: task_id で完了状況を確認
進行更新: 有効化進捗のリアルタイム更新

レスポンスデータ

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

フィールド説明

deployments: 各デプロイ先の結果
- platform: DSP のプラットフォーム ID（platform か agent_url のいずれかが入る）
- agent_url: デプロイメントエージェントの URL（platform か agent_url のいずれかが入る）
- account: 必要に応じたアカウント ID
- activation_key: ターゲティングに使用するキー（下記参照）。認証済みの呼び出し元がそのデプロイにアクセスできる場合にのみ含まれます。
- estimated_activation_duration_minutes: 非同期処理の所要時間目安
- deployed_at: 有効化完了時刻（ISO 8601）
errors: 有効化中のエラーや警告
- code: プログラムで扱いやすいエラーコード
- message: 文脈を含む説明
- field: エラーに関連するフィールド（任意）
- suggestion: 解決策の提案（任意）
- details: 有効化固有の追加情報（任意）

Activation Key Object

デプロイ先でのシグナル利用方法を示します。セグメント ID かキー/バリューのいずれかです。 セグメント ID 形式（DSP で一般的）:

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

キー/バリュー形式（セールスエージェントで一般的）:

{
  "type": "key_value",
  "key": "audience_segment",
  "value": "luxury_auto_intenders"
}

アクティベーションキーの使用

アクティベーションキーは、デスティネーションでシグナルをどう参照するかをバイヤーに伝えます。実行パスはデスティネーションタイプによります: プラットフォームデスティネーション — activation_key はプラットフォームネイティブの識別子 segment_id を含みます。シグナルエージェントはセグメントデータを DSP にプッシュしました。バイヤーはそのプラットフォームでキャンペーンターゲティングを設定する際にこのキーを参照します。バイヤーは、有効化プラットフォームがキャンペーンを実行する場所と一致することを保証する責任があります。 エージェントデスティネーション — activation_key はシグナルがセールスエージェント上でライブであることを確認します。SA は有効化を内部で記録し、create_media_buy を通じてメディアバイを履行するときにシグナルベースのターゲティングを適用できます。セラーがインライン Product.signal_targeting_options を通じて、またはインラインオプションを省略するホールセールプロダクトについて get_signals を通じて選択可能なシグナルを公開する場合、バイヤーはそれらのシグナルを packages[].targeting_overlay.signal_targeting_groups で選択し、選択した signal_ref、必要な場合は pricing_option_id、プロダクトオプションまたはシグナル結果が要求する別個のセラー実行ハンドルを運びます。バイヤーは SA がどの DSP を使うかを知る必要はありません — ダウンストリームのプラットフォーム連携は SA の責任です。 デスティネーションタイプの選択: DSP で直接購入するときは type: "platform" を使います。セールスエージェント経由で購入するときは type: "agent" を使います — SA は独自の DSP ターゲティングを実装の詳細として調整します。

プロトコル別の例

AdCP のペイロードはプロトコル間で同一で、ラッパーのみ異なります。

MCP リクエスト - セールスエージェントへの有効化

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

MCP レスポンス - 同期（キー/バリュー）

即時レスポンスとアクティベーションキー:

{
  "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 リクエスト - DSP 有効化

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

MCP レスポンス - 非同期（セグメント ID）

初期レスポンス:

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

完了後のポーリング:

{
  "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 リクエスト

自然言語での呼び出し

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

スキルを明示して呼び出す

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

A2A レスポンス（ストリーミング）

初期レスポンス:

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

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

プロトコルトランスポート

MCP: ポーリングや webhook による非同期トラッキング用の task_id を返す
A2A: SSE で進捗と完了をリアルタイム送信
データ整合性: どちらも同一の AdCP データ構造とバージョン情報を含みます

Webhook サポート

初期レスポンスが submitted となる長時間処理では、webhook を設定して完了時のレスポンスを受け取ります。

const response = await session.call('activate_signal',
  {
    signal_agent_segment_id: "luxury_auto_intenders",
    deployments: [{
      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" }
  }
);

有効化が完了すると、activate_signal のフルレスポンスが届きます。

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

詳細な webhook 設定や信頼性については Webhooks を参照してください。

シナリオ

非同期有効化 - 初期レスポンス（保留）

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:

{
  "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",
    "estimated_activation_duration_minutes": 60
  }]
}

非同期有効化 - 最終レスポンス（デプロイ済み）

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:

{
  "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",
    "activation_key": {
      "type": "segment_id",
      "segment_id": "pm_brand456_peer39_lux_auto"
    },
    "deployed_at": "2025-01-15T14:30:00Z"
  }]
}

同期有効化 - セールスエージェント（即時）

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

{
  "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",
    "activation_key": {
      "type": "key_value",
      "key": "audience_segment",
      "value": "luxury_auto_context_v2"
    },
    "deployed_at": "2025-01-15T14:31:00Z"
  }]
}

成功（警告付き）

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:

{
  "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",
    "activation_key": {
      "type": "segment_id",
      "segment_id": "pm_brand456_peer39_lux_auto"
    },
    "deployed_at": "2025-01-15T14:30:00Z"
  }],
  "errors": [
    {
      "code": "SUBOPTIMAL_CONFIGURATION",
      "message": "Account frequency cap settings may limit signal reach",
      "field": "account.frequency_settings",
      "suggestion": "Contact your PubMatic account manager to review frequency cap settings for optimal performance"
    }
  ]
}

エラーレスポンス（失敗）

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:

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

エラーコード

Activation Errors

REFERENCE_NOT_FOUND: 参照された signal_agent_segment_id が存在しないか、呼び出しアカウントからアクセスできません（error.field が失敗パラメーターを識別します）
ACTIVATION_FAILED: 何らかの理由で有効化できません
ALREADY_ACTIVATED: 指定プラットフォーム/アカウントですでに有効化済み
DEPLOYMENT_UNAUTHORIZED: 権限不足でデプロイ不可
INVALID_PRICING_MODEL: リクエストした課金モデルが利用できません

Configuration Warnings

SUBOPTIMAL_CONFIGURATION: 有効化したが設定により性能に影響の可能性
SLOW_ACTIVATION: 想定より時間がかかっているが進行中
FREQUENCY_CAP_RESTRICTIVE: 有効化済みだがフリークエンシーキャップが厳しい可能性

エラーハンドリングの考え方

ステータスとエラーの区別

タスクステータス: 有効化の全体結果（deployed、failed など）
errors 配列: 具体的な問題や警告、対応策
部分成功: errors に警告があっても deployed となる場合があります

エラーの種類

致命的エラー: 有効化を阻害（status = failed）
警告: 有効化は成功するが注意点あり（status = deployed + errors）
設定上の問題: パフォーマンスに影響する非致命的な課題

利用上の注意

アカウント指定: アカウント単位で有効化する場合は account を含めます
プラットフォーム全体: プラットフォーム全体で有効化する場合は account を省略
非同期処理: ステータス更新がある長時間タスク
監視: ポーリングまたは SSE で task_id を監視
冗長性: 失敗時はリトライ可能（冪等）

実装ガイド

有効化メッセージの生成

message フィールドは明確なステータスとアクションを伝えるべきです。

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

​リクエストパラメーター

​Governance

​Destination Object

​レスポンス構造

​レスポンスデータ

​フィールド説明

​Activation Key Object

​アクティベーションキーの使用

​プロトコル別の例

​MCP リクエスト - セールスエージェントへの有効化

​MCP レスポンス - 同期（キー/バリュー）

​MCP リクエスト - DSP 有効化

​MCP レスポンス - 非同期（セグメント ID）

​A2A リクエスト

​自然言語での呼び出し

​スキルを明示して呼び出す

​A2A レスポンス（ストリーミング）

​プロトコルトランスポート

​Webhook サポート

​シナリオ

​非同期有効化 - 初期レスポンス（保留）

​非同期有効化 - 最終レスポンス（デプロイ済み）

​同期有効化 - セールスエージェント（即時）

​成功（警告付き）

​エラーレスポンス（失敗）

​エラーコード

​Activation Errors

​Configuration Warnings

​エラーハンドリングの考え方

​ステータスとエラーの区別

​エラーの種類

​利用上の注意

​実装ガイド

​有効化メッセージの生成