Publishing Your Agent to the A2A Registry

Before You Begin

Publishing an agent to the A2A Registry makes it discoverable to other developers and organizations across the ecosystem. Before you start, make sure your agent meets these prerequisites:

• Your agent implements the A2A protocol and can handle standard A2A message exchanges
• You have an account on the A2A Registry (sign up at a2areg.com)
• You have the A2A CLI installed (npm install -g @a2a/cli or pip install a2a-cli)

Step 1: Define Your AgentCard

The AgentCard is the metadata document that describes your agent to the registry. It includes your agent's name, capabilities, supported input/output schemas, and endpoint information. Create a file called agent-card.json in your project root:

• name — a unique, human-readable identifier for your agent
• description — a clear explanation of what your agent does and when to use it
• skills — an array of capabilities your agent supports, each with its own input/output schema
• endpoint — the URL where your agent is accessible
• version — the current semantic version of your agent

Be thorough in your skill descriptions. These are what other developers will search against when looking for agents to integrate, so clarity here directly impacts discoverability.

Step 2: Validate Your AgentCard

Before publishing, run the validation command to ensure your AgentCard conforms to the A2A specification:

The validator checks for required fields, schema correctness, and endpoint reachability. If your agent's endpoint is not yet deployed, you can use the --skip-endpoint flag to validate the metadata only.

• Schema validation — ensures all required fields are present and correctly typed
• Skill validation — verifies that each skill has valid input/output schemas
• Endpoint check — confirms your agent is reachable and responds to A2A health checks

Step 3: Authenticate and Publish

Log in to the registry from the CLI, then publish your agent:

The CLI will authenticate you, upload your AgentCard, and register your agent in the global index. Once published, your agent is immediately discoverable through the registry's search interface and API.

Setting Visibility

By default, agents are published as public, meaning anyone can discover and integrate them. If you want to restrict visibility to your organization, use the --private flag. Private agents are only visible to members of your team.

Step 4: Verify Your Listing

After publishing, visit the registry to verify your agent appears correctly. Check that:

• Your agent's name and description are accurate
• All skills are listed with their correct schemas
• The version number matches what you intended
• The endpoint is marked as reachable

Updating Your Agent

When you release a new version, update the version field in your AgentCard and run the publish command again. The registry tracks all versions, so consumers on older versions are not affected. Use semantic versioning to communicate the nature of changes: patch for bug fixes, minor for new skills or non-breaking changes, and major for breaking changes.

Publishing to the A2A Registry is the fastest way to get your agent in front of the developers who need it. Once listed, your agent joins a growing ecosystem of composable, interoperable AI agents powering real-world workflows.