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

To manage an agent and qualify it for AAO Verified, enroll it on your member profile. Publisher adagents.json files can also add discovered agents to the registry. See Registering an agent for the owner enrollment flow. 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

Declare the agent type requested by your registration flow. Later capability probes verify the behavior it supports.

How the AAO Verified heartbeat works

AAO runs the compliance heartbeat approximately every hour. It selects your registered agent_url when your configured monitoring interval is due (12 hours by default) and capacity is available. The runner executes the storyboard suite required by your declarations in get_adcp_capabilities (universal baselines, protocol baselines, and declared-specialism storyboards). Repeated checks that cannot produce a grade because of the agent endpoint back off to 48 hours, or your configured interval if longer. A manual requeue clears that backoff. Agents found only through publisher discovery are monitored when their publisher authorization has been refreshed within 30 days. After a completed grade, they are checked at least 48 hours apart. Agents with an active or degraded badge remain monitored even if their listing disappears, until the badge is resolved. 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 shows each enrolled agent’s last authoritative compliance grade. If a check cannot confirm a compatible target or finishes without a complete grade, the previous grade is preserved. Badge state can still change independently during its grace period. Fix the endpoint or saved credentials, then test the affected storyboard and requeue the full suite.

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. The dashboard Test flow can check one storyboard; requeue the full compliance suite for a new grade that can restore the badge.
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 starts the heartbeat approximately every hour and selects due agents within its capacity. You can request these separate actions:

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 Test flow

Use the dashboard Test flow to check a selected storyboard immediately. This targeted test records audit-only evidence and cannot refresh a badge. The owner Recheck status action currently returns 503 while refresh authorization work is in progress; it does not enqueue a compliance run.

Compliance requeue

The Requeue comply button clears the scheduling delay and backoff streak, placing your agent ahead of regular checks at a future heartbeat. It does not clear the last graded result or guarantee a start time.

If you need to inspect a fix immediately, use the dashboard Test flow for the affected storyboard. Badge recovery requires a passing complete suite; use Requeue comply to schedule it. 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

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 Test flow

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 Test flow

​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 Test flow

Compliance requeue

How to read a comply report

Report structure

Per-storyboard verdicts

Debugging a failure

Related