Documentation Index
Fetch the complete documentation index at: https://agenticadvertisingorg-changeset-release-main.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Status: Request for Comments
Last Updated: May 11, 2026
AAO Verified is the public trust mark for AdCP agents. It carries one of two qualifiers in parens — (Spec) or (Sandbox) — and may carry both. The qualifier names which axis of verification an agent has earned.
It is two axes, not two tiers. The qualifiers answer different questions:
- Verified (Spec) — your AdCP protocol implementation matches the spec. Storyboards pass somewhere — could be a test deployment, could be local dev. Wire format, task shape, error semantics, state-machine transitions all check out. Attests wire-format conformance, not production tolerance.
- Verified (Sandbox) — your real production endpoint correctly honors
account.sandbox: true. AAO runs the full storyboard suite against your registered agent_url with sandbox-flagged traffic; your prod stack processes it with schema-valid responses, correct lifecycle transitions, proper error envelopes, and no real-world side effects (no real spend, no real persistence, no real platform calls). Attests the production code path tolerates test traffic correctly.
An agent can earn either axis or both. A pure protocol wrapper around a stub ad server is honestly Verified (Spec) — that’s what test agents and dev environments are. A real production seller whose prod URL handles sandbox traffic across the full storyboard suite earns Verified (Spec + Sandbox), the strongest claim available.
The two axes are orthogonal — neither is a prerequisite for the other. A seller without a separate test deployment (production-only platforms that have no test-mode surface) can earn (Sandbox) directly by exposing their prod URL to AAO’s runner with sandbox flagging — no separate test endpoint needed. Conversely, a test agent that can never serve real impressions earns (Spec) as a complete claim.
The badge surfaces whichever qualifiers are earned.
TL;DR for sellers. Both qualifiers run the same storyboards through the same AAO compliance heartbeat. The difference is where the runner targets and what the seller’s stack does with sandbox-flagged traffic:
- (Spec) runs storyboards against a test deployment / local dev / a sandbox endpoint. The agent’s prod surface is not exercised.
- (Sandbox) runs storyboards against the seller’s registered production
agent_url with account.sandbox: true on every request. The seller’s prod stack MUST honor the flag — return schema-valid responses, transition state correctly, surface errors properly, and have zero real-world side effects (no billing, no persistence beyond the sandbox account, no third-party platform calls).
The seller-side gate is normative: every comply_test_controller request includes account: { sandbox: true }, and the seller MUST verify the targeted account is sandbox by looking up the persisted account record — not by trusting the field. See comply_test_controller for the dev-side affordance; AAO grading itself does not require or use the controller. What each axis certifies
Verified (Spec)
| |
|---|
| Tested against | Any endpoint the agent owner registers — test deployment, local dev, sandbox-only stack. The runner does not distinguish. |
| What it proves | AdCP wire format, task shape, error semantics, state-machine transitions, declared specialisms map to working tools, schema conformance, filter behavior, idempotency semantics — exercised in isolation from real-world production state. |
| How | Storyboards from the Compliance Catalog run against the registered agent URL on AAO’s compliance heartbeat. |
| Cadence | ~1h heartbeat |
| Eligibility | Any agent that passes the storyboards for its declared specialisms + holds an active AAO membership with API-access tier |
| Status | Available now |
Verified (Sandbox)
| |
|---|
| Tested against | Your registered production agent_url, with account.sandbox: true on every request. |
| What it proves | Your production code path correctly honors sandbox flagging — same storyboards as (Spec), but exercised against the real prod stack buyers actually hit. Schema-valid responses, correct lifecycle transitions, proper error envelopes, zero real-world side effects. |
| How | Same storyboard suite as (Spec), driven against the seller’s registered URL with sandbox-flagged traffic. No separate canonical-campaign infrastructure. |
| Cadence | Same ~1h heartbeat as (Spec) |
| Eligibility | Same as (Spec), PLUS the seller’s prod surface accepts account.sandbox: true requests and processes them without persisting real state, calling third-party platforms, or billing |
| Status | Foundation shipping in #4382 (account.sandbox schema gate), #4384 (live-mode denial storyboard). Full grading framework following. |
Verified (Live) framing. The change: instead of attesting “your real-money production code path delivers impressions correctly” (canonical campaigns running through your stack), (Sandbox) attests “your real production code path correctly handles sandbox-flagged traffic across the full storyboard suite.” Both are real-prod-surface claims; the difference is what gets tested. (Sandbox) is universally achievable across specialisms with no new AAO operational infrastructure. See #4379 for the reframe verdict.
Re: comply_test_controller: the controller is a dev/staging-only affordance for adopters’ own integration testing. AAO’s (Sandbox) grading does not require or use it. Sellers MAY implement controller endpoints in their dev environment to support deterministic local testing, but the production stack does not need to expose comply_test_controller to earn (Sandbox). The seller-side sandbox gate is what (Sandbox) attests — schema and lifecycle correctness under flagged traffic, on real prod. How the dev-time test surface itself is stood up — DB-backed seed_* for state-local sellers vs the SDK’s TestControllerBridge for upstream-proxy sellers — is covered in Test surfaces and the storyboard loop. Naming history
Earlier drafts (#3001) proposed “AdCP Conformant” and “AAO Verified” as two distinct mark names — one per axis. This page uses a single brand mark with axis qualifiers in parens instead. Same shape, different naming convention:
| Earlier draft | Current |
|---|
| AdCP Conformant | AAO Verified (Spec) |
| AAO Verified | AAO Verified (Live) |
| AdCP Conformant + AAO Verified | AAO Verified (Spec + Live) |
verification_modes: string[] array in the JWT and registry API, where an agent might have ["spec"] or ["spec", "live"]. One badge URL per agent + role; the qualifier evolves as axes are earned, embedded badges automatically reflect the current state.
The earlier draft’s rejection of “Tier 1 / Tier 2” remains correct: tiering the same word — verified — across two different kinds of claim muddies the message. The two-axis qualifier framing inherits that rejection while keeping the brand word singular.
Coverage gaps are explicit
Under the (Sandbox) framing, every applicable storyboard runs against the seller’s production endpoint with sandbox-flagged traffic. There’s no observability carve-out — universal storyboards (signed_requests, pagination_integrity, etc.) run as part of the standard suite. The (Sandbox) qualifier attests that the seller’s prod stack handles all of them correctly under flagged traffic, not just the ones with a real-money observability path. See #4379 for the framing decision that replaced the earlier (Live) observability model.
Reading a badge
Badges render as a single shields.io-style image with the qualifiers in parens:
| Display | Meaning |
|---|
AAO Verified Sales Agent (Spec) | Storyboards pass for declared media-buy specialisms against a test deployment / dev / sandbox-only endpoint. Wire format and protocol semantics are correct; production-stack sandbox tolerance is not yet attested. Common for test agents and pre-production rollouts. |
AAO Verified Sales Agent (Spec + Sandbox) | Both axes earned. The strongest claim. The agent’s registered production URL handles the full storyboard suite under sandbox-flagged traffic with no real-world side effects. |
AAO Verified Sales Agent (Sandbox) | Storyboards pass against the seller’s registered production endpoint under account.sandbox: true. The seller’s prod stack correctly honors the sandbox gate. Common for production-only sellers without a separate test deployment. |
AAO Verified — Not Verified | No badge issued for this agent + role, or the badge has been revoked. |
How agents earn each axis
// agent declares its claims in get_adcp_capabilities
{
"supported_protocols": ["media_buy", "creative"],
"specialisms": [
"sales-broadcast-tv",
"sales-guaranteed",
"creative-ad-server"
]
}
To earn Verified (Spec):
- Implement AdCP for your declared specialisms.
- Pass the storyboards on your test-mode endpoint. (Run them locally first via
@adcp/sdk/testing to see what’s failing.)
- Hold an active AAO membership at an API-access tier.
The compliance heartbeat picks it up automatically — no manual enrollment needed beyond registering your agent.
To earn Verified (Sandbox):
A seller earns (Sandbox) by:
- Registering their production
agent_url with AAO. This is the same registration that earns (Spec) — no separate “compliance account” or “test deployment” needed.
- Implementing the sandbox-account gate in their production stack: when a request arrives with
account.sandbox: true, the seller verifies the targeted account is a sandbox account in the persisted record (not trusting the field), and processes the request with full schema/lifecycle correctness while producing zero real-world side effects — no real spend, no real ad-server orders, no third-party platform calls, no production persistence beyond the sandbox account’s bounded state.
- Holding an active AAO membership at an API-access tier.
That’s it. The compliance heartbeat runs the same storyboards as (Spec), but targets the registered production URL with account.sandbox: true on every request. Pass → (Sandbox) qualifier issues.
Key requirement: sandbox-account isolation. Sellers MUST persist a clear sandbox/live distinction at the account level. A request asserting sandbox: true against a live account MUST be refused with a structured error — see #4028 and the comply-controller-mode-gate storyboard for the canonical denial check. Cross-mode leakage is the failure mode (Sandbox) attests against.
Decentralized verification
Each badge is backed by a signed JWT (EdDSA / Ed25519). AAO publishes its public key set at /.well-known/jwks.json so any third party can verify a badge’s authenticity without calling AAO’s API.
The token claims:
{
"iss": "https://aao.org",
"sub": "https://your-agent.example.com/mcp",
"aud": "aao-verification",
"jti": "<uuid>",
"iat": 1745510400,
"exp": 1748102400,
"role": "media-buy",
"adcp_version": "3.0",
"verified_specialisms": ["sales-broadcast-tv", "sales-guaranteed"],
"verification_modes": ["spec"],
"protocol_version": "3.0.0"
}
adcp_version is the AdCP release this badge was issued against (MAJOR.MINOR). Pairs with the (agent_url, role, adcp_version) identity used by the badge URL routes. Verifiers MUST check adcp_version against the AdCP version they care about — a 3.0 token presented as proof of 3.1 conformance is not authoritative. The signed claim is shape-validated at signing time (^[1-9][0-9]*\.[0-9]+$); verifiers SHOULD apply the same regex defensively.
verification_modes is the array of axes earned. ["spec"] for test-deployment storyboard pass only; ["spec", "sandbox"] for agents whose production endpoint also passes under sandbox-flagged traffic. protocol_version is the full semver of the spec build the badge was tested against — informational metadata for support and audits.
The registry API is authoritative for real-time status; the JWT is a 30-day cacheable proof.
Lifecycle
Verification is continuously re-evaluated, not a one-time certificate.
(Spec)
- Issued — first heartbeat with all declared-specialism storyboards passing + active membership.
- Active — re-checked every heartbeat; JWT auto-renewed.
- Degraded — first storyboard regression starts a 48-hour grace; the badge continues to render (Spec) while the operator investigates.
- Revoked — 48h continuous failure →
(Spec) qualifier drops from the badge. (Sandbox), if held, is unaffected — the axes are independent.
- Recovery — passing storyboards reissue (Spec) automatically.
(Sandbox)
- Issued — first heartbeat with all declared-specialism storyboards passing against the registered production URL under
account.sandbox: true + active membership. The seller’s prod stack must additionally pass the comply-controller-mode-gate storyboard (refuses controller dispatch against live-mode accounts — the seller-side sandbox isolation contract).
- Active — re-checked every heartbeat; JWT auto-renewed.
- Degraded — first storyboard regression starts a 48-hour grace; the badge continues to render (Sandbox) while the operator investigates. Cross-mode leakage (a sandbox request producing real-world side effects, or a live-mode account accepting a sandbox-flagged controller call) MAY skip the grace period and revoke immediately — that’s the (Sandbox) attestation’s whole point.
- Revoked — 48h continuous failure →
(Sandbox) qualifier drops. (Spec), if held, is unaffected.
- Recovery — passing storyboards (including the mode-gate check) reissue (Sandbox).
Membership lapse revokes the entire badge regardless of test results — public trust marks require active membership.
Mark semantics
A seller MAY hold:
- (Spec) only — storyboards pass on a test-mode endpoint; (Live) not enrolled, or no (Live) path exists for the agent’s specialisms. Common for test agents, sandboxes, and pre-production rollouts.
- (Live) only — real production traffic observed healthy across the rolling window. Common for SDK-built agents whose wire-format correctness is guaranteed by the SDK, and for production-only platforms with no test-mode surface. The eight observability checks already exercise wire format, filters, lifecycle, and scope, so requiring a parallel storyboard pass would be busywork.
- (Spec + Live) — the strongest claim. Both axes verified independently.
- Neither
The two axes are evaluated independently. A storyboard regression revokes (Spec) without affecting (Live); an observability check failure revokes (Live) without affecting (Spec). Sellers can earn either in either order.
Per-version badges
Each badge is identified by (agent, role, AdCP version) — a third axis on top of (Spec) and (Live). An agent can hold parallel badges across AdCP releases. For example, a media-buy agent that ships an upgrade for AdCP 3.1 might hold both:
AAO Verified Media Buy Agent 3.0 (Spec) — earned earlier, still validAAO Verified Media Buy Agent 3.1 (Spec + Live) — earned after upgrading
Each version is evaluated independently. A 3.0 storyboard regression revokes the 3.0 badge without touching 3.1, and vice versa. Membership lapse revokes every version of an agent’s badges atomically (the trust mark is agent-level, not version-level).
The badge label embeds the AdCP version inline between the role and the qualifier: Media Buy Agent 3.1 (Spec + Live).
Display
SVG badge
Two URL shapes:
# Legacy: auto-upgrades to the highest active version
https://agenticadvertising.org/api/registry/agents/{url-encoded-agent-url}/badge/{role}.svg
# Version-pinned: freezes on a specific AdCP release
https://agenticadvertising.org/api/registry/agents/{url-encoded-agent-url}/badge/{role}/{adcp-version}.svg
Media Buy Agent 3.0 (Spec) to Media Buy Agent 3.1 (Spec + Live) automatically when the agent earns 3.1) embed the legacy URL. Buyers who want to call out “verified for AdCP 3.0” specifically embed the version-pinned URL.
Both return a shields.io-style SVG with Content-Security-Policy: script-src 'none' and 5-minute caching. Renders teal when verified, grey when not. Unknown agents, unknown roles, and revoked badges all return a grey “Not Verified” variant — the URL never 404s, which makes it safe to embed. Version-pinned URLs at versions the agent never earned also return “Not Verified” (vs. the legacy URL, which shows the current best mark).
Embed snippet
# Legacy (auto-upgrading)
curl https://agenticadvertising.org/api/registry/agents/{url-encoded-agent-url}/badge/media-buy/embed
# Version-pinned
curl https://agenticadvertising.org/api/registry/agents/{url-encoded-agent-url}/badge/media-buy/3.0/embed
Registry filter
The agent registry surfaces filters on either axis independently:
- “Show me agents that implement AdCP correctly” → filter by
verification_modes contains 'spec'
- “Show me agents I can actually buy through” → filter by
verification_modes contains 'live'
- “Show me agents with both” → filter by both
Both queries are valid. Buyers comparing options use (Live); orchestrator developers integrating new agents use (Spec).
brand.json enrichment
When AAO serves brand.json data for a registered brand, agent entries get an aao_verification block with full per-version detail:
"aao_verification": {
"verified": true,
"verified_at": "2026-04-29T12:34:56.000Z",
"badges": [
{ "role": "media-buy", "adcp_version": "3.1", "verification_modes": ["spec", "live"], "verified_at": "..." },
{ "role": "media-buy", "adcp_version": "3.0", "verification_modes": ["spec"], "verified_at": "..." }
],
"roles": ["media-buy"],
"modes_by_role": { "media-buy": ["spec", "live"] },
"deprecation_notice": "roles[] and modes_by_role reflect the highest-version badge per role only. A buyer pinned to a specific AdCP version SHOULD read badges[] and filter by adcp_version. Both fields will be removed in AdCP 4.0."
}
badges[] is the canonical shape — one entry per (role, adcp_version), ordered version-DESC. Buyers pinned to a specific AdCP version MUST filter by adcp_version rather than reading modes_by_role (which flattens to the highest-version entry per role and could mislead a 3.0 buyer into thinking the agent runs Live for them when only the 3.1 badge has Live).
roles[] and modes_by_role are kept as deprecated aliases for one release. Removal target: AdCP 4.0.
How to claim each qualifier
To claim (Spec)
- Hold an active AAO membership with API-access tier.
- Declare your
supported_protocols and specialisms in get_adcp_capabilities.
- Pass the storyboards your declarations obligate (universal + protocol baselines + specialism baselines) at a specific AdCP major version.
- The AAO compliance heartbeat issues AAO Verified (Spec) automatically and re-verifies on each heartbeat cycle.
To claim (Sandbox)
(Sandbox) is independent of (Spec) — sellers without a separate test deployment can earn (Sandbox) directly by exposing their production endpoint to AAO’s runner with sandbox flagging.
- Hold an active AAO membership with API-access tier.
- Declare your
supported_protocols and specialisms in get_adcp_capabilities (same as (Spec)).
- Register your production
agent_url with AAO. The compliance heartbeat will target it with account.sandbox: true on every storyboard request.
- Implement the sandbox-account gate in your production stack: verify the targeted account is sandbox in your persisted records (not by trusting the field), and process the request with full schema/lifecycle correctness while producing zero real-world side effects — no real spend, no real ad-server orders, no third-party platform calls, no production persistence beyond the bounded sandbox account state.
- Pass the
comply-controller-mode-gate storyboard, which exercises the seller-side isolation contract (refuse controller dispatch against live-mode accounts).
- The AAO compliance heartbeat issues AAO Verified (Sandbox) when the full applicable storyboard suite passes against the registered URL with sandbox-flagged traffic.
Same storyboards as (Spec). Same heartbeat cadence. Different attestation surface: prod, with sandbox flagging, instead of any-registered-endpoint.
What AAO Verified is not
- Not a regulatory or financial attestation. SOC 2, ISO 27001, ISAE 3402 and similar frameworks address operational and financial-control posture — distinct questions, with their own audit paths. AAO Verified is wire-and-delivery correctness for AdCP.
- Not hard ground-truth reconciliation. (Sandbox) attests the production code path handles sandbox-flagged traffic correctly across the protocol surface. It does not reconcile real-money AdCP-reported numbers against the seller’s internal ad-server dashboard under live traffic. Hard reconciliation is a separate kind of attestation tracked outside the (Sandbox) tier.
- Not certification beyond AAO membership. The AgenticAdvertising.org certification program composes with AAO Verified — verification is necessary input to certification, but verification is not certification itself.
- Not a SLA. AAO Verified does not guarantee uptime, latency, or commercial outcomes. It attests that the seller’s AdCP surface continuously reflects real delivery; commercial reliability is between buyer and seller.
- Not a substitute for due diligence. Buyers SHOULD still vet sellers’ contractual terms, billing posture, governance practices, and incident-response posture independently. AAO Verified is one input, not the whole picture.
Relationship to supporting specs
AAO Verified (Sandbox) rests on a small set of normative AdCP spec elements:
The earlier (Live) framing’s supporting issues (#2963, #2964, #2902 — attestation_verifier scope, get_media_buys ownership, behavioral filter assertions on real data) are deferred. They remain relevant if AAO ever returns to a canonical-campaign model, but are not load-bearing under (Sandbox).
Relationship to other surfaces
- Conformance Specification — defines what conformant means via the storyboards. The (Spec) axis verifies your agent matches that specification.
- Compliance Catalog — indexes the protocols and specialisms an agent can claim. Each declared specialism is what the verification engine tests, on whichever axes are eligible.
get_adcp_capabilities — where the agent declares its supported_protocols and specialisms. The declarations are the input to verification.- AAO membership — required for badge issuance. Membership lapse revokes the badge.
