How A2A works

The A2A (Agent-to-Agent) protocol enables AI agents to discover, understand, and invoke each other’s capabilities through standardized communication.

Discovery phase

External agents discover your capabilities by fetching the Agent Card:

$
GET https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/a2a/.well-known/agent-card.json

The Agent Card describes your agent’s identity, skills, and how to invoke them. It is publicly accessible without authentication.

Invocation phase

Once discovered, external agents invoke capabilities by sending JSON-RPC requests to the A2A endpoint:

$
POST https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/a2a

The A2A endpoint supports these JSON-RPC methods:

• message/send — Execute a task synchronously
• message/stream — Execute a task with SSE streaming
• tasks/get — Get task status
• tasks/cancel — Cancel a running task
• tasks/resubscribe — Resume SSE stream for a task

Authentication uses either header:

• Authorization: Bearer a2a_xxx
• X-API-Key: a2a_xxx

Orchestrated routing

When A2A Surfaces use managed mode, the external agent does not need to specify which skill to invoke. Instead:

1. Agent sends a natural language request
2. Your product’s orchestrator analyzes the request
3. Orchestrator routes to the appropriate capability
4. Response is returned to the requesting agent

This simplifies integration — external agents do not need to understand your internal capability structure.

Protocol standards

Runtype’s A2A implementation follows the A2A Protocol v0.3.0 (https://a2a-protocol.org).

Key features:

• JSON-RPC — All communication uses JSON-RPC 2.0
• Self-describing — Skills include schema information in the Agent Card
• Streaming — SSE streaming for real-time responses
• Task lifecycle — Tasks can be tracked, cancelled, and resumed

Security considerations

A2A Surfaces support authentication and rate limiting:

• API key authentication — Keys use the a2a_ prefix
• Rate limits — Configurable per key
• Capability scoping — Control which capabilities are exposed as skills
• Execution logs — Track which agents are calling your capabilities

Use cases

Multi-agent systems

Build complex workflows by composing multiple specialized agents across different platforms.

Cross-platform collaboration

Platforms like LangChain, CrewAI, or Vercel AI SDK can discover and call your Capabilities as part of larger workflows.

Cross-organization collaboration

Partner organizations can integrate their agents with yours without custom integration work.

Next steps

• Connecting external agents for integration details
• Setting up an A2A Surface
• Surface orchestration modes