Skip to main content

Agent-to-Agent (A2A) Protocol API Reference

GoRoute AI Gateway implements the Linux Foundation Agent-to-Agent (A2A v1.0) protocol specification. It serves as an enterprise gateway for autonomous agent discovery, asynchronous multi-step task delegation, real-time event streaming, and cross-framework agent federation.

[!NOTE] All A2A data plane endpoints require standard Bearer token authentication using a tenant Virtual API Key:

Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e

A2A Endpoints Summary​

Protocol / MethodEndpointDescription
GET/.well-known/agent-card.jsonRFC 8785 JCS canonicalized & RFC 7515 JWS signed Agent Card
POST/a2a/v1/agents/{agentSlug}Dual-binding message dispatch (JSON-RPC 2.0 & HTTP+JSON)
GET/a2a/v1/agents/{agentSlug}/tasksList tasks managed by the agent
GET/a2a/v1/agents/{agentSlug}/tasks/{taskID}Inspect state, iteration budget, and outputs for a task
POST/a2a/v1/agents/{agentSlug}/tasks/{taskID}:cancelSafely abort an in-flight task execution
GET/a2a/v1/agents/{agentSlug}/tasks/{taskID}:subscribeSubscribe-First SSE stream emitting monotonic a2a-events
gRPClf.a2a.v1.A2AServiceNative high-performance gRPC service
POST/v1/chat/completions (model: "a2a/{slug}")OpenAI-compatible bridge for multi-agent workflows

1. Cryptographic Agent Card Discovery (GET /.well-known/agent-card.json)​

Exposes the gateway's canonical agent identity formatted with RFC 8785 JSON Canonicalization Scheme (JCS) and signed with RFC 7515 JWS (ES256). External agents and registries use this card to verify capabilities, cryptographic public keys, and supported endpoints.

cURL Request​

curl http://localhost:8080/.well-known/agent-card.json

Response Schema (HTTP 200 OK)​

{
"name": "GoRoute AI Gateway Agent Service",
"version": "1.0.0",
"description": "Enterprise Autonomous Routing, Aggregation & Inference Agent",
"supportedInterfaces": [
{
"url": "http://localhost:8080/a2a/v1/agents/analyst",
"protocolBinding": "HTTP+JSON"
},
{
"url": "http://localhost:8080/a2a/v1/agents/analyst",
"protocolBinding": "JSON-RPC-2.0"
},
{
"url": "grpc://localhost:9090",
"protocolBinding": "gRPC"
}
],
"capabilities": {
"streaming": true,
"asyncTasks": true,
"pushNotifications": true
},
"signatures": [
{
"header": {
"alg": "ES256",
"kid": "gw-a2a-signer-v1",
"typ": "JWT"
},
"signature": "MEUCIQDx41..."
}
]
}

2. Dual-Binding Agent Message Dispatch (POST /a2a/v1/agents/{agentSlug})​

Dispatches messages to upstream agents. GoRoute inspects the request body and transparently handles both JSON-RPC 2.0 and HTTP+JSON Protobuf REST formats.

Option A: JSON-RPC 2.0 Binding (tasks/send)​

curl -X POST http://localhost:8080/a2a/v1/agents/risk-analyst \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "req-a2a-001",
"method": "tasks/send",
"params": {
"message": {
"role": "ROLE_USER",
"parts": [
{ "text": "Perform portfolio Value-at-Risk assessment for Portfolio Q3." }
]
}
}
}'

JSON-RPC 2.0 Response (HTTP 200 OK)​

{
"jsonrpc": "2.0",
"id": "req-a2a-001",
"result": {
"role": "ROLE_AGENT",
"parts": [
{ "text": "Portfolio risk assessment completed: VaR (95% confidence) is 1.42%." }
],
"taskId": "task_a2a_5b91a7c0",
"state": "completed"
}
}

Option B: HTTP+JSON Protobuf Binding​

curl -X POST http://localhost:8080/a2a/v1/agents/risk-analyst \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"message": {
"role": "ROLE_USER",
"parts": [
{ "text": "Calculate VaR 99% for portfolio." }
]
},
"budget": {
"max_cost_micros": 5000000,
"max_iterations": 10
}
}'

3. Task Management Endpoints​

Inspect, list, and control asynchronous agent execution lifecycles.

Inspect Task Details (GET /a2a/v1/agents/{agentSlug}/tasks/{taskID})​

curl http://localhost:8080/a2a/v1/agents/risk-analyst/tasks/task_a2a_5b91a7c0 \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e"

Response (HTTP 200 OK)​

{
"id": "task_a2a_5b91a7c0",
"agent_slug": "risk-analyst",
"state": "working",
"created_at": "2026-11-10T12:00:00Z",
"updated_at": "2026-11-10T12:00:05Z",
"iterations_executed": 3,
"max_iterations": 10,
"cost_incurred_micros": 12500
}

Cancel In-Flight Task (POST /a2a/v1/agents/{agentSlug}/tasks/{taskID}:cancel)​

Safely terminates background execution and prevents further upstream model spend:

curl -X POST http://localhost:8080/a2a/v1/agents/risk-analyst/tasks/task_a2a_5b91a7c0:cancel \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e"

4. Subscribe-First Real-Time SSE Task Streaming (GET ...:subscribe)​

Clients connect to stream durable task events (status transitions, intermediate thoughts, artifact publications) in real-time. Emits a2a-event Server-Sent Events with strictly monotonic sequence numbers (seq).

curl -N http://localhost:8080/a2a/v1/agents/risk-analyst/tasks/task_a2a_5b91a7c0:subscribe \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Accept: text/event-stream"

Event Stream Wire Format​

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

event: a2a-event
data: {"seq":1,"taskId":"task_a2a_5b91a7c0","state":"working","timestamp":"2026-11-10T12:00:01Z"}

event: a2a-event
data: {"seq":2,"taskId":"task_a2a_5b91a7c0","state":"working","thought":"Fetching historical volatility for 50 tickers...","timestamp":"2026-11-10T12:00:02Z"}

event: a2a-event
data: {"seq":3,"taskId":"task_a2a_5b91a7c0","state":"completed","output":{"role":"ROLE_AGENT","parts":[{"text":"VaR calculation complete."}]},"timestamp":"2026-11-10T12:00:05Z"}

5. Native A2A gRPC Service (lf.a2a.v1.A2AService)​

For latency-critical agent-to-agent communication, GoRoute exposes a native gRPC server implementing the official Linux Foundation Protobuf contract.

Protobuf Service Definition​

syntax = "proto3";
package lf.a2a.v1;

service A2AService {
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
rpc GetTask(GetTaskRequest) returns (Task);
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
rpc CancelTask(CancelTaskRequest) returns (Task);
rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamTaskResponse);
}

Go gRPC Client Example​

package main

import (
"context"
"fmt"
"google.golang.org/grpc"
"google.golang.org/grpc/metadata"
pb "github.com/goroute-ai/ai-gateway-go/internal/a2a/pb"
)

func main() {
conn, _ := grpc.Dial("localhost:9090", grpc.WithInsecure())
defer conn.Close()

client := pb.NewA2AServiceClient(conn)
md := metadata.Pairs("authorization", "Bearer sk-gw-prod-7f9a2b8c4d1e")
ctx := metadata.NewOutgoingContext(context.Background(), md)

resp, err := client.SendMessage(ctx, &pb.SendMessageRequest{
AgentSlug: "risk-analyst",
Message: &pb.Message{
Role: pb.MessageRole_ROLE_USER,
Parts: []*pb.Part{pb.NewTextPart("Run risk audit")},
},
})
if err != nil {
panic(err)
}
fmt.Printf("Task ID: %s, Response: %v\n", resp.TaskId, resp.Message)
}

6. A2A-to-OpenAI Compatibility Bridge​

Allows standard OpenAI Python/TypeScript/Go SDKs to orchestrate multi-agent workflows without changing client libraries by specifying model: "a2a/{agent_slug}".

cURL Request via Chat Completions​

curl -X POST http://localhost:8080/v1/chat/completions \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"model": "a2a/risk-analyst",
"messages": [
{"role": "user", "content": "Compute Value-at-Risk for Portfolio 4"}
]
}'

Multi-Turn Resumption (TASK_STATE_INPUT_REQUIRED)​

When an upstream agent requires clarifying input, GoRoute returns an assistant response with finish_reason: "stop" containing the agent's question. Callers resume execution simply by sending the next user turn back to model: "a2a/{agent_slug}"; GoRoute automatically reconciles conversational context with the active taskId.


7. Emergency Administrative Kill-Switch​

Administrators can instantly disable an agent across all cluster nodes using the control plane API:

curl -X POST http://localhost:8080/admin/v1/a2a/agents/agent_0192ab/kill-switch \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{ "killed": true }'

When tripped, subsequent invocations immediately fail-closed returning HTTP 503 agent_killed.


Next Steps​