Registering Agents

Registering Agents

Two registration paths depending on whether you are a personal developer or an organisation with a verified domain.

Option A โ€” Personal Developer (no domain required)

Connect your GitHub account and claim ownership via your GitHub identity. If you are signed in, submitting an agent URL auto-claims ownership in the same request โ€” no separate step needed.

A1 โ€” GitHub Repository (simplest)

github.your-username/your-repo

Your agent card lives directly in the repo. No extra config needed.

  1. Add agent-card.json (or /.well-known/agent-card.json) to your repo root
  2. Connect your GitHub account in Settings
  3. Go to Submit Agent and paste your GitHub repo URL

A2 โ€” Personal Hosting

github.your-username.agent-name

For agents on *.github.io or *.workers.dev where domain verification isn't possible.

  1. Add registry identity hints to your card's metadata (see below)
  2. Connect your GitHub account in Settings
  3. Go to Submit Agent and paste your agent URL
RECOMMENDED v1.0

Use A2A Registry Extension (Preferred)

The A2A v1.0 specification now supports extensions. The Registry Extension is the official way to declare identity hints and payment capabilities.

{
  "protocolVersion": "1.0.0",
  "capabilities": {
    "extensions": [{
      "uri": "https://a2a-registry.org/extensions/registry/v1",
      "required": false,
      "params": {
        "identity": {
          "provider": "github",
          "username": "your-github-username",
          "packageName": "github.your-github-username.agent-name"
        }
      }
    }]
  }
}
LEGACY v0.3

Alternative: metadata (Still Supported)

Why metadata and not a root-level field? The A2A v1.0 specification defines a strict schema for the agent card root object. Adding non-standard fields at the root level makes your card non-compliant and can cause validation failures in other A2A-compatible tools. The metadata object is the spec's official extension point โ€” fields placed there are safely ignored by tools that don't understand them.

Reserved namespace: All metadata keys starting with registry (e.g. registryIdentity, registryPackageName, registryIdentityProvider) are reserved by the A2A Global Registry. Future registry features may introduce additional registry* keys. Third-party tools should not use this prefix for their own keys.

If you prefer the v0.3 method, add these fields inside your agent card's metadata object:

"metadata": {
  "registryIdentityProvider": "github",
  "registryIdentity": "your-github-username",
  "registryPackageName": "github.your-github-username.agent-name"
}
FieldValue
registryIdentityProviderAlways "github" for now
registryIdentityYour exact GitHub username (case-insensitive match)
registryPackageNameMust start with github.{registryIdentity}.

These fields are only trusted when the agent URL comes from *.github.io or *.workers.dev. Only you can serve content from your subdomain, making this proof of ownership.

Already in the directory as Unclaimed? Find your agent, click View & Claimon the agent detail page โ€” the same identity check runs automatically, no resubmission needed. If the agent was listed under an auto-generated name (e.g. dev.workers.my_agent), the registry migrates it to your declared registryPackageName and keeps the old name as an alias so existing links still work.

Option B โ€” Organisation with a Verified Domain

Use this for business or team accounts deploying under their own domain. Domain verification proves you control the DNS, giving your agents the highest trust level in the registry.

๐Ÿ“ฅ Submit Agent

Index any publicly available agent into the directory. No account required.

  • Location: /submit
  • Auth: Not required
  • Ownership: Agent has no owner
  • Status: UNCLAIMED
Go to Submit โ†’

๐Ÿš€ Publish Agent

Create and manage agents you own. Requires authentication and a verified domain.

  • Location: /console/agents
  • Auth: Required
  • Ownership: You own the agent
  • Status: STAGE โ†’ ACTIVE
Go to My Agents โ†’
  1. Sign in and create an organisation
  2. In Organisation Settings, add the DNS TXT record shown there to your domain's DNS
  3. Click Verify to confirm ownership
  4. Go to Console โ†’ My Agents, click Publish Agent, choose Website as the source, and enter your agent card URL
  5. Click Go Live to publish
DOMAIN IDENTITY

Claiming agents on personal/free hosting under your org domain

If your agent is currently hosted on a free platform (e.g. *.workers.dev, *.vercel.app) but your organisation has a verified custom domain, you can claim it under your org's namespace by adding a domain identity hint to your agent card:

{
  "capabilities": {
    "extensions": [{
      "uri": "https://a2a-registry.org/extensions/registry/v1",
      "required": false,
      "params": {
        "identity": {
          "provider": "domain",
          "domain": "acme.ai",
          "packageName": "ai.acme.my_agent"
        }
      }
    }]
  }
}

The registry verifies that your organisation owns acme.ai (via Organisation Settings โ†’ Domains) before accepting the claim.packageName is required and used to match the agent listing to be claimed. Claiming transfers ownership without changing the agent's package name.

Agent Sources

When publishing an agent, you can import from various sources:

SourceDescriptionPackage Name
GitHub RepoImport from repo with agent-card.jsongithub.{username}/{repo}
Personal HostingAgent on *.github.io or *.workers.dev with registry identity hints in card metadatagithub.{username}.{slug}
Website ScanScan /.well-known/agent-card.jsoncom.domain.{slug}
ANS EndpointImport from GoDaddy ANSANS-derived
UploadUpload agent-card.json fileuser.{userId}.{slug}
ManualFill out formuser.{userId}.{slug}

Agent States

STAGE
โ†’
ACTIVE
โ†’
STAGE

Publish to go live, Unpublish to return to draft

StateDescriptionVisibility
STAGEDraft, only owner can seeOwner only
ACTIVEPublished, in public directoryEveryone
UNCLAIMEDSubmitted but no ownerPublic (read-only)
SUPERSEDEDRetired in favour of a newer listing โ€” hidden from discoveryBanner page only

Publishing Flow

  1. Create โ€” Import or manually create your agent in STAGE state
  2. Test โ€” Use the Playground to verify functionality
  3. Publish โ€” Verification check, then move to ACTIVE
  4. Manage โ€” Update, unpublish, or delete as needed

Tip: For verifiable sources (GitHub, Website, ANS), publishing triggers a re-verification to ensure the agent card still matches your records.

Superseding a Legacy Agent

Once you own two agents in the same organisation โ€” for example, an old anonymous listing and a new custom-domain deployment โ€” you can mark the old one as superseded by the new one. This consolidates their history without losing any data.

๐Ÿ”—

Redirects visitors

The legacy agent's page shows a prominent banner pointing users to the replacement.

๐Ÿ“Š

Aggregates history

Ratings and reviews from the legacy agent roll up into the new agent's totals dynamically โ€” no data is deleted.

โ†ฉ๏ธ

Fully reversible

Remove or re-target supersession at any time. The legacy agent instantly resumes normal operation.

To supersede an agent: open it in Console โ†’ Agents, click the โ‹ฎ menu โ†’ Supersede with New Agent, and select the replacement from your organisation's active listings.

How to Refresh Your Agent

When you update your agent-card.json (e.g. bumping the version, updating skills, adding payment terms, or changing endpoint URLs), the registry does not update in real-time. Cards are cached upon ingestion and refreshed during background sync cycles. To apply changes immediately, use one of the methods below.

โšก Hash-Gated Ingestion & Freshness Signals

The registry re-fetches your live agent card and compares its SHA-256 hash against the indexed source_agent_card. If the content hash is identical, the refresh operation succeeds as a no-op (changed: false). Make sure your hosting server or CDN has deployed and invalidated the cache before triggering a refresh.

Freshness indicator: lastCheckedAt (or last_checked_at) is the only authoritative timestamp proving the registry performed a real HTTP fetch against your live manifest URL. Fields such as updatedAt or lastSuggestedAt advance during searches, impressions, or metadata updates and do not indicate a card re-fetch.

Method 1 ยท RecommendedClaimed Agents

Console Agent Management

Fastest interactive method for claimed agent owners in the developer console.

  1. Open Console โ†’ My Agents
  2. Click your target agent to open the details drawer
  3. Click the Refresh (โ†ป) button
Rate limit: 1 refresh every 60 seconds per agent.
Method 2 ยท AutomationCI/CD & Deployments

Authenticated Refresh API

Trigger programmatic refreshes from GitHub Actions, webhooks, or deploy scripts via API token.

curl -X POST \
  https://api.a2a-registry.org/api/agents/{ID_OR_PKG}/refresh-token \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Generate tokens in Console โ†’ API Tokens. Tokens must belong to the agent's owner organisation. Accepts agent ID or package name.

Method 3Unclaimed Listings Only

Public Rescan / Re-Submit

For listings that have not yet been claimed into an organisation.

  • Web: Re-submit the URL on Submit Agent
  • API: POST /public/ingest/rescan with {"package_name":"..."}
Note for claimed agents: Re-submitting a claimed agent is an intentional no-op (protects owner listings from public tampering). Claimed agents must use Method 1 or 2.
Method 4 ยท AutomaticScheduled Background Sync

Scheduled Registry Crawl

The registry executes automated background sync batches triggered nightly at 02:00 UTC:

  • Healthy agents: Re-crawled every 7 days.
  • Failing / 404 agents: Rechecked every 24 hours.
  • Dynamic agents: Rechecked every 6 hours.

For immediate updates without waiting for the 7-day cycle, use Method 1 or 2.

Troubleshooting Refresh Issues

SymptomRoot CauseRecommended Resolution
Re-submitted on /submit, but card and lastCheckedAt didn't changeThe agent is already claimed by an organisation; public re-submission is intentionally ignored to protect claimed recordsLog in and refresh from Console โ†’ My Agents or use the authenticated API token endpoint
404 or 401 when calling refresh APIMissing /api/ prefix or missing/unauthorized bearer tokenUse https://api.a2a-registry.org/api/agents/{ID_OR_PKG}/refresh-token with a token from the owning organisation
Listing shows stale card data after refreshYour hosting provider or CDN (Cloudflare, Vercel, etc.) is serving a cached HTTP responsePurge cache on your hosting/CDN, verify live manifest in incognito, then re-trigger refresh
changed: false responseThe fetched manifest content hash matches the existing database recordEnsure the served file actually contains new content compared to the current version
Rate limit error (429)Manual refresh initiated within 60 seconds of previous checkWait 60 seconds before issuing another refresh request

Programmatic API

You can submit agents directly via the REST API without using the web UI. No authentication is required. The base URL for all API calls is https://api.a2a-registry.org.

POST/public/ingest/scanDry-run ยท No save

Probe an agent URL to extract its metadata without saving it to the registry. Use this to validate your agent card before submitting.

curl -X POST https://api.a2a-registry.org/public/ingest/scan \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/.well-known/agent-card.json"}'
POST/public/ingest/submitIndexes agent as UNCLAIMED

Submit an agent URL for public indexing. The agent will appear in the directory with an UNCLAIMED badge. You can later claim ownership via the Developer Console after verifying your domain.

curl -X POST https://api.a2a-registry.org/public/ingest/submit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/.well-known/agent-card.json"}'
Note: Submitting via API creates an unclaimed listing. To get a verified, owned listing with your namespace (e.g. com.example.my-agent), sign in and publish through the Developer Console.
POST/public/ingest/rescanUnclaimed listings only

Trigger an on-demand live re-fetch for an unclaimed agent. Claimed agents must be refreshed by their verified owner via Console or the authenticated API token endpoint.

curl -X POST https://api.a2a-registry.org/public/ingest/rescan \
  -H "Content-Type: application/json" \
  -d '{"package_name":"dev.workers.example_agent"}'
Full API reference: The complete OpenAPI 3.1 specification is available at api.a2a-registry.org/openapi.yaml.