Design Proposal: Agent2Agent(A2A) Support in Envoy

This proposal presents the high-level design and ideas for supporting Agent2Agent(A2A) protocol in Envoy

# Background
## What is A2A?

[Agent2Agent(or A2A) protocol ](https://a2a-protocol.org/latest/) is an open protocol designed for dynamic and multi-modal agent collaboration. It aims to enable interoperability between different agent systems, even those built with varying frameworks or by different vendors.

The protocol supports capabilities discovery, communication modalities (text, forms, media) negotiation, task management, and agent collaboration. It is built on existing standards like HTTP, SSE, and JSON-RPC, and emphasizes enterprise-grade security and privacy.

## A2A and MCP
A2A ❤️ MCP: They are complementary Protocols for Agentic Systems. An agentic application might primarily use A2A to communicate with other agents. Each individual agent internally uses MCP to interact with its specific tools and resources.

# Design Details
At a high-level, the Envoy pattern for A2A can be a mixture of :
- Parsing: JSON-RPC Parser parses the request message (either for MCP or A2A) to extract necessary attributes
- Authentication: Validate the authentication of each request based on http header and/or own authentication requirement (e.g., SPIFEE ID)
- Authorization: Authorize the request specific to the agent's implementation, the data it handles, and applicable enterprise policies
- Observability: Leverage [OpenTelemetry support](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/opentelemetry.proto.html) in Envoy for distributed tracing and metrics collection.

## Parsing

A2A supports 3 major protocol bindings: JSON-RPC, gRPC, and HTTP/REST. Today, Envoy natively provides first class support for [gRPC](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_protocols/grpc) and HTTP/REST (e.g., RESTful routing, diverse REST verbs, and authentication mechanism).

This part focuses on the parsing mechanism for JSON-RPC, which follows [JSON-RPC 2.0](https://www.jsonrpc.org/) specification. JSON-RPC 2.0 lacks a direct mapping to HTTP semantics, such as method names are contained within the payload. Consequently, Envoy must perform streaming JSON parsing to extract these necessary attributes.

To streamline this, we propose a unified parsing architecture: a shared JSON-RPC library will handle core payload extraction for both A2A and MCP, while protocol-specific layers handle their respective unique attributes.

The architecture can be illustrated as diagram below:

## Agent Card Support

AgentCard is a plain JSON file that details agents’ specific functionalities. It enables agents to discover and understand an agent's specific capabilities. A2A support three discovery strategies with GET requests: 1) Well-Known URI 2) Curated Registries 3) Private Discovery

1. Route to agent card service

The agent card is at https:///.well-known/agent-card.json and can be retrieved via a GET request. Envoy, as a proxy, handles the routing and cluster selection by its router filter based on route match, like the config example below:
```
virtual_hosts:
- name: agent_service
domains: [ "base_url:*"]
routes:
- match:
path: "/.well-known/agent-card.json"
headers:
- name: ":method"
exact_match: "GET"
route:
cluster: agent_card_backend
clusters:
- name: agent_card_backend
.....

```

Since agent cards are usually small and bounded, we can leverage existing JSON parsing ability(Envoy::Json::Factory) to parse the agent card response. Then we can identify the URL for routing and security requirements for authentication/authorization.

2. Agent Card Registry

It can be achieved via xDS or ext_proc. For example, the control plane or ext_proc server acts as the "Source of Truth" for the Agent Cards. When a new agent is registered, the control Plane sends a DiscoveryResponse containing the new Agent Card JSON or ext_proc server sends a ProcessingResponse.

3. Static Agent Card

Options described above are dynamic approaches. For simple deployment or the production environment where the agents are part of the infrastructure, the agent card can be provided via static config. For example, embedding the agent card into the direct response for that route

```
virtual_hosts:
name: agent_service
domains: ["*"]
routes:
# 1. Direct Response for Agent Card Discovery
- match:
path: "/.well-known/agent-card.json"
direct_response:
status: 200
body:
# Valid A2A Agent Card JSON
inline_string: |
{
"name": "finance-agent",
"description": "Market analysis agent",
"url": "https://api.yourdomain.com/v1/a2a",
"version": "1.0.0",
"capabilities": {
"streaming": true
},
"skills": [
{
"name": "get_stock_price",
"description": "Returns current price for a ticker"
}
]
}
# Required headers for A2A compliance
response_headers_to_add:
- header: { key: "Content-Type", value: "application/json" }
- header: { key: "Access-Control-Allow-Origin", value: "*" }
```

## Authentication and Authorization

A2A (or Agentic AI protocols in general) leverages well-established web security standards. Within this framework, identity details are managed at the protocol layer. More specifically in A2A, remote agents advertise its capabilities, identity, and requirements via [Agent Card](https://a2a-protocol.org/latest/tutorials/python/3-agent-skills-and-card/#agent-card). It supports various standard mechanisms below:
- mTLS
- OAuth 2.0 ([RFC6749](https://www.rfc-editor.org/rfc/rfc6749))
- OpenID Connect (OIDC)
- API Keys

The high-level system design for the aforementioned security and authorization mechanisms can be achieved by leveraging Envoy’s enterprise-grade extension ecosystem- such as SPIFFE CertValidator, ext_authz, and authentication filters (JWT/OAuth 2.0) etc - supplemented by targeted enhancements (e.g., https://github.com/envoyproxy/envoy/issues/41974)

For example, the sequence diagram for Identity-Based Security via SPIFFE-mTLS and Policy Enforcement:

# Acknowledgments
This proposal incorporates discussion and input from @botengyao @abeyad @yanavlasov @yangfanud

We highly value the community's perspective and welcome further insights, feedback, and ideas as we refine our strategy, evolve the design, and iron out the remaining details.