API Reference (A2A JSON-RPC)

Capsule Agents exposes the A2A JSON-RPC API at the root POST / endpoint. All requests use JSON-RPC 2.0 and return JSON-RPC responses. Streaming responses are delivered as Server-Sent Events (SSE) when the method supports it.

Endpoint

• POST /
• Content-Type: application/json

JSON-RPC Request Shape

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "message/send",
  "params": { }
}

Fields:

• jsonrpc: Must be "2.0".
• id: String or number. Required if you want a response.
• method: A2A method name.
• params: Method parameters object.

Methods

message/send

Send a message to create or continue a task. Returns a single JSON-RPC response with the task and/or message results.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        { "kind": "text", "text": "tell me a joke" }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}

message/stream

Send a message and stream updates via SSE. Set Accept: text/event-stream and parse data: events as JSON-RPC responses.

{
  "jsonrpc": "2.0",
  "id": "stream-001",
  "method": "message/stream",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        { "kind": "text", "text": "Generate a short report" }
      ]
    }
  }
}

Example SSE events:

data: {"jsonrpc":"2.0","id":"stream-001","result":{"task":{...}}}

data: {"jsonrpc":"2.0","id":"stream-001","result":{"statusUpdate":{...}}}

data: {"jsonrpc":"2.0","id":"stream-001","result":{"artifactUpdate":{...}}}

tasks/get

Fetch a task by ID. Optionally provide historyLength to limit the task history returned.

{
  "jsonrpc": "2.0",
  "id": "task-1",
  "method": "tasks/get",
  "params": {
    "id": "task_123",
    "historyLength": 20
  }
}

tasks/cancel

Cancel a running task by ID.

{
  "jsonrpc": "2.0",
  "id": "cancel-1",
  "method": "tasks/cancel",
  "params": {
    "id": "task_123"
  }
}

Errors

Errors are returned as JSON-RPC error objects. Common cases:

• Parse error: -32700
• Internal error: -32603

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "error": {
    "code": -32603,
    "message": "Internal error"
  }
}