Skip to main content
エージェントが実行されたら、本番稼働前に検証してください。ストーリーボードは特定のワークフローをエンドツーエンドで行使します — メディアバイ作成、クリエイティブ同期、シグナルディスカバリー。各ストーリーボードは、バイヤーエージェントが行う正確なツール呼び出しシーケンスを定義し、すべてのレスポンス形状を検証します。 ストーリーボードはコマンドラインから、また Addie を通じてインタラクティブに利用できます。それらはスキーマと並んで /compliance/{version}/ でも公開され、/protocol/{version}.tgz のバージョンごとのプロトコル tarball にバンドルされています — オフラインで取得する方法については スキーマと SDK を参照してください。
@adcp/sdk パッケージは、testing/scenarios/*(例: media-buy.tssignals.ts)下のレガシー TypeScript テストランナーもエクスポートします。これらは comply() に先行し、適合性仕様では ありません。AdCP が何を要求するかを学ぶためにそれらのファイルを grep している自分に気づいたら、どの表面が規範的かについて Storyboards 対 scenarios を参照してください。
アップストリームプラットフォームをラップ(DSP、SSP、リテールデータウェアハウス、クリエイティブサーバー、シグナルマーケットプレイス)していますか? ストーリーボードは AdCP ワイヤーコントラクトをチェックします。ワイヤーの背後のアダプターが実際にアップストリームと統合するか、合成データで形状有効なレスポンスを返すかを判別できません。モックアップストリームフィクスチャでアダプターエージェントを検証する を参照してください — 公開されたモックフィクスチャとトラフィックカウンターが、任意の言語のアダプターにファサード耐性のあるコンプライアンスを与えます。

Storyboard taxonomy

ストーリーボードは 3 つの層に編成され、エージェントは実際にサポートするものだけを宣言します: get_adcp_capabilitiessupported_protocolsspecialisms を宣言してください — ランナーは一致するストーリーボードを自動的に選びます。完全な分類については コンプライアンスカタログ を参照してください。

セットアップ

名前でエージェントを参照できるよう、名前付きエイリアスとして保存します:
これはエイリアスを ~/.adcp/config.json に保存します。これは一度だけ行えば十分です。組み込みエイリアス test-mcptest-a2a は公開テストエージェントを指します — セットアップ不要です。
エイリアスの代わりに URL を直接渡すこともできます: npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller

ストーリーボードを実行する

1. 利用可能なストーリーボードをリストする

各ストーリーボードは特定のエージェントタイプをターゲットします。エージェントをビルドする ページはスキルを一致するストーリーボードにマップします。

2. ストーリーボードが何をテストするかをプレビューする

これは何も実行せずにフェーズ、ステップ、検証を表示します。

3. ストーリーボードを実行する

出力は各ステップを pass/fail で表示します:
機械可読な結果には --json を渡します。各ステップの完全なリクエスト/レスポンスペイロードを見るには --debug を渡します。

4. 失敗するステップをデバッグする

ステップが失敗する場合、それを個別に実行します:
早期ステップからの状態(アカウント ID、製品 ID)を提供するには --context を渡します:

5. すべてのストーリーボードを実行する

すべてをテストするにはストーリーボード ID なしで実行します。CLI は tools/list 経由でエージェントのツールを発見し、一致するストーリーボードを自動的に選びます:
構造化出力には --json を追加します。 ストーリーボードランナーは、エージェントがオプションの コンプライアンステストコントローラー を実装するかどうかに応じて 2 つのモードで動作します:

partial を読む

partial はカバレッジ結果であり、自動的に失敗ではありません。ランナーは、実行されたアサーションが失敗しなかったにもかかわらず 1 つ以上の選択されたシナリオがグレードできなかったときにそれを使います。最も一般的な原因は意図的です: 本番エンドポイントは comply_test_controller を公開してはならない(MUST NOT)ため、コントローラーがシードまたは強制するフェーズは missing_test_controller でスキップします。 steps_not_selectedsteps_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)とレート比較を表示するため、実行がどこで破綻するかを正確に見られます。

推奨テストシーケンス

  1. 接続性 — エージェントはオンラインか?
  2. ストーリーボード — プロトコルコンプライアンスを通過するか?
  3. RFP テスト — 実際のバイヤー需要に応答できるか?
  4. IO 実行 — 実際のディールをクローズできるか?
各ステップが信頼を構築します。ストーリーボードはプロトコルコンプライアンスを証明します。RFP と IO テストはビジネス準備性を証明します。

サンドボックスモード

すべてのストーリーボード実行はデフォルトでサンドボックスモードを使います。ストーリーボードランナーはすべてのアカウント参照に sandbox: true を設定するため、エージェントは実プラットフォーム呼び出しや支出なしにリクエストを処理します。 エージェントは get_adcp_capabilities でサンドボックスサポートを宣言すべきです:
リクエストがサンドボックスアカウントを参照するとき、エージェントは本番状態を永続化したり実世界の副作用を引き起こしてはなりません(MUST NOT) — 実オーダーなし、実課金なし、実広告プラットフォーム API 呼び出しなし。シミュレートされたデータで現実的なレスポンス形状を返し、成功レスポンスに 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)。
2 つのテナントが共有する他のもの — 監査シャード、リソースタイプでキーされたレート制限バケット、キャッシュタグ — は不変条件が捕捉するよう設計された潜在的サイドチャネルです。本番で共有するものだけを共有してください。

ランナー呼び出し

トークンは ADCP_AUTH_TOKENADCP_AUTH_TOKEN_CROSS_TENANT 経由でも供給できます。完全なフラグリスト、ヘッダー allowlist、現在プローブされるツールのリストについては @adcp/sdk 統一エラーレスポンス不変条件ガイド を参照してください。

1 テナントだけでテストする

2 つ目のテナントをまだプロビジョンしていない場合、とにかくベースラインを実行してください — 依然として意味のあるクラスのリークを捕捉し、CLI は実行をベースライン専用としてフラグするためオペレーターはカバレッジが部分的であることを見られます。単一テナントの fuzz を適合性シグナルではなく事前チェックとして扱ってください: クリーンなベースライン実行は MUST が成り立つことを証明しません。統一レスポンス適合性を主張する前にクロステナントレッグを追加してください。

build-validate-fix ループ

典型的な開発ワークフロー:
  1. Build — コーディングエージェントを スキルファイル に向けてエージェントを生成
  2. Run — エージェントをローカルで起動(npx tsx agent.ts
  3. Validate — 一致するストーリーボードを実行(npx @adcp/sdk@latest storyboard run my-agent media_buy_seller
  4. Fix — 任意の失敗に対処(欠けているフィールド、誤ったステータス値、無効な遷移)
  5. Repeat — すべてのステップが通過するまでストーリーボードを再実行
  6. Full check — 本番稼働前に完全な評価のため npx @adcp/sdk@latest storyboard run my-agent(ストーリーボード ID なし)を実行
Practitioner 認定 では、ストーリーボード検証の通過が集大成です — それはエージェントが選択したロールトラックの完全なプロトコルワークフローを処理することを証明します。

CLI リファレンス

すべてのコマンドは --json--debug--auth TOKEN--protocol mcp|a2a をサポートします。

ストーリーボードが失敗するとき

次は何か