/compliance/{version}/ でも公開され、/protocol/{version}.tgz のバージョンごとのプロトコル tarball にバンドルされています — オフラインで取得する方法については スキーマと SDK を参照してください。
@adcp/sdk パッケージは、testing/scenarios/*(例: media-buy.ts、signals.ts)下のレガシー TypeScript テストランナーもエクスポートします。これらは comply() に先行し、適合性仕様では ありません。AdCP が何を要求するかを学ぶためにそれらのファイルを grep している自分に気づいたら、どの表面が規範的かについて Storyboards 対 scenarios を参照してください。アップストリームプラットフォームをラップ(DSP、SSP、リテールデータウェアハウス、クリエイティブサーバー、シグナルマーケットプレイス)していますか? ストーリーボードは AdCP ワイヤーコントラクトをチェックします。ワイヤーの背後のアダプターが実際にアップストリームと統合するか、合成データで形状有効なレスポンスを返すかを判別できません。モックアップストリームフィクスチャでアダプターエージェントを検証する を参照してください — 公開されたモックフィクスチャとトラフィックカウンターが、任意の言語のアダプターにファサード耐性のあるコンプライアンスを与えます。
Storyboard taxonomy
ストーリーボードは 3 つの層に編成され、エージェントは実際にサポートするものだけを宣言します:get_adcp_capabilities で supported_protocols と specialisms を宣言してください — ランナーは一致するストーリーボードを自動的に選びます。完全な分類については コンプライアンスカタログ を参照してください。
セットアップ
名前でエージェントを参照できるよう、名前付きエイリアスとして保存します:~/.adcp/config.json に保存します。これは一度だけ行えば十分です。組み込みエイリアス test-mcp と test-a2a は公開テストエージェントを指します — セットアップ不要です。
ストーリーボードを実行する
1. 利用可能なストーリーボードをリストする
2. ストーリーボードが何をテストするかをプレビューする
3. ストーリーボードを実行する
--json を渡します。各ステップの完全なリクエスト/レスポンスペイロードを見るには --debug を渡します。
4. 失敗するステップをデバッグする
ステップが失敗する場合、それを個別に実行します:--context を渡します:
5. すべてのストーリーボードを実行する
すべてをテストするにはストーリーボード ID なしで実行します。CLI はtools/list 経由でエージェントのツールを発見し、一致するストーリーボードを自動的に選びます:
--json を追加します。
ストーリーボードランナーは、エージェントがオプションの コンプライアンステストコントローラー を実装するかどうかに応じて 2 つのモードで動作します:
partial を読む
partial はカバレッジ結果であり、自動的に失敗ではありません。ランナーは、実行されたアサーションが失敗しなかったにもかかわらず 1 つ以上の選択されたシナリオがグレードできなかったときにそれを使います。最も一般的な原因は意図的です: 本番エンドポイントは comply_test_controller を公開してはならない(MUST NOT)ため、コントローラーがシードまたは強制するフェーズは missing_test_controller でスキップします。
steps_not_selected を steps_skipped と別に読んでください。未選択のシナリオは、あなたが要求したスイートまたは実行モードの外側にありました。スキップされたシナリオは選択されたスイートの内側にありましたが、適用性ゲート、欠けているテスト表面、欠けているツール、前提条件のためランナーがそれらを実行できませんでした。
結果が何を意味するかを決めるには、サマリーカウンターとスキップ理由を使ってください:
本番パスのサンドボックス検証では、
84 passed, 0 failed, 0 skipped, 80 not selected のような結果はクリーンなサンドボックス専用選択結果です: 除外されたプローブはその実行の一部ではありませんでした。84 passed, 0 failed, 80 skipped のような結果は、何かを意味する前にスキップ内訳が必要です。オプションケイパビリティが主張されなかったためのスキップは選択スコープスキップです。missing_test_controller のスキップは決定的カバレッジギャップです: スイートは公開サンドボックスパスをテストし、コントローラーがシードするライフサイクルシナリオがグレードされなかったとレポートしました。それらを完全にグリーンにするには、コントローラーを公開する開発/ステージングエンドポイントに対して実行するか、必須状態を事前シードしランナーにシード状態カバレッジをアサートするよう伝えるか、スキップされたカバレッジリストを明示的な制限として受け入れ公開してください。
Addie を通じて検証する
Addie は、CLI セットアップなしにインタラクティブなテストを提供します。任意の会話にエージェント URL を貼り付けて始めてください。接続性チェック
Addie にエージェントをチェックするよう頼んでください。オンラインであることを検証し、アドバタイズされたツールをリストし、トランスポートプロトコル(MCP または A2A)を確認します。これは任意のテストを実行する前にエージェントが到達可能であることを確認する最速の方法です。ストーリーボードコーチング
Addie は CLI と同じストーリーボードを実行しますが、各ステップをインタラクティブに案内します。ステップが失敗すると、何が間違ったかを説明し、期待対実際のレスポンスを表示し、具体的なコード変更を提案します。これは構築中に反復する最速の方法です。RFP テスト
実際の RFP またはキャンペーンブリーフを Addie と共有してください。それを解析し、バイヤーの実際の要件でエージェントのget_products を呼び、結果をあなたのセールスチームが通常提案するものと比較します。これは、エージェントが実際のバイヤー需要を処理できるか — あなた自身の在庫記述から派生した合成ブリーフだけでなく — をテストします。
IO 実行テスト
インサーションオーダーを Addie と共有してください。ラインアイテムを抽出し、エージェントの製品カタログに対して照合し、create_media_buy がディールを実行できるかをテストします。出力はライン単位の照合品質(exact、close、weak、unmapped)とレート比較を表示するため、実行がどこで破綻するかを正確に見られます。
推奨テストシーケンス
- 接続性 — エージェントはオンラインか?
- ストーリーボード — プロトコルコンプライアンスを通過するか?
- RFP テスト — 実際のバイヤー需要に応答できるか?
- IO 実行 — 実際のディールをクローズできるか?
サンドボックスモード
すべてのストーリーボード実行はデフォルトでサンドボックスモードを使います。ストーリーボードランナーはすべてのアカウント参照にsandbox: true を設定するため、エージェントは実プラットフォーム呼び出しや支出なしにリクエストを処理します。
エージェントは get_adcp_capabilities でサンドボックスサポートを宣言すべきです:
sandbox: true を含めてください。
完全な実装詳細と 2 つのアカウントモデルパス(暗黙対明示)については サンドボックスモード を参照してください。
Verifying cross-instance state
プロトコルは、(brand, account) スコープの状態が エージェントプロセスインスタンス間で生き残る こと — あるレプリカで作成されたメディアバイが他の任意のレプリカから読めること — を要求します。単一インスタンスのストーリーボード成功はそれ自体でその不変条件を証明しません。デプロイに合った検証アプローチを選んでください。
アーキテクチャで検証する。 共有データストアを持つマネージドサーバーレスプラットフォーム — Lambda + DynamoDB、Cloudflare Workers + D1、Cloud Run + Firestore、Vercel + Neon — で実行する場合、不変条件は構造上成り立ちます。デプロイされたエンドポイントに対して通過するストーリーボードで十分です。発見可能なようストレージパターンを文書化してください。
マルチインスタンステストで検証する。 長期実行プロセス(コンテナ、VM、ロードバランサーの背後の古典的アプリサーバー)をデプロイする場合、ラウンドロビンルーティングの背後に 2 つ以上のレプリカを置き、共有エンドポイントに対してストーリーボードを実行します:
stateful: true とマークされたステップを含む任意のストーリーボード — インプロセス状態を捕捉する可能性が最も高い write→read シーケンス — についてレプリカ間でリクエストをローテートします。ステートレスプローブ(ケイパビリティディスカバリー、認証拒否、スキーマ検証)は影響を受けません。
典型的な失敗は次のようになります:
Map やモジュールレベル変数ではなく、共有ストアに存在しなければなりません。
Preparing to test uniform error responses
統一レスポンス MUST は、「id は存在するが呼び出し元がアクセス権を欠く」と「id が存在しない」について、すべての観測可能チャネル — エラーボディ、トランスポートステータス、ヘッダー、副作用、テレメトリー — 全体でバイト等価なレスポンスを要求します。これを検証するには、ツールごとに 2 つのレスポンスを比較するペア化プローブランナー(adcp fuzz)が必要です。ランナーは 2 つのモードを持ち、強いモードを行使する前にテナントセットアップを計画する必要があります。
ベースラインモード — 単一テナント。 1 つの認証トークン、ツールごとにプローブされる 2 つの新しい UUID。エラーボディの id エコー、allowlist 外のヘッダー分岐、MCP isError / A2A task.status.state 分岐、大まかなレイテンシーデルタを捕捉。どちらのプローブも実リソースに解決しないため、クロステナント存在リークは捕捉できません。
クロステナントモード — 2 テナント。 テナント A がリソース(例: プロパティリスト、コンテンツ標準、メディアバイ、クリエイティブ)をシード。テナント B がシードされた id と新しい UUID に対してプローブ。ベースラインが構築できない (exists, unauthorized) 対 (does not exist) ペアを行使するため、完全な MUST を捕捉します。
両方のモードが仕様 MUST を行使します。クロステナントパスのみが不変条件全体を検証します。
最小テナントセットアップ
エージェントに対して 2 つの分離されたテストアカウントをプロビジョンします:- テナント A — 不変条件がシードするリソース(プロパティリスト、コンテンツ標準、メディアバイ、クリエイティブ)を作成できる。サンドボックスモードアカウントで問題ない。
- テナント B — 共有ディスカバリー表面に対して読み取り専用。プラットフォームがグローバルに可視にするもの(例: 公開された製品カタログ)を超えて A とテナントごとの状態を共有してはならない(MUST NOT)。
ランナー呼び出し
ADCP_AUTH_TOKEN と ADCP_AUTH_TOKEN_CROSS_TENANT 経由でも供給できます。完全なフラグリスト、ヘッダー allowlist、現在プローブされるツールのリストについては @adcp/sdk 統一エラーレスポンス不変条件ガイド を参照してください。
1 テナントだけでテストする
2 つ目のテナントをまだプロビジョンしていない場合、とにかくベースラインを実行してください — 依然として意味のあるクラスのリークを捕捉し、CLI は実行をベースライン専用としてフラグするためオペレーターはカバレッジが部分的であることを見られます。単一テナントの fuzz を適合性シグナルではなく事前チェックとして扱ってください: クリーンなベースライン実行は MUST が成り立つことを証明しません。統一レスポンス適合性を主張する前にクロステナントレッグを追加してください。build-validate-fix ループ
典型的な開発ワークフロー:- Build — コーディングエージェントを スキルファイル に向けてエージェントを生成
- Run — エージェントをローカルで起動(
npx tsx agent.ts) - Validate — 一致するストーリーボードを実行(
npx @adcp/sdk@latest storyboard run my-agent media_buy_seller) - Fix — 任意の失敗に対処(欠けているフィールド、誤ったステータス値、無効な遷移)
- Repeat — すべてのステップが通過するまでストーリーボードを再実行
- Full check — 本番稼働前に完全な評価のため
npx @adcp/sdk@latest storyboard run my-agent(ストーリーボード ID なし)を実行
Practitioner 認定 では、ストーリーボード検証の通過が集大成です — それはエージェントが選択したロールトラックの完全なプロトコルワークフローを処理することを証明します。
CLI リファレンス
すべてのコマンドは
--json、--debug、--auth TOKEN、--protocol mcp|a2a をサポートします。
ストーリーボードが失敗するとき
- ストーリーボードのトラブルシューティング — 根本原因と修正にマップされたエラーパターン(欠けているフィクスチャ、署名チャレンジ、エンベロープドリフト、コンテキストエコー、ケイパビリティ不一致)
- 既知の仕様曖昧性 — 適合性に影響するオープンな仕様ギャップ、回避策と issue リンク付き
次は何か
- コンプライアンステストコントローラー — 完全なライフサイクルカバレッジのため決定的テストを実装
- タスクライフサイクル — ステータス値、遷移、ポーリング
- エラー処理 — エラーカテゴリー、コード、リカバリー