A2A OpenAI Bridge & gRPC Service
GoRoute AI Gateway enables seamless interoperability between autonomous A2A agents and existing AI application ecosystems:
- OpenAI Compatibility Bridge (
model: "a2a/{slug}"): Exposes autonomous agents over standardPOST /v1/chat/completions, allowing off-the-shelf OpenAI SDKs, LangChain, Cursor, Claude Code, and OpenWebUI to call A2A agents without custom protocol libraries. - Native gRPC Service (
lf.a2a.v1.A2AService): High-performance, low-latency Protobuf RPCs with server-side streaming designed for production microservice architectures.
1. OpenAI Compatibility Bridge (model: "a2a/{slug}")
The OpenAI Compatibility Bridge translates standard Chat Completions requests into A2A agent tasks, preserving conversational state, streaming SSE chunks, and enforcing tenant permissions.
Invoking an Agent via cURL
To invoke an agent named risk-analyst, simply set model to "a2a/risk-analyst":
curl -X POST "http://localhost:8080/v1/chat/completions" \
-H "Authorization: Bearer sk-gw-client-key" \
-H "Content-Type: application/json" \
-d '{
"model": "a2a/risk-analyst",
"messages": [
{
"role": "user",
"content": "Perform sensitivity analysis on portfolio beta under a 200bps rate hike."
}
],
"stream": false
}'
Response Format
The gateway formats the agent's task output into standard OpenAI response JSON:
{
"id": "chatcmpl_a2a_task_01928374",
"object": "chat.completion",
"created": 1731340800,
"model": "a2a/risk-analyst",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "### Portfolio Sensitivity Analysis\nUnder a 200bps rate increase, duration-sensitive fixed income assets experience an estimated 4.2% drawdown while high-dividend equity beta contracts by 0.15..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 38,
"completion_tokens": 154,
"total_tokens": 192
}
}
Python OpenAI SDK Integration
Existing code using the official openai Python package works without code changes:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="sk-gw-client-key"
)
# Call the autonomous agent directly
response = client.chat.completions.create(
model="a2a/risk-analyst",
messages=[
{"role": "user", "content": "Analyze supply chain risks for our automotive supplier portfolio."}
],
stream=True
)
for chunk in response:
content = chunk.choices[0].delta.content or ""
print(content, end="", flush=True)
Multi-Turn Resumption & Context Tracking
To continue an existing agent task across multiple turns, pass the task identifier via HTTP headers or metadata:
curl -X POST "http://localhost:8080/v1/chat/completions" \
-H "Authorization: Bearer sk-gw-client-key" \
-H "X-Gateway-Task-Id: task_01928374-abcd-ef01" \
-H "Content-Type: application/json" \
-d '{
"model": "a2a/risk-analyst",
"messages": [
{"role": "user", "content": "Re-run the previous stress test assuming high inflation persistency."}
]
}'
2. Native gRPC Service (lf.a2a.v1.A2AService)
For backend systems, microservices, and Kubernetes clusters requiring high-throughput binary serialization, GoRoute AI Gateway exposes the native Linux Foundation A2A gRPC service.
Protobuf Service Definition
syntax = "proto3";
package lf.a2a.v1;
service A2AService {
// Dispatches a message to an agent task
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
// Queries task status, current state, and artifacts
rpc GetTask(GetTaskRequest) returns (Task);
// Lists active tasks for the authenticated caller
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
// Signals cancellation to an in-flight agent task
rpc CancelTask(CancelTaskRequest) returns (Task);
// Real-time server-streaming of task progress events
rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamResponse);
// Webhook push notification configurations
rpc CreateTaskPushNotificationConfig(TaskPushNotificationConfig) returns (TaskPushNotificationConfig);
rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig);
rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (google.protobuf.Empty);
}
gRPC Authentication & Metadata
gRPC clients authenticate by including the standard VirtualKey Bearer token in the gRPC incoming metadata context:
md := metadata.Pairs(
"authorization", "Bearer sk-gw-client-key-prod",
"agent-slug", "risk-analyst",
)
ctx := metadata.NewOutgoingContext(context.Background(), md)
The gateway extracts the token, executes the 4-layer RBAC policy check, and attributes compute spend to the associated organization and team.
Server-Streaming Task Subscription Example (Go)
package main
import (
"context"
"fmt"
"io"
"log"
"github.com/goroute-ai/ai-gateway-go/internal/a2a/pb"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
"google.golang.org/grpc/metadata"
)
func main() {
conn, err := grpc.Dial("localhost:9090", grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
log.Fatalf("did not connect: %v", err)
}
defer conn.Close()
client := pb.NewA2AServiceClient(conn)
ctx := metadata.NewOutgoingContext(context.Background(), metadata.Pairs(
"authorization", "Bearer sk-gw-client-key-prod",
))
stream, err := client.SubscribeToTask(ctx, &pb.SubscribeToTaskRequest{
TaskId: "task_01928374",
AfterSeq: 0,
})
if err != nil {
log.Fatalf("subscribe failed: %v", err)
}
for {
event, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
log.Fatalf("stream error: %v", err)
}
fmt.Printf("[Seq %d] Event: %s, Payload: %s\n",
event.EventSeq, event.EventType, event.PayloadJson)
}
}
[!TIP] Use
lf.a2a.v1.A2AServicewhen building backend services that require sub-millisecond serialization overhead and high-volume parallel event streaming.