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)
Your agent card lives directly in the repo. No extra config needed.
- Add
agent-card.json(or/.well-known/agent-card.json) to your repo root - Connect your GitHub account in Settings
- Go to Submit Agent and paste your GitHub repo URL
A2 โ Personal Hosting
For agents on *.github.io or *.workers.dev where domain verification isn't possible.
- Add registry identity hints to your card's
metadata(see below) - Connect your GitHub account in Settings
- Go to Submit Agent and paste your agent URL
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"
}
}
}]
}
}Alternative: metadata (Still Supported)
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"
}| Field | Value |
|---|---|
| registryIdentityProvider | Always "github" for now |
| registryIdentity | Your exact GitHub username (case-insensitive match) |
| registryPackageName | Must 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
๐ 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
- Sign in and create an organisation
- In Organisation Settings, add the DNS TXT record shown there to your domain's DNS
- Click Verify to confirm ownership
- Go to Console โ My Agents, click Publish Agent, choose Website as the source, and enter your agent card URL
- Click Go Live to publish
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:
| Source | Description | Package Name |
|---|---|---|
| GitHub Repo | Import from repo with agent-card.json | github.{username}/{repo} |
| Personal Hosting | Agent on *.github.io or *.workers.dev with registry identity hints in card metadata | github.{username}.{slug} |
| Website Scan | Scan /.well-known/agent-card.json | com.domain.{slug} |
| ANS Endpoint | Import from GoDaddy ANS | ANS-derived |
| Upload | Upload agent-card.json file | user.{userId}.{slug} |
| Manual | Fill out form | user.{userId}.{slug} |
Agent States
Publish to go live, Unpublish to return to draft
| State | Description | Visibility |
|---|---|---|
| STAGE | Draft, only owner can see | Owner only |
| ACTIVE | Published, in public directory | Everyone |
| UNCLAIMED | Submitted but no owner | Public (read-only) |
| SUPERSEDED | Retired in favour of a newer listing โ hidden from discovery | Banner page only |
Publishing Flow
- Create โ Import or manually create your agent in
STAGEstate - Test โ Use the Playground to verify functionality
- Publish โ Verification check, then move to
ACTIVE - 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.
Console Agent Management
Fastest interactive method for claimed agent owners in the developer console.
- Open Console โ My Agents
- Click your target agent to open the details drawer
- Click the Refresh (โป) button
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.
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/rescanwith{"package_name":"..."}
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
| Symptom | Root Cause | Recommended Resolution |
|---|---|---|
Re-submitted on /submit, but card and lastCheckedAt didn't change | The agent is already claimed by an organisation; public re-submission is intentionally ignored to protect claimed records | Log in and refresh from Console โ My Agents or use the authenticated API token endpoint |
| 404 or 401 when calling refresh API | Missing /api/ prefix or missing/unauthorized bearer token | Use 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 refresh | Your hosting provider or CDN (Cloudflare, Vercel, etc.) is serving a cached HTTP response | Purge cache on your hosting/CDN, verify live manifest in incognito, then re-trigger refresh |
changed: false response | The fetched manifest content hash matches the existing database record | Ensure the served file actually contains new content compared to the current version |
| Rate limit error (429) | Manual refresh initiated within 60 seconds of previous check | Wait 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.
/public/ingest/scanDry-run ยท No saveProbe 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"}'/public/ingest/submitIndexes agent as UNCLAIMEDSubmit 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"}'com.example.my-agent), sign in and publish through the Developer Console./public/ingest/rescanUnclaimed listings onlyTrigger 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"}'