Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt

Use this file to discover all available pages before exploring further.

If you’re trying to figure out how to test an AdCP agent, three things in this ecosystem share overlapping vocabulary. They are not the same. Confusing them produces wrong conclusions — including the kind that get reported as protocol gaps that aren’t actually gaps.

​
TL;DR

What it isWhere it livesNormative?
StoryboardsYAML files defining a workflow end-to-end + every wire-shape assertion. The conformance specification./compliance/{version}/universal/*.yaml, protocols/*/*.yaml, specialisms/*/index.yaml✅ Yes
comply_test_controller scenariosProtocol-level tool operations a seller exposes (force_*, simulate_*, seed_*) so storyboards can drive deterministic state.The scenario parameter of the seller’s comply_test_controller MCP tool.✅ Yes
@adcp/sdk/testing/scenarios/*.tsLegacy TypeScript test runners predating storyboard-driven comply().node_modules/@adcp/sdk/dist/lib/testing/scenarios/*.js❌ No
If you’re reading a file at node_modules/@adcp/sdk/dist/lib/testing/scenarios/media-buy.js and trying to figure out what AdCP requires — stop. That’s not the spec. Read the storyboards instead.

​
Storyboards (normative)

Storyboards are the conformance specification. Each one defines:
  • A workflow (e.g. sales-guaranteed proposal/refine/finalize lifecycle)
  • The exact tool calls a buyer agent makes
  • Every wire-shape assertion the seller’s responses must satisfy
  • The comply_test_controller operations the runner uses to seed deterministic state
conformance.mdx calls these “the truth” — and means it. The AdCP Verified (Spec) badge is issued by running these YAML files through comply() and observing every assertion pass. You’ll see storyboards at:
  • /compliance/{version}/universal/*.yaml — every AdCP agent must pass
  • /compliance/{version}/protocols/{protocol}/index.yaml — anyone claiming the protocol
  • /compliance/{version}/specialisms/{id}/index.yaml — opt-in claims
Run them via npx @adcp/sdk storyboard run <id> or interactively through Addie.

​
comply_test_controller scenarios (normative — but different)

The word “scenario” also appears in the comply_test_controller MCP tool that sellers expose to support deterministic testing. Storyboards call this tool with scenario: <name> to drive seller state without waiting for real time to pass: e.g. force_task_completion to finish a pending async media buy, simulate_delivery to inject impressions, seed_product to install a fixture. These are protocol operations, not test runners. They’re documented at comply_test_controller. Sellers MUST implement them to be testable; the storyboards MUST use them to stay deterministic. So when you hear “the seller doesn’t support that scenario,” it usually means: “the seller’s comply_test_controller doesn’t expose force_X yet.” Not “no storyboard tests X.”

​
@adcp/sdk/testing/scenarios/*.ts (NON-normative legacy)

The SDK ships TypeScript files under testing/scenarios/ — media-buy.ts, signals.ts, creative.ts, and a dozen siblings. These predate the storyboard-driven comply() engine. They are:
  • Not the conformance spec. Reading them to learn what AdCP requires will produce wrong answers.
  • Not maintained in lockstep with storyboards. A scenario file may hard-code parameters that the storyboard equivalent has long since corrected. Example: scenarios/media-buy.ts hard-codes buying_mode: 'brief' at four call sites; the YAML storyboard for sales-guaranteed exercises buying_mode: 'refine' + action: 'finalize' via the proposal_finalize storyboard. Both are valid buying_mode values; the scenario file just doesn’t cover the lifecycle.
  • Callable, but for different purposes. Internal smoke tests in the SDK, integration-test fixtures for downstream tooling, and some legacy paths still use these. They are not what AAO Verified (Spec) runs against.
If you find yourself grepping testing/scenarios/*.ts to understand AdCP, you’ve taken a wrong turn. The right path:
  1. Find the storyboard that matches your declared specialism: npx @adcp/sdk storyboard list
  2. Read the YAML: npx @adcp/sdk storyboard show <id>
  3. Run it: npx @adcp/sdk storyboard run <id> --agent-url <url>

​
Three-line decoder

If you see……you’re looking atTrust as spec?
A .yaml under /compliance/{version}/...A storyboard✅ Yes
A seller responding to comply_test_controller with a scenario parameterA protocol-level test-control operation✅ Yes (the contract is normative; the seller MAY refuse with UNKNOWN_SCENARIO)
A .ts or .js under @adcp/sdk/dist/lib/testing/scenarios/A legacy SDK test runner❌ No

​
Cross-repo

The disambiguation work in the SDK itself — marking the legacy scenarios as @deprecated, mirroring the storyboard CLI verbs, or removing the export entirely — lives in adcp-client. The decision on whether testing/scenarios/* stays public-but-deprecated or becomes internal-only is tracked in #4035. For now: if you want to test an AdCP agent, the answer is storyboards. The other two things named “scenario” have their place, but they aren’t it.