Reference

The complete API surface of the KubeMQ A2A connector: HTTP endpoints, the JSON-RPC 2.0 wire format, the agent card schema, internal channels, configuration fields, error codes, and Prometheus metrics. The connector is a transparent JSON-RPC proxy — agents are plain HTTP servers registered by URL, reached through a per-agent virtual subscriber over the broker.

All HTTP endpoints are served on the shared HTTP server (default port 9090), which also hosts the REST, MCP, and CloudEvents connectors. Prometheus metrics are exposed separately on port 8080 (see Observability).

HTTP Endpoints

A2A endpoints

POST /a2a/{agent_id} is the primary endpoint. Its behavior depends on the JSON-RPC method: message/stream opens an SSE proxy; every other method is forwarded synchronously to the agent. GET /a2a/{agent_id} always returns 405 — use POST for JSON-RPC or GET /a2a/{agent_id}/stream for a server-pushed stream.

# Synchronous message/send
curl -X POST http://localhost:9090/a2a/echo-agent-01 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"parts":[{"text":"Hello, agent!"}]}}}'

# SSE stream via GET
curl -N http://localhost:9090/a2a/echo-agent-01/stream \
  -H 'Accept: text/event-stream'

Registry endpoints

Standard HTTP JSON responses (not JSON-RPC). See Agent registry for the full workflow.

POST /agents/register errors: 400 (card validation), 403 (ownership conflict — a different principal owns this agent_id), 409 (MaxAgents limit reached). registered_by is set automatically from the caller's JWT claims.

# List agents tagged "search" or "nlp", capped at 10
curl 'http://localhost:9090/agents?skill_tags=search,nlp&limit=10'

Agent card endpoints

Both .well-known/agent-card.json paths are public — they bypass authentication. See Agent cards.

# Platform card — confirms the A2A connector is reachable
curl http://localhost:9090/.well-known/agent-card.json

JSON-RPC 2.0 wire format

The connector uses JSON-RPC 2.0 for all client-to-agent communication. A request carries three required fields plus an optional params object.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": { "parts": [{ "text": "Hello, agent!" }] },
    "contextId": "optional-correlation-id",
    "configuration": { "timeout": 30 }
  }
}

Request fields

Methods

KubeMQ is method-agnostic — it forwards any method to the agent unchanged. The five methods below are recognized for metrics labeling; all others are recorded as method="unknown".

Success and error responses

On success, the agent's return value is placed verbatim in result — KubeMQ does not modify the payload. On failure, the response carries an error object instead.

{ "jsonrpc": "2.0", "id": 1, "result": { "…": "agent output, unmodified" } }

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32002, "message": "agent not found: nonexistent-agent" } }

Agent card schema

The AgentCard is submitted on registration and returned, enriched with server-managed timestamps, from the list/get/well-known endpoints. Required fields are agent_id, name, and url.

AgentSkill

{
  "agent_id": "echo-agent-01",
  "name": "Echo Agent",
  "url": "http://localhost:18080/",
  "skills": [{ "id": "echo", "name": "Echo", "tags": ["test", "echo"] }]
}

Internal channel map

The connector and registry use the reserved _AGENTS_. prefix internally. User channels carrying this prefix are rejected (IsReservedChannel). Callers never address these channels directly — the connector and virtual subscriber own them.

Caller HTTP headers are forwarded to the agent as a2a_hdr_* tags on the broker request; the virtual subscriber always sets X-KubeMQ-Caller-ID to the original caller's identity. See Architecture.

SSE event types

Streaming responses (message/stream or GET /a2a/{agent_id}/stream) are delivered as Server-Sent Events. Each event has an event: line and a data: line carrying the stream envelope. A keepalive comment (: keepalive) is sent every 30 seconds; the idle timeout is MaxSSEIdleSeconds (default 300s). See Streaming.

event: task.status
data: {"stream_id":"…","type":"status_update","payload":{"status":"working"}}

event: task.done
data: {"stream_id":"…","type":"done","payload":{"final_result":"completed"}}

Error codes

The connector returns standard JSON-RPC 2.0 base codes plus four A2A-specific codes. See Error handling for the transport-vs-application distinction and retry guidance.

Transport vs application errors

The virtual subscriber sets Executed: false on transport failures (the agent never processed the request) and Executed: true on application errors (the agent processed it and returned an error body). This lets callers choose a retry strategy.

Configuration fields

A2aConfig is configured in Connectors.A2A.*. The connector is enabled by default — set CONNECTORSA2_A_ENABLE=false to disable it. See Configuration and the shared HTTP server enable model for the irregular env-var naming.

The gateway adds a GatewayTimeoutBuffer of 10 seconds on top of the caller-specified timeout so it does not time out before the downstream agent.

Metrics

Prometheus metrics are exposed on port 8080 at /metrics. See Observability for the full surface and the web AI dashboard.

The method label is sanitized against the five standard methods; any other value is recorded as method="unknown" to bound Prometheus label cardinality.

curl http://localhost:8080/metrics 2>/dev/null | grep kubemq_a2a_