A2X

Concepts

A2A in one page

A2A (Agent-to-Agent) is an open protocol for one agent to discover and call another. It is deliberately boring: HTTP + JSON-RPC 2.0, with an optional Server-Sent Events stream. The spec lives at a2a-protocol.org.

The two endpoints

An A2A-compliant agent exposes exactly two routes:

Method Path Purpose
GET /.well-known/agent.json Publish the AgentCard (discovery).
POST /a2a JSON-RPC endpoint (message/send, message/stream, tasks/get, tasks/cancel).

That's the whole protocol surface. Anything beyond this — model choice, storage, tools, auth — is implementation detail.

The AgentCard

The AgentCard is the agent's self-description: who it is, what it can do, how to reach it, and what auth it requires. A minimal v1.0 card looks like:

{
  "name": "my_assistant",
  "description": "A helpful assistant.",
  "supportedInterfaces": [
    { "url": "https://agent.example.com/a2a", "protocolBinding": "jsonrpc-2.0" }
  ],
  "skills": [
    { "id": "chat", "name": "Chat", "description": "General conversation", "tags": ["chat"] }
  ],
  "securityRequirements": []
}

The SDK auto-derives every field from your runtime objects — you rarely write this JSON by hand. A2X publishes both v0.3 and v1.0 shapes from the same instance.

The four RPC methods

Method Shape When
message/send Request → one response (may include a task id). Simple one-shot.
message/stream Request → SSE stream of events. Long replies, tool use, partial results.
tasks/get { taskId } → current task state. Resume a long-running job.
tasks/cancel { taskId } → canceled task. Abort.

The task model is explicit: every call produces a Task with state transitions (pending → running → completed / canceled / failed). The client can reconnect and fetch status at any time.

Why not just REST?

REST has no shared model of "a task." Every team invents its own status endpoints, its own cancellation semantics, its own streaming format. A2A standardizes those primitives so any compliant client can call any compliant agent.

Where A2X fits

A2X's job is to let you write ordinary TypeScript and get A2A compliance for free:

import { LlmAgent, toA2x } from '@a2x/sdk';
 
const agent = new LlmAgent({ /* ... */ });
toA2x(agent, { port: 4000 });
// → /.well-known/agent.json + /a2a, A2A v0.3 + v1.0 ready

Next