fix(spec): Add clarification about multi-tenancy support and tenant field usage in Agent Cards

[darrelmiller]

Problem Statement

The specification currently lacks clear guidance on how multi-tenancy should be handled in A2A, particularly regarding the tenant field in Agent Cards. This has led to confusion about:

1. Whether Agent Cards should list multiple AgentInterface entries for different tenants
2. How the tenant field should be used across different protocol bindings (gRPC vs HTTP+JSONRPC)
3. The distinction between multi-tenancy (same agent, different data/permissions) and multi-hosting (different agents on the same host)

Background

The tenant field was introduced to accommodate protocol-specific requirements, particularly gRPC's URL structure limitations. However, its purpose and usage patterns need clearer documentation.

Key Confusion Points

1. Agent Card Structure: Should a public Agent Card contain multiple AgentInterface entries for different tenants? This seems problematic because:

   • The preferred protocol binding is at index 0, which would incorrectly suggest the Agent has a preference over which tenant the client should use
   • Agent Cards shouldn't be used for tenant discovery

2. Protocol Binding Differences:

   • For HTTP/JSONRPC: Clients expect to get the root path and append /<tenant>/<operation>
   • For gRPC: Clients need to add the tenant into the operation call
   • The tenant field in gRPC supportedInterfaces is essentially breaking down the URL into two pieces due to gRPC's design

3. Multi-tenancy vs Multi-hosting:

   • Multi-tenancy: Same agent hosted in different tenants with access to different data or permission rights
   • Multi-hosting: Completely different agents living on the same host
   • Are we solving both with the same field?

Proposed Clarifications

The specification should include:

1. Clear Definition: A paragraph explaining that:

   • Multi-tenancy is a first-class supported concept in A2A
   • The tenant field serves both multi-tenancy and multi-hosting scenarios
   • From a client perspective, these are treated the same way (separate agents)

2. Agent Card Guidelines:

   • One Agent Card should represent one specific agent instance (including tenant context)
   • Agent Cards should NOT list multiple interfaces for different tenants
   • For agents that support multiple tenants, each tenant should have its own Agent Card

3. Protocol-Specific Handling:

   • Document how each protocol binding should handle the tenant field
   • Consider whether tenant should be an explicit optional property in supportedInterfaces rather than buried in protocolParameters

Example Structure Discussion

Current consideration for representing tenant information:

{
  "supportedInterfaces": [{
    "url": "https://service.acme.org:8102",
    "protocolBinding": "GRPC",
    "tenant": "/project/123/agent/345"
   },
   {
    "url": "https://service.acme.org/project/123/agent/345",
    "protocolBinding": "HTTP+JSON"
   }
  ]
}

Alternative with protocol parameters:

{
  "supportedInterfaces": [{
    "url": "https://service.acme.org:8102",
    "protocolBinding": "GRPC",
    "protocolParameters": {
      "tenant": "/project/123/agent/345"
    }
   },
   {
    "url": "https://service.acme.org/project/123/agent/345",
    "protocolBinding": "HTTP+JSON"
   }
  ]
}

Recommendation

If multi-tenancy is acknowledged as a first-class supported concept in A2A, the tenant field should live as an optional property directly in supportedInterfaces rather than being buried in a map of protocolParameters.

Acceptance Criteria

• Add a dedicated section or paragraph in the specification explaining multi-tenancy support
• Clarify the distinction between multi-tenancy and multi-hosting
• Document how clients should handle tenant fields across different protocol bindings
• Provide clear guidance on Agent Card structure for multi-tenant scenarios
• Decide on the final structure for representing tenant information (direct field vs protocolParameters)

References

Related discussion from team conversation on December 4, 2025. https://discord.com/channels/1362108044737253548/1362204426365833347/1446152799376248922

[mindcrime]

I wish I'd found this sooner. This does slightly deviate from how I'd (naively) thought the "tenant" field would be used. Or at least I think it does.

I almost want to ask for a way to add arbitrary additional metadata to the AgentInterface, so that client Agents (or middleware in the flow) can have "hints" to help choose Interfaces. But maybe I'm going about this wrong. Let me lay out what I'm doing and maybe you folks can tell me a better way to think about this.

I have an environment for hosting Agents. It could be a Docker Swarm cluster, Kubernetes cluster, Mesos, whatever. And in that environment, there is an "auto-registration" module that listens for new Container events and when it sees a new Agent container spin up, it grabs the AgentCard and stores it with the AgentRegistry. But before storing the AgentCard, it also creates two Routes using APISIX - one for client Agents colocated in the same cluster/swarm and one for client Agents from "outside". And it takes that Route information and munges the AgentCard to have two AgentInterface objects, one with the "uri" set to the "internal" Route and one with the "uri" set to the "external" Route. I had thought to use the "tenant" field with corresponding values of "internal" and "external" to discriminate these Interfaces.

For initial testing I'm actually letting the client choose the AgentInterface to use, so my instinct is to want an easy way to explicitly tell the Client class which AgentInterface to use. But that's temporary so that's really neither here nor there I guess. But long-term, I had thought the Registry would further munge the AgentCard at query time, to return only the desired AgentInterface in the AgentCard that is rendered. But I'd still thought it would rely on that "internal" vs "external" distinction as captured in the "tenant" field.

Now I'm getting the idea that this is wrong. Is the best answer to turn the one AgentCard with two AgentInterfaces into two AgentCards with just one AgentInterface apiece? I suppose if I do that the "internal" vs "external" notion never has to actually appear in the AgentCard at all, but can just be a database field in the Registry db, that the query time logic uses.