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
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.

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	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. The .NET SDK (a2a-dotnet) has tenant properties on all request types but no plumbing to actually use them.

[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.