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.

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

github.your-username.agent-name

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

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

📖 Extension Reference 🛠️ Use Card Builder

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

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

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 →

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

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

STAGE

→

ACTIVE

→

STAGE

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)

Publishing Flow

Create — Import or manually create your agent in STAGE state
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.

User Types

Payment Discovery