Talk to your agent via A2A (JSON-RPC)

The A2A (Agent-to-Agent) endpoint lets third-party agents, agent platforms, or agent workspaces interact with your Inkeep Agent using a standard agent protocol.

Here are some example platforms that you can add Inkeep Agents to:

Authentication

Choose the authentication method:

See Authentication → Run API for more details.

Endpoints

• Agent card discovery (agent or sub-agent-level): GET <INKEEP_AGENTS_RUN_API_URL>/agents/.well-known/agent.json
• A2A protocol (agent or sub-agent-level): POST <INKEEP_AGENTS_RUN_API_URL>/agents/.well-known/agent.json

Notes:

• If you supply x-inkeep-sub-agent-id in headers, requests target that specific Sub Agent. This is supported in development (or when using the bypass secret). With production API keys, requests always use the Agent's default Sub Agent.

Message Send (Blocking)

• Path: POST <INKEEP_AGENTS_RUN_API_URL>/agents/a2a
• Headers: Per Authentication section (Standard API Key recommended)
• Body (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": 1,
  "params": {
    "message": {
      "messageId": "msg-123",
      "role": "user",
      "parts": [
        { "kind": "text", "text": "Hello!" }
      ],
      "contextId": "conv-123",
      "kind": "message"
    },
    "configuration": {
      "acceptedOutputModes": ["text", "text/plain"],
      "blocking": true
    }
  }
}

• Success Response (Message):

{
  "jsonrpc": "2.0",
  "result": {
    "kind": "message",
    "messageId": "auto-generated",
    "role": "agent",
    "parts": [ { "kind": "text", "text": "..." } ],
    "taskId": "task-...",
    "contextId": "conv-123"
  },
  "id": 1
}

• Transfer Case: if the agent decides to transfer, the response contains a task with a transfer artifact:

{
  "jsonrpc": "2.0",
  "result": {
    "kind": "task",
    "id": "task-...",
    "contextId": "conv-123",
    "status": { "state": "completed", "timestamp": "..." },
    "artifacts": [
      {
        "artifactId": "...",
        "parts": [
          { "kind": "data", "data": { "type": "transfer", "targetSubAgentId": "other-agent-id" } },
          { "kind": "text", "text": "Transfer reason text" }
        ]
      }
    ]
  },
  "id": 1
}

Message Send (Non-blocking)

Set configuration.blocking to false. The server immediately returns a task, and you can poll or stream updates.

• Request: same as above, with "blocking": false
• Response (Task):

{
  "jsonrpc": "2.0",
  "result": {
    "kind": "task",
    "id": "task-...",
    "contextId": "conv-123",
    "status": { "state": "completed", "timestamp": "..." },
    "artifacts": [ { "artifactId": "...", "parts": [ { "kind": "text", "text": "..." } ] } ]
  },
  "id": 1
}

Streaming Messages (SSE)

• Path: POST /agents/a2a
• Headers: include Accept: text/event-stream plus Authentication headers
• Body (JSON-RPC 2.0): same as blocking, but method "message/stream"

{
  "jsonrpc": "2.0",
  "method": "message/stream",
  "id": 2,
  "params": {
    "message": {
      "messageId": "msg-456",
      "role": "user",
      "parts": [ { "kind": "text", "text": "Stream please" } ],
      "contextId": "conv-123",
      "kind": "message"
    },
    "configuration": {
      "acceptedOutputModes": ["text", "text/plain"],
      "blocking": false
    }
  }
}

• SSE Events (each line is an SSE data: payload containing JSON-RPC):

: keep-alive

data: {"jsonrpc":"2.0","result":{"kind":"task","id":"task-...","contextId":"conv-123","status":{"state":"working","timestamp":"..."},"artifacts":[]},"id":2}

data: {"jsonrpc":"2.0","result":{"kind":"message","messageId":"...","role":"agent","parts":[{"kind":"text","text":"..."}],"taskId":"task-...","contextId":"conv-123"},"id":2}

data: {"jsonrpc":"2.0","result":{"kind":"task","id":"task-...","contextId":"conv-123","status":{"state":"completed","timestamp":"..."},"artifacts":[{"artifactId":"...","parts":[{"kind":"text","text":"..."}]}]},"id":2}

• Transfer (streaming): if a transfer is triggered, an SSE event with a JSON-RPC result of transfer details is sent, then the stream ends.

Task APIs

• Get task: POST /agents/a2a with method "tasks/get" and params { "id": "task-..." } → returns the task
• Cancel task: POST /agents/a2a with method "tasks/cancel" and params { "id": "task-..." } → returns { "success": true }
• Resubscribe (SSE, mock): POST /agents/a2a with method "tasks/resubscribe" and params { "taskId": "task-..." } → SSE with a task event

Agent Card Discovery

• Agent-level: GET /agents/.well-known/agent.json (uses Agent's default Sub Agent)
• Agent-level (dev/bypass only): Provide x-inkeep-sub-agent-id in headers to target a specific agent for discovery

Notes & Behavior

• contextId resolution: The server first tries task.context.conversationId (derived from the request), then params.message.metadata.conversationId. Final fallback is 'default'.
• Artifacts in responses: Message/Task responses may include artifacts[0].parts as the agent's output parts.
• Errors (JSON-RPC): Standard JSON-RPC error codes: -32600, -32601, -32602, -32603, -32700, plus A2A-specific -3200x codes.

Development Notes

• Base URL (local): http://localhost:3003
• Route Mounting: A2A routes are mounted under /agents; use /agents/a2a for RPC and /agents/.well-known/agent.json for discovery
• Streaming support: Requires agent capabilities streaming: true in the agent card