モックアップストリームフィクスチャでアダプターエージェントを検証する

​

4 ステップのレシピ

# 1. あなたの専門分野用のモックアップストリームをブートする
npx @adcp/sdk@latest mock-server sales-social --port 4250 &

# 2. http://localhost:4250 をアップストリームとして使うよう設定した AdCP エージェントを実行
./your-agent.sh        # Python / Go / Rust / TS — 言語非依存

# 3. 該当ストーリーボードに対してエージェントをグレードする
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp sales_social \
  --auth $TOKEN --json > grader.json

# 4. エージェントが実際にアップストリームを呼んだことをアサート
curl -s http://localhost:4250/_debug/traffic
# {"traffic": {"POST /oauth/token": 1, "POST /event/track": 6, ...}}

​

なぜトラフィックカウンターか

• 入力が非仕様分岐に一致しないとき、ハンドラーがアップストリーム呼び出しの前に短絡する（例: sync_audiences の空 members[] → 形状的に有効な空レスポンスを返し、決して POST しない）。
• OAuth クライアントは配線されているがどのハンドラーからも呼ばれない。ツリーシェイキングは void fetchUpstreamToken; リテラルで無効化されている。
• アップストリームの必須フィールドスキーマを満たすため合成プレースホルダーデータが注入され、実データの形状不一致を隠す。

​

利用可能なもの

• アップストリームのドメインエンドポイント — 実プラットフォームの公開コントラクトに一致するよう形作られている。
• GET /_lookup/<resource>?<adcp_field>=<value> — AdCP 側の識別子からアップストリームテナント ID へのランタイム解決。ハーネス規約。
• GET /_debug/traffic — <METHOD> <route-template> でキーされたヒットカウンター、認証なし、ハーネス専用。ハーネス規約。 ストーリーボード実行後に読み、各主要ルートが少なくとも 1 回ヒットしたことをアサートする。

​

CI 統合

jobs:
  validate-adapter:
    runs-on: ubuntu-latest
    services:
      mock-upstream:
        image: node:20
        ports: ['4250:4250']
        # `npx @adcp/sdk@latest mock-server <specialism>` を実行するブートストラップスクリプトを使う。
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/start-agent.sh &              # あなたの言語のエージェント
      - run: ./scripts/wait-for-port.sh 3001
      - run: |
          npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp <storyboard_id> \
            --auth $TOKEN --json > grader.json
      - run: |
          # 期待される各アップストリームルートが少なくとも 1 回ヒットしたことをアサート
          curl -s http://localhost:4250/_debug/traffic | \
            jq -e '.traffic["POST /oauth/token"] >= 1 and .traffic["POST /event/track"] >= 1'

​

反復ループ

• ストーリーボードが passing だが N エンドポイントでトラフィックゲートが失敗 — 典型的なファサード。それらのルートのハンドラーは短絡したか、ストーリーボードの入力によって行使されなかった。
• カスケードスキップを伴うストーリーボード partial — 早期ステップ（get_products、get_signals）が、ランナーが状態を抽出するフィールドを欠いた形状的に有効なレスポンスを返した。下流ステップは unresolved context variables でスキップする。早期ステップのレスポンス形状を修正すればほとんどのカスケードスキップはクリアされる。
• 単一ステップでストーリーボード failing + トラフィックゲートはクリーン — 通常は 1 行の形状バグ（誤ったフィールド名、欠けている必須フィールド、ステータス不一致）。ステップごとの details が JSON ポインターでフィールドを名指す。
• トラフィックゲートが空（どこでも 0 ヒット）+ エージェントが起動しているように見える — エージェントのブートがポートでリッスンした後に回復可能なエラーをスローした。エージェントの stderr を確認する。

​

制限

​

ストーリーボードの制限

• ストーリーボードはペイロードの多様性をアンダーカバーする。 ストーリーボードステップは、実際のアダプターが決して行使されない空入力で形状を通過するかもしれない — 重要なバリアントで。adcontextprotocol/adcp#3785 で追跡。

​

ランナー / ツーリングの注意点

• ストーリーボードは黙ってカスケードスキップする — 早期ステップのレスポンスが形状的に有効だがランナーが状態を抽出するフィールドを欠くとき。表示されるエラーは 下流 ステップにあり、早期ステップではありません — “failed” の前に “skipped” ステップを調査してください。adcontextprotocol/adcp#3796（ランナー側）で追跡。
• モックシードデータがストーリーボードフィクスチャ入力に一致しないかもしれない。 _lookup/<resource> で 404 が見えたら、ストーリーボードのペイロードはモックがシードしない ID を参照しているかもしれません。モックのシードを広げるか、コンプライアンステストコントローラー 経由でランタイムにシナリオ状態をシードしてください。

​

トラフィックゲートの制限

• 必要だが十分ではない。 ハンドラーは合成プレースホルダーデータでアップストリームを呼び、なおヒットカウントアサーションを満たしうる。規制されたチャネル（オーディエンスアップロード、コンバージョントラッキング、署名付きリクエスト）のエージェントについては、本番前に実アップストリームのペイロード検証に対する追加の統合テストが依然として必要です。
• 冪等性リプレイはトラフィックカウンターで行使されない。 idempotency_key を無視しアップストリーム書き込みを二重化するファサードはヒットカウントゲートを通過します。プラットフォームが at-most-once セマンティクスを持つ場合、ストーリーボードの冪等性リプレイシナリオ + 別のカウンターチェック（同じ idempotency_key → 同じヒットカウント）を使ってください。
• アウトバウンド webhook 配信はアップストリームトラフィックカウンターで行使されない。 トラフィックカウンターはエージェントが呼び 込む アップストリーム上に存在します。エージェント → バイヤー webhook の署名/配信は、ストーリーボードランナーの --webhook-receiver フラグで別途グレードされます。webhook を発行するアダプターには両方のゲートが適用されます。

​

次は何か

• エージェントを検証する — より広範なストーリーボードランナー駆動の検証チェックリスト（ファズ、マルチインスタンス、リクエスト署名、webhook 適合性）。
• コンプライアンステストコントローラー — ストーリーボードがモックの提供しないフィクスチャを必要とするとき、ランタイムにシナリオ状態をシードする。
• エージェントをビルドする — AdCP エージェントをビルドするための言語非依存ガイド。
• コンプライアンスカタログ — universal / protocol / specialism ストーリーボードの完全な分類。