Multi-Tenancy and Multi-Agent Routing
A single A2A endpoint can serve multiple agents or tenants. The A2A protocol does not prescribe a specific routing implementation, and operators are free to choose the approach that best fits their infrastructure. This page describes the routing mechanisms the protocol supports and the rules clients must follow when a routing identifier is advertised in an Agent Card.
Overview
A common deployment pattern places several agents behind a single host or reverse proxy. From the outside the agents are reachable at the same domain, but each one must be distinguished so requests reach the right backend.
Three complementary approaches are available:
1. URL-based routing (sub-path)
Each agent gets a distinct URL prefix. Each agent’s Agent Card advertises its own url in supportedInterfaces, so clients automatically send requests to the correct path.
Agent Card for the “billing” agent:
{
"name": "Billing Agent",
"supportedInterfaces": [
{
"url": "https://agents.example.com/billing",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0"
}
]
}Agent Card for the “support” agent:
{
"name": "Support Agent",
"supportedInterfaces": [
{
"url": "https://agents.example.com/support",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0"
}
]
}The gateway or reverse proxy routes /billing/* and /support/* to the appropriate backend. This is the simplest approach and requires no special client awareness beyond reading the Agent Card.
2. Authentication header-based routing
When multiple agents share the same URL, a gateway can use the authentication credentials already present in the request to decide where to route. Authentication requirements are declared in the Agent Card’s securitySchemes and related fields, which makes this approach fully discoverable by clients.
Examples:
- A bearer token whose claims (such as audience or scope) identify the target agent.
- An API key that maps to a particular agent in the gateway’s configuration.
The gateway inspects the credential and forwards the request to the appropriate backend without any change to the A2A protocol messages themselves.
3. Body-based routing with the tenant field
Every A2A request message has an optional tenant field. It is an opaque string whose value is defined entirely by the server operator; the protocol imposes no format or semantics on it. A gateway or agent implementation can inspect this field and forward the request to the appropriate backend.
The tenant value a client should use for a particular agent is advertised in the AgentInterface entry inside supportedInterfaces:
{
"name": "Billing Agent",
"supportedInterfaces": [
{
"url": "https://agents.example.com/a2a",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0",
"tenant": "billing"
}
]
}Client requirement: The client MUST always echo the tenant value from the selected AgentInterface entry in every request message. If the AgentInterface does not set tenant, the field MUST be omitted from the request. See the specification
for the normative rule.
In the HTTP+JSON binding, tenant can also appear as a path prefix, for example POST /{tenant}/message:send, alongside the tenant-less POST /message:send.
A server may use the tenant field to represent any routing key that suits its deployment: agent identifiers, workspace slugs, organization IDs, or any other opaque discriminator.
Combining approaches
The three approaches are not mutually exclusive. For example, a deployment could use URL-based routing to distinguish major product lines and rely on the tenant field to distinguish individual customers within each product line. The right combination depends on the operator’s architecture and the capabilities of the gateway in use.
Discovering multiple agents
When multiple agents are deployed behind a shared domain, each agent should have its own Agent Card published at an appropriate location (see Agent Discovery
). Clients retrieve each agent’s card independently and use the supportedInterfaces information it contains, including any tenant value, to communicate with the correct agent.