> ## Documentation Index > Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # activate_signal **タスク**: 特定のプラットフォーム/アカウントでシグナルを有効化します。 **応答時間**: 数分～数日（人手を伴う非同期処理の可能性あり） **リクエストスキーマ**: [`https://adcontextprotocol.org/schemas/v3/signals/activate-signal-request.json`](https://adcontextprotocol.org/schemas/v3/signals/activate-signal-request.json) **レスポンススキーマ**: [`https://adcontextprotocol.org/schemas/v3/signals/activate-signal-response.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](/docs/building/by-layer/L1/security#idempotency) を参照。 | | `signal_agent_segment_id` | string | Yes | 有効化するシグナルの `get_signals` からの不透明なシグナルハンドル | | `action` | string | No | `"activate"`（デフォルト）または `"deactivate"`。デアクティベートはデータガバナンスコンプライアンス（GDPR、CCPA）のためダウンストリームプラットフォームからセグメントを削除します。 | | `destinations` | Destination\[] | Yes | 有効化のターゲットデスティネーション（下記 Destination Object を参照） | | `account` | [AccountRef](/docs/building/by-layer/L2/accounts-and-agents#account-references) | No | この有効化のアカウント。`sync_accounts` で確立された商業関係に関連付けます。 | | `pricing_option_id` | string | Yes（シグナルに料金オプションがある場合） | [`get_signals`](/docs/signals/tasks/get_signals) レスポンスの `pricing_options` から選択した料金オプション。有効化時のバイヤーの価格コミットメントを記録します。後続の `report_usage` 呼び出しでこの同じ値を渡します。 | | `governance_context` | string | Conditional | [`check_governance`](/docs/governance/campaign/tasks/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 で完了状況を確認 * **進行更新**: 有効化進捗のリアルタイム更新 ## レスポンスデータ ```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": {} } ] } ``` ### フィールド説明 * **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 で一般的）:** ```json theme={null} { "type": "segment_id", "segment_id": "ttd_segment_12345" } ``` **キー/バリュー形式（セールスエージェントで一般的）:** ```json theme={null} { "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 リクエスト - セールスエージェントへの有効化 ```json theme={null} { "tool": "activate_signal", "arguments": { "signal_agent_segment_id": "luxury_auto_intenders", "deployments": [{ "type": "agent", "agent_url": "https://wonderstruck.salesagents.com" }] } } ``` ### MCP レスポンス - 同期（キー/バリュー） 即時レスポンスとアクティベーションキー: ```json theme={null} { "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 有効化 ```json theme={null} { "tool": "activate_signal", "arguments": { "signal_agent_segment_id": "luxury_auto_intenders", "deployments": [{ "type": "platform", "platform": "the-trade-desk", "account": "agency-123-ttd" }] } } ``` ### MCP レスポンス - 非同期（セグメント ID） 初期レスポンス: ```json theme={null} { "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 }] } ``` 完了後のポーリング: ```json theme={null} { "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 リクエスト #### 自然言語での呼び出し ```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." }] } }); ``` #### スキルを明示して呼び出す ```javascript theme={null} 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 レスポンス（ストリーミング） 初期レスポンス: ```json theme={null} { "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 を設定して完了時のレスポンスを受け取ります。 ```javascript theme={null} 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` のフルレスポンスが届きます。 ```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" }] } ``` 詳細な webhook 設定や信頼性については **[Webhooks](/docs/building/by-layer/L3/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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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） * **設定上の問題**: パフォーマンスに影響する非致命的な課題 ## 利用上の注意 1. **アカウント指定**: アカウント単位で有効化する場合は `account` を含めます 2. **プラットフォーム全体**: プラットフォーム全体で有効化する場合は `account` を省略 3. **非同期処理**: ステータス更新がある長時間タスク 4. **監視**: ポーリングまたは SSE で task\_id を監視 5. **冗長性**: 失敗時はリトライ可能（冪等） ## 実装ガイド ### 有効化メッセージの生成 `message` フィールドは明確なステータスとアクションを伝えるべきです。 ```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}" ```