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.

Once your agent is registered in the AAO registry, your responsibilities don’t end at enrollment. The registry continuously monitors your agent’s protocol conformance via the AAO Verified compliance heartbeat and reflects the current health of your listing in the dashboard. This page covers the full operator lifecycle: what the heartbeat tests, how to read dashboard status indicators, how to manually trigger a re-probe, and how to interpret a comply report.

​
Registration recap

There is one path into the AAO registry: an AAO member explicitly enrolls the agent on their member profile. See Registering an agent for the full enrollment flow — dashboard or PUT /api/me/member-profile, end-to-end in under five minutes. After enrollment your agent gets:
  • A catalog entry in /api/registry/agents with visibility: "members_only" (upgrade to public on a paid AAO tier)
  • Eligibility for the AAO Verified badge, issued automatically once your agent passes the relevant storyboards on the compliance heartbeat
The next crawler probe will resolve your agent’s type from its get_adcp_capabilities response — you do not need to set or maintain the type field manually.

​
How the AAO Verified heartbeat works

AAO continuously re-evaluates your agent’s conformance on an approximately 1-hour heartbeat cadence. Every heartbeat cycle, AAO’s compliance runner executes the storyboard suite against your registered agent_url — the same set of storyboards your declarations in get_adcp_capabilities obligate (universal baselines + protocol baselines + declared-specialism storyboards). What the heartbeat tests:
  • AdCP wire format and task shape
  • Error semantics and error envelopes
  • State-machine transitions across the media-buy or applicable lifecycle
  • Declared specialisms map to working tools
  • Schema conformance and filter behavior
  • Idempotency semantics
The heartbeat is not a registry crawl. A crawl re-reads your adagents.json or capability snapshot and updates registry metadata. The heartbeat runs protocol storyboards against your live endpoint and determines your verification status. The two are independent operations.

​
Verified (Spec) vs Verified (Sandbox)

Both qualifiers run the same storyboards on the same ~1h heartbeat. The difference is where the runner targets:
QualifierRunner targetsWhat it attests
(Spec)Any endpoint you register — test deployment, local dev, sandbox-only stackAdCP wire format and protocol semantics are correct
(Sandbox)Your registered production agent_url with account.sandbox: true on every requestYour production code path honors sandbox flagging with zero real-world side effects
See AAO Verified for complete eligibility and attestation details.

​
Dashboard status indicators

The agent dashboard at agenticadvertising.org/dashboard/agents reflects the current state of each enrolled agent. The status comes from the compliance heartbeat — AAO updates it on every probe cycle.
StatusWhat it meansOperator action
ActiveAll storyboards are passing on the current heartbeat. Your AAO Verified badge is live and auto-renewing.No action needed. Monitor for regressions after deploys.
DegradedAt least one storyboard started failing. The badge continues to render while a 48-hour grace period runs.Investigate immediately — check the comply report, reproduce locally with @adcp/sdk/testing, and fix the regression before the grace period expires.
Revoked48 hours of continuous storyboard failure elapsed without recovery. The qualifier has dropped from the badge. (Sandbox), if separately held, is unaffected — the two axes are independent.Fix the underlying conformance issue, then wait for the next heartbeat cycle to restore the badge automatically.
RecoveryStoryboards are passing again after a prior failure. The badge qualifier reissues automatically.No action needed beyond confirming the fix is stable.
Grace period math. The Degraded state begins on the first failed heartbeat. The 48-hour clock runs from that initial failure — not from when you first notice the status. Check your comply report promptly after any deploy that touches protocol behavior.
Membership lapse revokes the entire badge immediately, regardless of storyboard results. AAO Verified is contingent on active AAO membership at an API-access tier.

​
How to manually trigger a re-probe

AAO runs probes automatically on the ~1h heartbeat, but there are two ways to trigger an immediate refresh:

​
Registry crawl (metadata update)

If you’ve updated your adagents.json, brand.json, or capability snapshot and want the registry to pick up changes without waiting for the next scheduled crawl, use the crawl-request endpoint: 
curl -X POST "https://agenticadvertising.org/api/registry/crawl-request" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"yourcompany.com"}'
This runs asynchronously and returns 202 Accepted. Rate-limited to one request per domain every 5 minutes and 30 requests per user per hour. What this does and does not do:
  • Does refresh your agent’s registry metadata (type resolution, capability snapshot, adagents.json authorization graph)
  • Does not trigger a compliance heartbeat re-run — the heartbeat storyboards are not re-executed by this endpoint

​
Dashboard Refresh button

In the agent card on agenticadvertising.org/dashboard/agents, the Refresh button calls /api/registry/agents/{encodedUrl}/refresh. Like the crawl-request endpoint, this re-reads your agent’s registry metadata and updates the dashboard view. It is a registry metadata refresh, not a full compliance re-run.
Re: comply re-runner (#4253). Manually triggering a full compliance storyboard re-run (outside the ~1h heartbeat schedule) is not currently available via the dashboard or API. If you need to confirm a fix before the next scheduled heartbeat, reproduce the storyboard locally using @adcp/sdk/testing — the local runner runs the same storyboard suite the heartbeat uses.

​
How to read a comply report

The comply report appears in your agent’s dashboard panel under the AAO Verified section. It shows the result of the most recent heartbeat run.

​
Report structure

FieldWhat it means
Overall verdictpassed — all applicable storyboards passed. failed — at least one storyboard failed. degraded — first failure detected; grace period running.
Storyboard resultsPer-storyboard breakdown. Each entry has a verdict and an optional failure_reason.
Specialism coverageWhich declared specialisms were tested, and which storyboards each obligates.
Heartbeat timestampWhen this probe ran.

​
Per-storyboard verdicts

VerdictMeaning
passedThe storyboard’s assertions all evaluated true against your agent’s response.
failedAt least one assertion failed. The failure_reason field identifies which assertion and what the runner received.
skippedThe storyboard does not apply to your declared specialisms or current protocol version.
not_applicableThe storyboard tests an operation your agent has not declared support for — graded not_applicable rather than failed. Common for optional tools and controller-only storyboards.

​
Debugging a failure

  1. Note the storyboard name from the failed row (e.g. signed_requests, pagination_integrity, comply-controller-mode-gate).
  2. Find the storyboard definition in the Compliance Catalog.
  3. Reproduce locally: 
    npx @adcp/sdk test --storyboard signed_requests --url https://your-agent-url.example/mcp
  4. The local runner gives the same assertions as the heartbeat. Fix the failure, verify locally, then deploy — the next heartbeat cycle will reissue the badge if all storyboards pass.
  • Registering an agent — the enrollment path, fields, and programmatic registration.
  • Registry API overview — POST /api/registry/crawl-request and the full endpoint catalog.
  • AAO Verified — full lifecycle states, axis semantics, and badge embedding.
  • Compliance Catalog — the storyboard index, per-specialism coverage, and how to run storyboards locally.