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:

• SendMessage — Execute a task synchronously
• SendStreamingMessage — Execute a task with SSE streaming
• GetTask — Get task status
• ListTasks — List tasks (cursor-paginated)
• CancelTask — Cancel a running task
• SubscribeToTask — Resume SSE stream for a task

The legacy v0.3 method names (message/send, message/stream, tasks/get, tasks/cancel, tasks/resubscribe) are still accepted as aliases for backward compatibility.

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 v1.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

Request and response examples

All requests are JSON-RPC 2.0 envelopes sent to the A2A endpoint. Message parts use kind (for example "kind": "text"), and the skill to invoke is passed in metadata.skill — in managed orchestration mode you can omit metadata.skill and let the orchestrator route the request.

message/send

Execute a task synchronously and wait for the result:

1
{
2
  "jsonrpc": "2.0",
3
  "id": "req-1",
4
  "method": "message/send",
5
  "params": {
6
    "message": {
7
      "role": "user",
8
      "parts": [{ "kind": "text", "text": "What is your return policy?" }],
9
      "messageId": "msg_123"
10
    },
11
    "metadata": { "skill": "answer_questions" }
12
  }
13
}

A completed task is returned as the result. The status is an object with a state field, and outputs are returned as artifacts:

1
{
2
  "jsonrpc": "2.0",
3
  "id": "req-1",
4
  "result": {
5
    "id": "a2atask_abc123",
6
    "contextId": "ctx_123",
7
    "kind": "task",
8
    "status": { "state": "completed" },
9
    "artifacts": [
10
      {
11
        "name": "response",
12
        "parts": [{ "kind": "text", "text": "Our return policy allows returns within 30 days." }]
13
      }
14
    ]
15
  }
16
}

To continue a multi-turn conversation, include contextId inside params.message. To receive asynchronous updates, add a params.configuration.pushNotificationConfig with a webhook url.

message/stream

Execute a task and receive incremental updates over Server-Sent Events. The stream emits task/status and task/artifact events, and the terminal status carries "final": true:

event: task/status
data: {"taskId":"a2atask_abc123","contextId":"ctx_123","kind":"status-update","status":{"state":"working"},"final":false}
event: task/artifact
data: {"taskId":"a2atask_abc123","artifact":{"artifactId":"art_1","name":"response","parts":[{"kind":"text","text":"Our return policy "}],"append":false,"lastChunk":false},"kind":"artifact-update"}
event: task/artifact
data: {"taskId":"a2atask_abc123","artifact":{"artifactId":"art_1","parts":[{"kind":"text","text":"allows returns within 30 days."}],"append":true,"lastChunk":true},"kind":"artifact-update"}
event: task/status
data: {"taskId":"a2atask_abc123","contextId":"ctx_123","kind":"status-update","status":{"state":"completed"},"final":true}

A task/error event is emitted instead if execution fails.

tasks/get

Retrieve the current state of a task. Pass the task id, and optionally historyLength to include status history:

1
{
2
  "jsonrpc": "2.0",
3
  "id": "req-2",
4
  "method": "tasks/get",
5
  "params": {
6
    "id": "a2atask_abc123",
7
    "historyLength": 10
8
  }
9
}

tasks/cancel

Cancel a running task by its id:

1
{
2
  "jsonrpc": "2.0",
3
  "id": "req-3",
4
  "method": "tasks/cancel",
5
  "params": {
6
    "id": "a2atask_abc123"
7
  }
8
}

Task lifecycle and errors

Every task moves through these states:

Errors are returned as a JSON-RPC error object with a numeric code and optional data:

1
{
2
  "jsonrpc": "2.0",
3
  "id": "req-1",
4
  "error": {
5
    "code": -32002,
6
    "message": "Skill not found",
7
    "data": { "skill": "unknown_skill" }
8
  }
9
}

Standard JSON-RPC codes:

A2A-specific codes:

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