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

# Storyboards 対 scenarios — どれがどれか

> AdCP の 3 つのものが「scenarios」という言葉を共有し、それらは同じではない。区別する方法。

AdCP エージェントを *どう* テストするかを理解しようとしているなら、このエコシステムの 3 つのものが重なる語彙を共有します。それらは同じではありません。それらを混同すると誤った結論を生みます — 実際にはギャップでないものがプロトコルギャップとしてレポートされる類を含みます。

## TL;DR

|                                        | What it is                                                                       | Where it lives                                                                           | Normative? |
| -------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- |
| **Storyboards**                        | ワークフローをエンドツーエンドで定義する YAML ファイル + すべてのワイヤー形状アサーション。**適合性仕様。**                     | `/compliance/{version}/universal/*.yaml`、`protocols/*/*.yaml`、`specialisms/*/index.yaml` | ✅ Yes      |
| **`comply_test_controller` scenarios** | ストーリーボードが決定的な状態を駆動できるよう、セラーが公開するプロトコルレベルのツール操作（`force_*`、`simulate_*`、`seed_*`）。 | セラーの `comply_test_controller` MCP ツールの `scenario` パラメーター。                                | ✅ Yes      |
| **`@adcp/sdk/testing/scenarios/*.ts`** | ストーリーボード駆動の `comply()` に先行するレガシー TypeScript テストランナー。                             | `node_modules/@adcp/sdk/dist/lib/testing/scenarios/*.js`                                 | ❌ **No**   |

`node_modules/@adcp/sdk/dist/lib/testing/scenarios/media-buy.js` のファイルを読んで AdCP が何を要求するかを理解しようとしている場合 — **止まってください**。それは仕様ではありません。代わりに [ストーリーボード](/docs/building/verification/conformance) を読んでください。

## Storyboards（規範的）

ストーリーボードは適合性仕様です。それぞれが定義します:

* ワークフロー（例: *sales-guaranteed proposal/refine/finalize ライフサイクル*）
* バイヤーエージェントが行う正確なツール呼び出し
* セラーのレスポンスが満たさなければならないすべてのワイヤー形状アサーション
* ランナーが決定的な状態をシードするのに使う `comply_test_controller` 操作

[`conformance.mdx`](/docs/building/verification/conformance) はこれらを *「真実」* と呼び、それを意味します。これらの YAML ファイルは **AgenticAdvertising.org Verified (Spec)** の基礎です。AgenticAdvertising.org は、そのコンプライアンスハートビートが該当するストーリーボードを実行しすべてのアサーションが通過するときその修飾子を発行します。

ストーリーボードは次で見られます:

* `/compliance/{version}/universal/*.yaml` — すべての AdCP エージェントが通過しなければならない
* `/compliance/{version}/protocols/{protocol}/index.yaml` — プロトコルを主張する者
* `/compliance/{version}/specialisms/{id}/index.yaml` — オプトインクレーム

`npx @adcp/sdk@latest storyboard run <id>` 経由で、または [Addie](https://agenticadvertising.org) を通じてインタラクティブに実行します。

### ソース権威とロールアウト

ストーリーボードの作られた真実の源泉は、`adcontextprotocol/adcp` リポジトリの `static/compliance/source/` です。`scripts/build-compliance.cjs` は開発中に `dist/compliance/latest/` を構築し、リリース時に `dist/compliance/{version}/` をスタンプし、`index.json` やレガシー `domains/` エイリアスのような生成された配布アーティファクトのみを追加します。SDK は、ランナーがオフラインで動作しバージョンピン留めされたままになるようスナップショットをバンドルしてもよいが、そのスナップショットは配布コピーで権威ではありません。

現在の移行中、`@adcp/sdk` はデフォルトで依然としてバンドルされたキャッシュをロードします。仕様リポジトリ CI は、プルリクエストが同じステップでランタイム権威を切り替えずに候補ソースに対してグレードされるよう、training-agent ストーリーボードを実行する前に `static/compliance/source/` をそのキャッシュにオーバーレイします。SDK リリース作業は、バンドルされたキャッシュが出荷を主張する仕様バンドルに一致することを別途証明すべきです。

破壊的または実質的により厳格なストーリーボード変更は、この順序でロールアウトしなければなりません:

```text theme={null}
spec storyboard change -> reference implementations update -> @adcp/sdk runner release -> downstream consumers update
```

その順序は、リポジトリ所有のリファレンス実装がそれらを通過できるタグ付けされた実装を持つ前に新しいランナーがより厳格なシナリオを期待するリリースデッドロックを防ぎます。

## `comply_test_controller` scenarios（規範的 — だが異なる）

「scenario」という言葉は、決定的テストをサポートするためにセラーが公開する `comply_test_controller` MCP ツールにも現れます。ストーリーボードは、実時間が経過するのを待たずにセラー状態を駆動するため、`scenario: <name>` でこのツールを呼びます: 例えば保留中の非同期メディアバイを終える `force_task_completion`、インプレッションを注入する `simulate_delivery`、フィクスチャをインストールする `seed_product`。

これらは **プロトコル操作** で、テストランナーではありません。[comply\_test\_controller](/docs/building/by-layer/L3/comply-test-controller) で文書化されています。セラーはテスト可能であるためそれらを実装しなければならず（MUST）、ストーリーボードは決定的なままであるためそれらを使わなければなりません（MUST）。

したがって「セラーがそのシナリオをサポートしない」と聞くとき、通常は「セラーの `comply_test_controller` がまだ `force_X` を公開していない」を意味します。「どのストーリーボードも X をテストしない」ではありません。

## `@adcp/sdk/testing/scenarios/*.ts`（非規範的レガシー）

SDK は `testing/scenarios/` の下に TypeScript ファイル — `media-buy.ts`、`signals.ts`、`creative.ts`、その他十数個の兄弟 — を出荷します。これらはストーリーボード駆動の `comply()` エンジンに先行します。それらは:

* **適合性仕様ではない。** AdCP が何を要求するかを学ぶためにそれらを読むと誤った答えを生みます。
* **ストーリーボードとロックステップで保守されていない。** シナリオファイルは、ストーリーボード同等物がとうに訂正したパラメーターをハードコードしているかも。*例: `scenarios/media-buy.ts` は 4 つの呼び出しサイトで `buying_mode: 'brief'` をハードコードします。`sales-guaranteed` の YAML ストーリーボードは `proposal_finalize` ストーリーボード経由で `buying_mode: 'refine'` + `action: 'finalize'` を実行します。両方とも有効な `buying_mode` 値です。シナリオファイルはライフサイクルをカバーしていないだけです。*
* **呼び出し可能だが、異なる目的で。** SDK の内部スモークテスト、下流ツールの統合テストフィクスチャ、一部のレガシーパスは依然としてこれらを使います。それらは AgenticAdvertising.org Verified (Spec) が対して実行するものではありません。

AdCP を理解するために `testing/scenarios/*.ts` を grep している自分に気づいたら、間違った角を曲がりました。正しいパス:

1. 宣言した専門分野に一致するストーリーボードを見つける: `npx @adcp/sdk@latest storyboard list`
2. YAML を読む: `npx @adcp/sdk@latest storyboard show <id>`
3. 実行する: `npx @adcp/sdk@latest storyboard run <id> --agent-url <url>`

## 3 行デコーダー

| 次を見たら…                                                      | …見ているものは         | 仕様として信頼？                                           |
| ----------------------------------------------------------- | ---------------- | -------------------------------------------------- |
| `/compliance/{version}/...` の下の `.yaml`                     | ストーリーボード         | ✅ Yes                                              |
| `scenario` パラメーターを伴う `comply_test_controller` に応答するセラー      | プロトコルレベルのテスト制御操作 | ✅ Yes（コントラクトは規範的。セラーは `UNKNOWN_SCENARIO` で拒否してもよい） |
| `@adcp/sdk/dist/lib/testing/scenarios/` の下の `.ts` または `.js` | レガシー SDK テストランナー | ❌ No                                               |

## クロスリポジトリ

SDK 自体の曖昧性解消作業 — レガシーシナリオを `@deprecated` とマーク、ストーリーボード CLI 動詞をミラー、またはエクスポートを完全に削除 — は [`adcp-client`](https://github.com/adcontextprotocol/adcp-client) にあります。`testing/scenarios/*` が public-but-deprecated のままか internal-only になるかの決定は [#4035](https://github.com/adcontextprotocol/adcp/issues/4035) で追跡されます。

今のところ: AdCP エージェントをテストしたいなら、答えはストーリーボードです。「scenario」と名付けられた他の 2 つのものには場所がありますが、それではありません。