A2A Registry

The A2A Registry is where you register, inspect, and manage external agents that your project's workflows can delegate work to. Any service that exposes a /.well-known/agent-card.json endpoint can be registered - the platform discovers its capabilities, tracks its health, and routes work to it based on observed performance.

What is an AgentCard?

An AgentCard is a JSON document that describes an agent: its name, a list of skills it can perform, and optional metadata like cost-per-task. The platform fetches and validates this document at registration time and re-fetches it whenever you trigger a refresh.

A minimal AgentCard looks like this:

{
  "name": "code-reviewer",
  "skills": [
    {
      "id": "review",
      "name": "Code Review",
      "description": "Review a pull request for correctness and style.",
      "tags": ["qa"]
    }
  ]
}

The skills[].id field is used as the MCP verb id in the A2A MCP bridge. The optional skills[].inputSchema (JSON Schema) is forwarded to the MCP tool surface so callers know what arguments to pass.

Navigating to the registry

The registry lives at Factory → Agents within any project scope:

/<org>/<project>/factory/agents

Each row in the list shows:

• Agent name and URL
• Number of registered skills
• Current health status (healthy / degraded / unreachable / unknown)
• Trust level
• Last seen timestamp
• Actions: view detail, refresh card, remove

Registering an external agent

URL normalisation rules

The platform normalises the URL you supply before storing and discovery:

• Host is lowercased.
• Trailing slashes are stripped from the pathname.
• If you accidentally paste the full discovery path (/.well-known/agent-card.json), it is stripped automatically - the canonical stored URL is always the base.

Discovery timeout

The default discovery timeout is 5 seconds. Override it org-wide with the A2A_DISCOVERY_TIMEOUT_MS environment variable on the platform server.

Trust levels

Trust level controls how Cedar policies are evaluated for agent-to-agent calls involving this agent. The registry stores the trust level on the agent_cards row; it takes effect immediately on subsequent Cedar evaluations - no cache invalidation required.

You can change the trust level at any time from the agent detail page.

Health statuses

The platform runs periodic health probes against each registered agent's discovery URL. Results are stored in health_probes and the agent's health_status column is updated:

Refreshing a registration

Click Refresh on any registered agent to re-fetch its AgentCard. If the card content has not changed, only last_fetched_at is updated. If it changed, the skill index is rebuilt immediately so routing reflects the new capabilities.

On refresh failure the health_status is set to unreachable and last_error is populated - the previously stored card is preserved so routing decisions already in progress are not disrupted.

Removing a registration

Click Remove to delete an agent card. Because the platform resolves Cedar A2A principals from the live agent_cards row on every request, deletion is sufficient to revoke access - no separate Cedar principal cleanup is needed.

Skill index and routing

When a registration is created or refreshed the platform invalidates the per-org skill index. The skill matcher rebuilds the index lazily on the next routing call. See A2A Routing for how skills are matched to work and how Thompson Sampling selects among matched candidates.

Related pages

• Agent Detail - skills, trust editing, health probe history, raw card JSON
• A2A Dispatches - chronological dispatch log
• A2A Policies - Cedar policy management for agent invocations
• A2A Routing - MAB/Thompson Sampling selection algorithm
• A2A MCP Bridge - how registered agents become MCP tools