Skip to main content
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. These YAML files are the basis for AgenticAdvertising.org Verified (Spec); AgenticAdvertising.org issues that qualifier when its compliance heartbeat runs the applicable storyboards and every assertion passes. 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@latest storyboard run <id> or interactively through Addie.

​
Source authority and rollout

The authored source of truth for storyboards is static/compliance/source/ in the adcontextprotocol/adcp repo. scripts/build-compliance.cjs builds dist/compliance/latest/ during development and stamps dist/compliance/{version}/ on release, adding only generated distribution artifacts such as index.json and the legacy domains/ alias. SDKs may bundle a snapshot so runners work offline and remain version-pinned, but that snapshot is a distribution copy, not the authority. During the current migration, @adcp/sdk still loads its bundled cache by default. Spec repo CI overlays static/compliance/source/ onto that cache before running the training-agent storyboards so pull requests are graded against the candidate source without switching runtime authority in the same step. SDK release work should separately prove its bundled cache matches the spec bundle it claims to ship. Breaking or materially stricter storyboard changes must roll out in this order: 
spec storyboard change -> reference implementations update -> @adcp/sdk runner release -> downstream consumers update
That order prevents the release deadlock where a new runner expects stricter scenarios before repo-owned reference implementations have a tagged implementation that can pass them.

​
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 AgenticAdvertising.org 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@latest storyboard list
  2. Read the YAML: npx @adcp/sdk@latest storyboard show <id>
  3. Run it: npx @adcp/sdk@latest 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.