> ## 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.

# ストーリーボードを使ってエージェントを検証する

> AdCP エージェントをストーリーボードでテストする — CLI から、または Addie を通じて。

エージェントが実行されたら、本番稼働前に検証してください。ストーリーボードは特定のワークフローをエンドツーエンドで行使します — メディアバイ作成、クリエイティブ同期、シグナルディスカバリー。各ストーリーボードは、バイヤーエージェントが行う正確なツール呼び出しシーケンスを定義し、すべてのレスポンス形状を検証します。

ストーリーボードはコマンドラインから、また [Addie](https://agenticadvertising.org) を通じてインタラクティブに利用できます。それらはスキーマと並んで `/compliance/{version}/` でも公開され、`/protocol/{version}.tgz` のバージョンごとのプロトコル tarball にバンドルされています — オフラインで取得する方法については [スキーマと SDK](/docs/building/by-layer/L0/schemas#one-shot-protocol-bundle) を参照してください。

<Note>
  `@adcp/sdk` パッケージは、`testing/scenarios/*`（例: `media-buy.ts`、`signals.ts`）下のレガシー TypeScript テストランナーもエクスポートします。これらは `comply()` に先行し、適合性仕様では **ありません**。AdCP が何を要求するかを学ぶためにそれらのファイルを grep している自分に気づいたら、どの表面が規範的かについて [Storyboards 対 scenarios](/docs/building/verification/storyboards-vs-scenarios) を参照してください。
</Note>

<Info>
  **アップストリームプラットフォームをラップ**（DSP、SSP、リテールデータウェアハウス、クリエイティブサーバー、シグナルマーケットプレイス）していますか? ストーリーボードは AdCP ワイヤーコントラクトをチェックします。ワイヤーの背後のアダプターが実際にアップストリームと統合するか、合成データで形状有効なレスポンスを返すかを判別できません。[モックアップストリームフィクスチャでアダプターエージェントを検証する](/docs/building/verification/validate-with-mock-fixtures) を参照してください — 公開されたモックフィクスチャとトラフィックカウンターが、任意の言語のアダプターにファサード耐性のあるコンプライアンスを与えます。
</Info>

## Storyboard taxonomy

ストーリーボードは 3 つの層に編成され、エージェントは実際にサポートするものだけを宣言します:

| Layer          | Path                                          | 通過しなければならない者                                                                                                                                     |
| -------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Universal**  | `/compliance/{version}/universal/`            | すべての AdCP エージェント（ケイパビリティディスカバリー、エラー処理、スキーマ検証）                                                                                                    |
| **Protocol**   | `/compliance/{version}/protocols/{protocol}/` | プロトコルを主張する任意のエージェント（`media-buy`、`creative`、`signals`、`governance`、`brand`）                                                                       |
| **Specialism** | `/compliance/{version}/specialisms/{id}/`     | オプトインクレーム（例: `sales-guaranteed`、`sales-broadcast-tv`、`creative-generative`） — [コンプライアンスカタログ](/docs/building/verification/compliance-catalog) を参照 |

`get_adcp_capabilities` で `supported_protocols` と `specialisms` を宣言してください — ランナーは一致するストーリーボードを自動的に選びます。完全な分類については [コンプライアンスカタログ](/docs/building/verification/compliance-catalog) を参照してください。

## セットアップ

名前でエージェントを参照できるよう、名前付きエイリアスとして保存します:

```bash theme={null}
npx @adcp/sdk@latest --save-auth my-agent http://localhost:3001/mcp
```

これはエイリアスを `~/.adcp/config.json` に保存します。これは一度だけ行えば十分です。組み込みエイリアス `test-mcp` と `test-a2a` は公開テストエージェントを指します — セットアップ不要です。

<Tip>
  エイリアスの代わりに URL を直接渡すこともできます: `npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller`
</Tip>

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

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

```bash theme={null}
npx @adcp/sdk@latest storyboard list
```

各ストーリーボードは特定のエージェントタイプをターゲットします。[エージェントをビルドする](/docs/building/by-layer/L4/build-an-agent) ページはスキルを一致するストーリーボードにマップします。

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

```bash theme={null}
npx @adcp/sdk@latest storyboard show media_buy_seller
```

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

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

```bash theme={null}
npx @adcp/sdk@latest storyboard run my-agent media_buy_seller
```

出力は各ステップを pass/fail で表示します:

```
media_buy_seller (9 steps)
  ✓ get_adcp_capabilities
  ✓ sync_accounts
  ✓ get_products
  ✓ create_media_buy
  ✓ list_creative_formats
  ✓ sync_creatives
  ✓ list_creatives
  ✓ get_media_buy_delivery
  ✓ provide_performance_feedback
  9/9 passed
```

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

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

ステップが失敗する場合、それを個別に実行します:

```bash theme={null}
npx @adcp/sdk@latest storyboard step my-agent media_buy_seller create_media_buy --json --debug
```

早期ステップからの状態（アカウント ID、製品 ID）を提供するには `--context` を渡します:

```bash theme={null}
npx @adcp/sdk@latest storyboard step my-agent media_buy_seller get_products \
  --context '{"account_id":"acct-123"}' --json
```

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

すべてをテストするにはストーリーボード ID なしで実行します。CLI は `tools/list` 経由でエージェントのツールを発見し、一致するストーリーボードを自動的に選びます:

```bash theme={null}
npx @adcp/sdk@latest storyboard run my-agent
```

構造化出力には `--json` を追加します。

ストーリーボードランナーは、エージェントがオプションの [コンプライアンステストコントローラー](/docs/building/by-layer/L3/comply-test-controller) を実装するかどうかに応じて 2 つのモードで動作します:

| Mode              | When         | テストするもの                        |
| ----------------- | ------------ | ------------------------------ |
| **Observational** | テストコントローラーなし | レスポンススキーマとバイヤー開始フロー            |
| **Deterministic** | テストコントローラー存在 | 完全なライフサイクルステートマシン、エラーコード、操作ゲート |

### `partial` を読む

`partial` はカバレッジ結果であり、自動的に失敗ではありません。ランナーは、実行されたアサーションが失敗しなかったにもかかわらず 1 つ以上の選択されたシナリオがグレードできなかったときにそれを使います。最も一般的な原因は意図的です: 本番エンドポイントは `comply_test_controller` を公開してはならない（MUST NOT）ため、コントローラーがシードまたは強制するフェーズは `missing_test_controller` でスキップします。

`steps_not_selected` を `steps_skipped` と別に読んでください。未選択のシナリオは、あなたが要求したスイートまたは実行モードの外側にありました。スキップされたシナリオは選択されたスイートの内側にありましたが、適用性ゲート、欠けているテスト表面、欠けているツール、前提条件のためランナーがそれらを実行できませんでした。

結果が何を意味するかを決めるには、サマリーカウンターとスキップ理由を使ってください:

| Summary                                                 | 解釈                                            |
| ------------------------------------------------------- | --------------------------------------------- |
| `0 failed`、`steps_not_selected > 0`、`steps_skipped = 0` | 選択された実行モードに期待される。ライブ専用プローブを除外するサンドボックス専用テストなど |
| `0 failed`、ケイパビリティゲートの `not_applicable` スキップのみ          | セラーが宣言したケイパビリティスコープのクリーンな通過                   |
| `0 failed`、`missing_test_controller` スキップ               | バイヤー可視パスは通過したが、決定的ライフサイクルカバレッジはグレードされなかった     |
| 宣言されたプロトコルまたは専門分野の `missing_tool` スキップ                  | セラーが過剰主張したか、必須ツールの公開を忘れた                      |
| 任意の failed ステップ                                         | 修正されるまで宣言されたスコープに非適合                          |

本番パスのサンドボックス検証では、`84 passed, 0 failed, 0 skipped, 80 not selected` のような結果はクリーンなサンドボックス専用選択結果です: 除外されたプローブはその実行の一部ではありませんでした。`84 passed, 0 failed, 80 skipped` のような結果は、何かを意味する前にスキップ内訳が必要です。オプションケイパビリティが主張されなかったためのスキップは選択スコープスキップです。`missing_test_controller` のスキップは決定的カバレッジギャップです: スイートは公開サンドボックスパスをテストし、コントローラーがシードするライフサイクルシナリオがグレードされなかったとレポートしました。それらを完全にグリーンにするには、コントローラーを公開する開発/ステージングエンドポイントに対して実行するか、必須状態を事前シードしランナーにシード状態カバレッジをアサートするよう伝えるか、スキップされたカバレッジリストを明示的な制限として受け入れ公開してください。

## Addie を通じて検証する

[Addie](https://agenticadvertising.org) は、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` でサンドボックスサポートを宣言すべきです:

```json theme={null}
{
  "account": {
    "sandbox": true
  }
}
```

リクエストがサンドボックスアカウントを参照するとき、エージェントは本番状態を永続化したり実世界の副作用を引き起こしてはなりません（MUST NOT） — 実オーダーなし、実課金なし、実広告プラットフォーム API 呼び出しなし。シミュレートされたデータで現実的なレスポンス形状を返し、成功レスポンスに `sandbox: true` を含めてください。

完全な実装詳細と 2 つのアカウントモデルパス（暗黙対明示）については [サンドボックスモード](/docs/media-buy/advanced-topics/sandbox) を参照してください。

## Verifying cross-instance state

プロトコルは、`(brand, account)` スコープの状態が [エージェントプロセスインスタンス間で生き残る](/docs/protocol/architecture#state-persistence-and-horizontal-scaling) こと — あるレプリカで作成されたメディアバイが他の任意のレプリカから読めること — を要求します。単一インスタンスのストーリーボード成功はそれ自体でその不変条件を証明しません。デプロイに合った検証アプローチを選んでください。

**アーキテクチャで検証する。** 共有データストアを持つマネージドサーバーレスプラットフォーム — Lambda + DynamoDB、Cloudflare Workers + D1、Cloud Run + Firestore、Vercel + Neon — で実行する場合、不変条件は構造上成り立ちます。デプロイされたエンドポイントに対して通過するストーリーボードで十分です。発見可能なようストレージパターンを文書化してください。

**マルチインスタンステストで検証する。** 長期実行プロセス（コンテナ、VM、ロードバランサーの背後の古典的アプリサーバー）をデプロイする場合、ラウンドロビンルーティングの背後に 2 つ以上のレプリカを置き、共有エンドポイントに対してストーリーボードを実行します:

```bash theme={null}
npx @adcp/sdk@latest --save-auth my-agent https://my-agent.example/mcp
npx @adcp/sdk@latest storyboard run my-agent
```

コンプライアンスランナーは、`stateful: true` とマークされたステップを含む任意のストーリーボード — インプロセス状態を捕捉する可能性が最も高い write→read シーケンス — についてレプリカ間でリクエストをローテートします。ステートレスプローブ（ケイパビリティディスカバリー、認証拒否、スキーマ検証）は影響を受けません。

典型的な失敗は次のようになります:

```
✗ get_media_buy  MEDIA_BUY_NOT_FOUND
  create_media_buy on replica A returned media_buy_id=mb_abc123 (status: active)
  get_media_buy on replica B returned MEDIA_BUY_NOT_FOUND for the same id
  → Brand-scoped state is not shared across replicas.
```

**独自のテストで検証する。** 実データストアに対するプロパティベーステスト、レプリカ間のカオス障害注入、またはインスタンス間で書き込みと読み取りを相関させる本番可観測性はすべて有効です。プロトコルは方法論ではなく不変条件を気にします。

インサーションオーダー承認レコード、ガバナンストークン、シグナルアクティベーション、スポンサードインテリジェンスセッションはすべて同じルールの下にあります。後の呼び出しが読み返せる任意の書き込み状態は、プロセスごとの `Map` やモジュールレベル変数ではなく、共有ストアに存在しなければなりません。

## Preparing to test uniform error responses

[統一レスポンス MUST](/docs/building/by-layer/L3/error-handling#standard-error-codes) は、「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 つのテナントが共有する他のもの — 監査シャード、リソースタイプでキーされたレート制限バケット、キャッシュタグ — は不変条件が捕捉するよう設計された潜在的サイドチャネルです。本番で共有するものだけを共有してください。

### ランナー呼び出し

```bash theme={null}
# クロステナント（完全な MUST）
npx @adcp/sdk@latest fuzz my-agent \
  --auth-token $TENANT_A_TOKEN \
  --auth-token-cross-tenant $TENANT_B_TOKEN

# ベースライン（部分カバレッジ）
npx @adcp/sdk@latest fuzz my-agent --auth-token $TOKEN
```

トークンは `ADCP_AUTH_TOKEN` と `ADCP_AUTH_TOKEN_CROSS_TENANT` 経由でも供給できます。完全なフラグリスト、ヘッダー allowlist、現在プローブされるツールのリストについては [`@adcp/sdk` 統一エラーレスポンス不変条件ガイド](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/VALIDATE-YOUR-AGENT.md#uniform-error-response-invariant-paired-probe) を参照してください。

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

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

## build-validate-fix ループ

典型的な開発ワークフロー:

1. **Build** — コーディングエージェントを [スキルファイル](/docs/building/by-layer/L4/build-an-agent) に向けてエージェントを生成
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 なし）を実行

<Info>
  [Practitioner 認定](https://agenticadvertising.org/certification) では、ストーリーボード検証の通過が集大成です — それはエージェントが選択したロールトラックの完全なプロトコルワークフローを処理することを証明します。
</Info>

## CLI リファレンス

| Command                                                    | Description                     |
| ---------------------------------------------------------- | ------------------------------- |
| `npx @adcp/sdk@latest storyboard list`                     | 利用可能なすべてのストーリーボードをリスト           |
| `npx @adcp/sdk@latest storyboard show <id>`                | ストーリーボード構造をプレビュー                |
| `npx @adcp/sdk@latest storyboard run <agent> [id]`         | 1 つのストーリーボードを実行、ID がなければ一致するすべて |
| `npx @adcp/sdk@latest storyboard step <agent> <id> <step>` | 単一ステップを実行                       |
| `npx @adcp/sdk@latest <agent> [tool] [payload]`            | 任意のツールを直接呼び出す                   |
| `npx @adcp/sdk@latest --save-auth <alias> <url>`           | エージェントエイリアスを保存                  |
| `npx @adcp/sdk@latest --list-agents`                       | 保存されたエイリアスをリスト                  |

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

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

* **[ストーリーボードのトラブルシューティング](/docs/building/operating/storyboard-troubleshooting)** — 根本原因と修正にマップされたエラーパターン（欠けているフィクスチャ、署名チャレンジ、エンベロープドリフト、コンテキストエコー、ケイパビリティ不一致）
* **[既知の仕様曖昧性](/docs/building/cross-cutting/known-ambiguities)** — 適合性に影響するオープンな仕様ギャップ、回避策と issue リンク付き

## 次は何か

* **[コンプライアンステストコントローラー](/docs/building/by-layer/L3/comply-test-controller)** — 完全なライフサイクルカバレッジのため決定的テストを実装
* **[タスクライフサイクル](/docs/building/by-layer/L3/task-lifecycle)** — ステータス値、遷移、ポーリング
* **[エラー処理](/docs/building/by-layer/L3/error-handling)** — エラーカテゴリー、コード、リカバリー