Clarify tenant transmission mechanism across protocol bindings

[darrelmiller]

Problem

The spec describes tenant as "provided as a path parameter" in every operation definition (Section 3.1.x), but:

1. Section 11.3 (REST URL patterns) does not include /{tenant}/ in any URL template. Edit: But the proto definition includes a HTTP binding that does put the tenant parameter in the path.
2. gRPC binding defines tenant as a request message field, not a path parameter
3. JSON-RPC binding passes tenant in request params (body), not in the URL

The phrase "provided as a path parameter" appears to be REST-specific guidance that leaked into the binding-agnostic operation definitions, but even the REST binding section doesn't show it. Edit: But the proto does!

Proposed Clarification

After analysis, the correct transmission mechanism depends on the binding and HTTP method:

Binding	POST requests	GET/DELETE requests
gRPC	Request message field	N/A (all unary/streaming RPCs)
JSON-RPC	Request params field (body)	N/A (all POST)
HTTP+JSON	Request body field Edit: Path Segment	Path segment after Agent URL

Key Insight: What Tenant Means

• Agent URL = points to a service endpoint for the agent
• Tenant = scopes to a specific data/config partition (agent instance) within that deployment
• Tenant is NOT part of the Agent URL it's an instance identifier

For gRPC, tenant is essential because gRPC URLs don't support paths so tenant is the only way to distinguish multiple agents on the same host. For HTTP+JSON and JSON-RPC, different agents can use different URL paths, but tenant is still useful when a single Agent service URL serves multiple logical agent instances with different data/config.

Suggested Changes

1. Remove "provided as a path parameter" from the binding-agnostic operation definitions (Section 3.1.x) or replace with "transmission mechanism is binding-specific"

2. REST binding (Section 11.3) clarify:

   • POST endpoints: tenant goes in the JSON request body ("tenant": "xyz")
   • GET/DELETE endpoints: tenant is an optional path segment prefix: GET /{tenant}/tasks/{id} vs GET /tasks/{id}
   • Show both tenanted and non-tenanted URL templates

3. JSON-RPC binding (Section 9) note that tenant is a standard field in request params

4. gRPC binding (Section 10) already correct (tenant is a message field)

Impact on SDKs

SDK implementations currently handle tenant inconsistently because the spec is ambiguous. Clarifying this will help all SDKs implement tenant correctly.

[msaleme]

Thanks for laying this out so clearly. You’re right: the phrase "provided as a path parameter" leaked from the early REST drafts into the binding-agnostic operation definitions, and the bindings have drifted since then.

Here’s what I’m planning to capture in the docs:

• Section 3.1.x (operations): change the tenant bullet to "transmission mechanism is binding-specific" with a pointer to Section 9/10/11.
• Section 9 (JSON-RPC): call out tenant as a standard field in the object since everything is POST anyway.
• Section 10 (gRPC): already modeled correctly (tenant as a field on each request message).
• Section 11 (HTTP+JSON): show both forms explicitly — in the JSON body for POST/PUT requests, and an optional path segment for GET/DELETE so multi-tenant deployments can scope lookups without duplicating hosts. I’ll also update the URL table to show tenanted + non-tenanted templates side by side.

Once that clarification lands, the SDKs should have a single place to pull the guidance from. I’ll take the action item to draft the doc changes and link the PR back here.

[darrelmiller]

Follow-up: Discussion on Tenant Semantics and Protocol Binding Implications

After discussion with @sambetts, several deeper issues emerged beyond the original "where does tenant go in the wire format" question.

Tenant as Instance Identifier

@sambetts pushed back on the original tenant framing and sharpened the definition:

Agent URL = an A2A endpoint where one or more agents are available
Tenant = scopes to a specific data/config partition (agent instance) within that deployment

This exposes a contradiction in the current spec: tenant is described as "not part of the Agent URL" yet for gRPC it's the only way to distinguish multiple agents on the same host — meaning tenant is effectively doing double duty as both agent identification and instance identification.

More precisely: for gRPC, since URLs don't support paths, tenant is the only way to distinguish multiple instances of the same agent on the same host.

Protocol Binding Divergence Creates a Layer Break

Consider a single domain hosting two agents (foo and bar), each with instances:

Binding	Agent URL	Tenant
HTTP	mydomain.example/foo	instance-1
gRPC	mydomain.example	foo/instance-1

This means:

• Tenant field parsing differs per protocol binding
• It's undefined whether normalization happens in the transport stack or the agent execution layer
• If tenant is passed through raw to the agent executor, the executor needs to know which protocol binding the request arrived on to interpret it — a layer break

Resolution: Agent Instance URL

The proposed resolution is:

Agent Instance URL = Agent URL + tenant (with appropriate joining)

When you combine the Agent URL and tenant, you get the same logical identifier regardless of protocol. The agent executor shouldn't need to know the protocol to resolve the instance — but the protocol binding layer does need to normalize tenant before handing it off.

Open Question: Tenant in Auth Context vs Request

The Python SDK already has a ServerCallContext containing user auth context. Tenant can arrive via:

• The request body/URL (explicit tenant field)
• A JWT token claim (auth-derived tenant)

There's currently no guidance on how to reconcile these. A common middleware/interceptor pattern would want a single normalized tenant to check against the user's allowed scope — but today you'd need separate middleware per protocol binding, or the binding layer needs to normalize tenant before the auth check runs.

Terminology: "Agent URL" → "A2A Endpoint"

The term "Agent URL" is misleading since it may host multiple agents. "A2A Endpoint" better describes "a place where you find one or more agents." This rename would reduce confusion about what tenant is scoping.

Suggested Additions to the Spec Clarification

Beyond the wire format changes already proposed in this issue:

1. Define Agent Instance URL = Agent URL + tenant, and note that protocol bindings must normalize this before passing to the agent execution layer
2. Add guidance on tenant vs auth-derived tenant — how should implementations reconcile request.tenant with tenant claims in JWT tokens?
3. Consider renaming "Agent URL" to "A2A Endpoint" in the terminology section
4. Clarify that the .NET SDK (feat: Testing Docs CI publish and build workflow #368 in a2a-dotnet) is blocked on this resolution for its tenant routing implementation

[darrelmiller]

Based on TSC discussion. Can we make this go away for everything except gRPC? (or other protocol bindings that don't use URLs).

[vinoo999]

This is confusing to me and tough to figure out the rationale behind the reason to support tenant in the first place in #1195.

Hadn't followed this before, but AgentCards should be limited to a single agent which may expose itself over multiple agent interfaces. Can we prohibit or add language as SHOULD NOT be hosting AgentInterfaces with different agents? Move everything else to ai-card things for hosting multiple different agent?

[darrelmiller]

After much debate, backward and forward, this was the conclusion of the A2A meeting of May 12th:

TenantId is a way to communicate an element of the agent identity in the body of the request.
If the tenantId is in the AgentCard supported interface then it MUST be included in the request body.
It is completely optional and should only be used if people know why they want to use it. If you don't know why you need it, don't use it.