AdCP — Maintaining your agent

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.

Grading profiles and verification modes

The agent dashboard can compare three grading profiles from the same completed heartbeat evidence:

Grading profile	Meaning
Legacy grading	The compatibility evaluator used by existing badges and by every role/version with no explicit selection.
Strict Spec grading	Requires complete universal, role-protocol, and declared-specialism evidence. Missing or ambiguous evidence never counts as a pass.
Sandbox grading preview	A non-selectable preview. It remains unavailable until the runner exposes causal bundle data and AgenticAdvertising.org publishes a versioned exception catalog.

This comparison is passive. Opening the dashboard and selecting a saved result do not contact your agent or enqueue another compliance run. Selection enqueues only a database-backed badge and token projection retry from that immutable result. For each exact agent role and AdCP version, an organization owner or admin can select Legacy grading or Strict Spec grading from a current completed run. The selection is authenticated, revision-checked, reversible, and recorded in an append-only audit. New roles and versions independently default to Legacy. If a selected result is non-passing, the dashboard requires an explicit public-impact confirmation. An active badge degrades and enters the existing 48-hour grace period; selection never creates a badge from non-passing evidence. The first failing Strict Spec timestamp survives Legacy/Spec toggles and clears only after a passing Strict Spec assessment, so toggling cannot restart grace. Grading profiles are separate from badge evidence modes. verification_modes values such as spec and live describe what kind of evidence a badge carries; live remains independent. A badge token’s grading_profile claim identifies Legacy or Strict Spec grading. Older claim-less tokens are historical Legacy evidence. Offline copies may remain cryptographically valid for their existing 30-day lifetime after a selection changes, so use the registry API for real-time status. Legacy has no automatic migration. Six months after selection general availability is a review point only. Any retirement is a separate working-group decision, cannot occur before 12 months, requires at least 90 days’ notice and a safe selectable profile for production agents, and would make remaining Legacy identities unverified rather than silently relabeling them Strict Spec. 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.

Status	What it means	Operator action
Active	All storyboards are passing on the current heartbeat. Your AAO Verified badge is live and auto-renewing.	No action needed. Monitor for regressions after deploys.
Degraded	At 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.
Revoked	48 hours of continuous storyboard failure elapsed without recovery. The verification qualifier has dropped from the badge.	Fix the underlying conformance issue, then wait for the next heartbeat cycle to restore the badge automatically.
Recovery	Storyboards 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 three ways to refresh agent state:

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"}'

const res = await fetch(
  "https://agenticadvertising.org/api/registry/crawl-request",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ domain: "yourcompany.com" }),
  }
);
// Returns 202 Accepted — crawl runs asynchronously

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 Recheck status button calls /api/registry/agents/{encodedUrl}/refresh. It re-reads your agent’s registry metadata and, when you own the agent and the capability probe succeeds, runs the full compliance storyboard suite synchronously before updating the dashboard view.

Compliance requeue

The Requeue comply button does not run the storyboard suite immediately. It clears last_checked_at so the agent is picked up by the next scheduled heartbeat cycle, which can take up to about 1 hour.

If you need to confirm a fix immediately, use Recheck status or the dashboard Test flow rather than Requeue comply. For local reproduction, run the same storyboards with @adcp/sdk/testing.

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

Field	What it means
Overall verdict	`passed` — all applicable storyboards passed. `failed` — at least one storyboard failed. `degraded` — first failure detected; grace period running.
Storyboard results	Per-storyboard breakdown. Each entry has a `verdict` and an optional `failure_reason`.
Specialism coverage	Which declared specialisms were tested, and which storyboards each obligates.
Heartbeat timestamp	When this probe ran.

Per-storyboard verdicts

Verdict	Meaning
`passed`	The storyboard’s assertions all evaluated true against your agent’s response.
`failed`	At least one assertion failed. The `failure_reason` field identifies which assertion and what the runner received.
`skipped`	The storyboard does not apply to your declared specialisms or current protocol version.
`not_applicable`	The 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

Note the storyboard name from the failed row (e.g. signed_requests, pagination_integrity, comply-controller-mode-gate).
Find the storyboard definition in the Compliance Catalog.

Reproduce locally:

npx @adcp/sdk@latest storyboard run signed_requests --agent-url https://your-agent-url.example/mcp

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.

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

Maintaining your agent

Registration recap

How the AAO Verified heartbeat works

Grading profiles and verification modes

Dashboard status indicators

How to manually trigger a re-probe

Registry crawl (metadata update)

Dashboard Refresh button

Compliance requeue

How to read a comply report

Report structure

Per-storyboard verdicts

Debugging a failure

​Registration recap

​How the AAO Verified heartbeat works

​Grading profiles and verification modes

​Dashboard status indicators

​How to manually trigger a re-probe

​Registry crawl (metadata update)

​Dashboard Refresh button

​Compliance requeue

​How to read a comply report

​Report structure

​Per-storyboard verdicts

​Debugging a failure

​Related

Registration recap

How the AAO Verified heartbeat works

Grading profiles and verification modes

Dashboard status indicators

How to manually trigger a re-probe

Registry crawl (metadata update)

Dashboard Refresh button

Compliance requeue

How to read a comply report

Report structure

Per-storyboard verdicts

Debugging a failure

Related