feat(server)!: add multitenancy support with per-tenant routing · a2aproject/a2a-java@c175054 · GitHub
Skip to content

Commit c175054

Browse files
ehsavoieehsavoie
committed
feat(server)!: add multitenancy support with per-tenant routing
- Add AgentExecutorRouter and AgentCardRouter SPI in server-common - Add @tenant CDI qualifier and CDI router implementations in extras/multitenancy - Wire tenant-aware resolution in DefaultRequestHandler and all transport handlers - Add tenant field to RequestContext for execute/cancel flows - Update GetExtendedAgentCardRequest to carry GetExtendedAgentCardParams Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent ef09aeb commit c175054

61 files changed

Lines changed: 2609 additions & 222 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎boms/extras/pom.xml‎

Lines changed: 5 additions & 0 deletions

‎boms/extras/src/it/extras-usage-test/pom.xml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,10 @@
8888
<groupId>org.a2aproject.sdk</groupId>
8989
<artifactId>a2a-java-queue-manager-replication-mp-reactive</artifactId>
9090
</dependency>
91+
<dependency>
92+
<groupId>org.a2aproject.sdk</groupId>
93+
<artifactId>a2a-java-extras-multitenancy</artifactId>
94+
</dependency>
9195

9296
<!-- Core SDK modules (inherited from SDK BOM via Extras BOM) -->
9397
<dependency>

‎client/transport/grpc/src/main/java/org/a2aproject/sdk/client/transport/grpc/GrpcTransport.java‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
import org.a2aproject.sdk.spec.TaskIdParams;
4949
import org.a2aproject.sdk.spec.TaskPushNotificationConfig;
5050
import org.a2aproject.sdk.spec.TaskQueryParams;
51+
import org.a2aproject.sdk.spec.util.Utils;
5152
import io.grpc.Channel;
5253
import io.grpc.Metadata;
5354
import io.grpc.StatusException;
@@ -84,6 +85,9 @@ public GrpcTransport(Channel channel, AgentCard agentCard, @Nullable String agen
8485
this.blockingStub = A2AServiceGrpc.newBlockingV2Stub(channel);
8586
this.agentCard = agentCard;
8687
this.interceptors = interceptors;
88+
if (agentTenant != null && !agentTenant.isBlank()) {
89+
Utils.validateTenant(agentTenant);
90+
}
8791
this.agentTenant = agentTenant == null || agentTenant.isBlank() ? "" : agentTenant;
8892
}
8993

@@ -352,11 +356,9 @@ private MessageSendParams createRequestWithTenant(MessageSendParams request) {
352356

353357
@Override
354358
public AgentCard getExtendedAgentCard(GetExtendedAgentCardParams params, @Nullable ClientCallContext context) throws A2AClientException {
355-
GetExtendedAgentCardRequest.Builder builder = GetExtendedAgentCardRequest.newBuilder();
356-
if (params.tenant() != null) {
357-
builder.setTenant(params.tenant());
358-
}
359-
GetExtendedAgentCardRequest request = builder.build();
359+
GetExtendedAgentCardRequest request = GetExtendedAgentCardRequest.newBuilder()
360+
.setTenant(resolveTenant(params.tenant()))
361+
.build();
360362
PayloadAndHeaders payloadAndHeaders = applyInterceptors(GET_EXTENDED_AGENT_CARD_METHOD, request, agentCard, context);
361363

362364
try {

‎client/transport/jsonrpc/src/main/java/org/a2aproject/sdk/client/transport/jsonrpc/JSONRPCTransport.java‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ public EventKind sendMessage(MessageSendParams request, @Nullable ClientCallCont
9898
agentCard, context);
9999

100100
try {
101-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, SEND_MESSAGE_METHOD);
101+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, SEND_MESSAGE_METHOD);
102102
SendMessageResponse response = unmarshalResponse(httpResponseBody, SEND_MESSAGE_METHOD);
103103
return response.getResult();
104104
} catch (A2AClientException e) {
@@ -120,7 +120,7 @@ public void sendMessageStreaming(MessageSendParams request, Consumer<StreamingEv
120120
SSEEventListener sseEventListener = new SSEEventListener(eventConsumer, errorConsumer);
121121

122122
try {
123-
A2AHttpClient.PostBuilder builder = createPostBuilder(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, SEND_STREAMING_MESSAGE_METHOD);
123+
A2AHttpClient.PostBuilder builder = createPostBuilder(agentInterface.url(), payloadAndHeaders, SEND_STREAMING_MESSAGE_METHOD);
124124
ref.set(builder.postAsyncSSE(
125125
event -> sseEventListener.onMessage(event, ref.get()),
126126
throwable -> sseEventListener.onError(throwable, ref.get()),
@@ -144,7 +144,7 @@ public Task getTask(TaskQueryParams request, @Nullable ClientCallContext context
144144
agentCard, context);
145145

146146
try {
147-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, GET_TASK_METHOD);
147+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, GET_TASK_METHOD);
148148
GetTaskResponse response = unmarshalResponse(httpResponseBody, GET_TASK_METHOD);
149149
return response.getResult();
150150
} catch (A2AClientException e) {
@@ -161,7 +161,7 @@ public Task cancelTask(CancelTaskParams request, @Nullable ClientCallContext con
161161
agentCard, context);
162162

163163
try {
164-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, CANCEL_TASK_METHOD);
164+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, CANCEL_TASK_METHOD);
165165
CancelTaskResponse response = unmarshalResponse(httpResponseBody, CANCEL_TASK_METHOD);
166166
return response.getResult();
167167
} catch (A2AClientException e) {
@@ -177,7 +177,7 @@ public ListTasksResult listTasks(ListTasksParams request, @Nullable ClientCallCo
177177
PayloadAndHeaders payloadAndHeaders = applyInterceptors(LIST_TASK_METHOD, ProtoUtils.ToProto.listTasksParams(request),
178178
agentCard, context);
179179
try {
180-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, LIST_TASK_METHOD);
180+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, LIST_TASK_METHOD);
181181
ListTasksResponse response = unmarshalResponse(httpResponseBody, LIST_TASK_METHOD);
182182
return response.getResult();
183183
} catch (IOException | InterruptedException | JsonProcessingException e) {
@@ -193,7 +193,7 @@ public TaskPushNotificationConfig createTaskPushNotificationConfiguration(TaskPu
193193
ProtoUtils.ToProto.createTaskPushNotificationConfigRequest(request), agentCard, context);
194194

195195
try {
196-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, SET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
196+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, SET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
197197
CreateTaskPushNotificationConfigResponse response = unmarshalResponse(httpResponseBody, SET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
198198
return response.getResult();
199199
} catch (A2AClientException e) {
@@ -211,7 +211,7 @@ public TaskPushNotificationConfig getTaskPushNotificationConfiguration(GetTaskPu
211211
ProtoUtils.ToProto.getTaskPushNotificationConfigRequest(request), agentCard, context);
212212

213213
try {
214-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, GET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
214+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, GET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
215215
GetTaskPushNotificationConfigResponse response = unmarshalResponse(httpResponseBody, GET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
216216
return response.getResult();
217217
} catch (A2AClientException e) {
@@ -230,7 +230,7 @@ public ListTaskPushNotificationConfigsResult listTaskPushNotificationConfigurati
230230
ProtoUtils.ToProto.listTaskPushNotificationConfigsRequest(request), agentCard, context);
231231

232232
try {
233-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, LIST_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
233+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, LIST_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
234234
ListTaskPushNotificationConfigsResponse response = unmarshalResponse(httpResponseBody, LIST_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
235235
return response.getResult();
236236
} catch (A2AClientException e) {
@@ -248,7 +248,7 @@ public void deleteTaskPushNotificationConfigurations(DeleteTaskPushNotificationC
248248
ProtoUtils.ToProto.deleteTaskPushNotificationConfigRequest(request), agentCard, context);
249249

250250
try {
251-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, DELETE_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
251+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, DELETE_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
252252
DeleteTaskPushNotificationConfigResponse response = unmarshalResponse(httpResponseBody, DELETE_TASK_PUSH_NOTIFICATION_CONFIG_METHOD);
253253
// Response validated (no error), but no result to return
254254
} catch (A2AClientException e) {
@@ -270,7 +270,7 @@ public void subscribeToTask(TaskIdParams request, Consumer<StreamingEventKind> e
270270
SSEEventListener sseEventListener = new SSEEventListener(eventConsumer, errorConsumer);
271271

272272
try {
273-
A2AHttpClient.PostBuilder builder = createPostBuilder(Utils.buildBaseUrl(agentInterface, request.tenant()), payloadAndHeaders, SUBSCRIBE_TO_TASK_METHOD);
273+
A2AHttpClient.PostBuilder builder = createPostBuilder(agentInterface.url(), payloadAndHeaders, SUBSCRIBE_TO_TASK_METHOD);
274274
ref.set(builder.postAsyncSSE(
275275
event -> sseEventListener.onMessage(event, ref.get()),
276276
throwable -> sseEventListener.onError(throwable, ref.get()),
@@ -294,7 +294,7 @@ public AgentCard getExtendedAgentCard(GetExtendedAgentCardParams params, @Nullab
294294
ProtoUtils.ToProto.extendedAgentCard(params), agentCard, context);
295295

296296
try {
297-
String httpResponseBody = sendPostRequest(Utils.buildBaseUrl(agentInterface, params.tenant()), payloadAndHeaders, GET_EXTENDED_AGENT_CARD_METHOD);
297+
String httpResponseBody = sendPostRequest(agentInterface.url(), payloadAndHeaders, GET_EXTENDED_AGENT_CARD_METHOD);
298298
GetExtendedAgentCardResponse response = unmarshalResponse(httpResponseBody, GET_EXTENDED_AGENT_CARD_METHOD);
299299
return response.getResult();
300300
} catch (IOException | InterruptedException | JsonProcessingException e) {

‎docs/content/dev/extras.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,10 @@ JPA-backed replacements for the in-memory stores, providing database persistence
4040

4141
Replaces the default `InMemoryQueueManager` with event replication across multiple A2A server instances via message brokers. Required for multi-instance deployments. The core module (`a2a-java-queue-manager-replicated-core`) pairs with a MicroProfile Reactive Messaging strategy (`a2a-java-queue-manager-replication-mp-reactive`) supporting Apache Kafka, Pulsar, or AMQP. You can also write your own `ReplicationStrategy`.
4242

43+
## [Multi-Tenancy](multi-tenancy)
44+
45+
Serve multiple tenants from a single A2A server with per-tenant `AgentExecutor` and `AgentCard` routing. The module (`a2a-java-extras-multitenancy`) provides a `@Tenant` CDI qualifier and automatic routing — requests are dispatched to tenant-specific beans based on the `tenant` field in the request payload, with fallback to the default beans for unknown tenants.
46+
4347
## [OpenTelemetry](../extra/opentelemetry)
4448

4549
Distributed tracing, metrics, and context propagation for A2A servers and clients using OpenTelemetry. The server module (`a2a-java-sdk-opentelemetry-server`) adds automatic span creation for all protocol methods with context propagation across async boundaries. Client modules (`a2a-java-sdk-opentelemetry-client`, `a2a-java-sdk-opentelemetry-client-propagation`) instrument A2A client operations.

‎docs/content/dev/multi-tenancy.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Multi-Tenancy
3+
description: Serve multiple tenants from a single A2A server — per-tenant AgentExecutor and AgentCard routing with CDI qualifiers.
4+
layout: page
5+
---
6+
7+
# Multi-Tenancy
8+
9+
Multi-tenancy lets a single A2A server provide different agent behavior per tenant. Each tenant can have its own `AgentExecutor` (business logic) and extended `AgentCard` (capabilities, skills, metadata). Requests without a tenant — or with an unknown tenant — fall back to the default beans automatically.
10+
11+
## Setup
12+
13+
Add the multitenancy extras module:
14+
15+
```xml
16+
<dependency>
17+
<groupId>org.a2aproject.sdk</groupId>
18+
<artifactId>a2a-java-extras-multitenancy</artifactId>
19+
</dependency>
20+
```
21+
22+
> **Tip:** Use the [extras BOM](boms) to manage the version.
23+
24+
No code changes are needed in the server itself — the module activates automatically via CDI when present on the classpath.
25+
26+
## Declaring Per-Tenant Beans
27+
28+
Use the `@Tenant` qualifier to declare tenant-specific producers:
29+
30+
```java
31+
@ApplicationScoped
32+
public class MultiTenantConfig {
33+
34+
// Default executor — used for unknown tenants and requests with no tenant
35+
@Produces
36+
public AgentExecutor defaultExecutor() {
37+
return new DefaultAgentExecutor();
38+
}
39+
40+
// Tenant-specific executor — used when params.tenant == "acme"
41+
@Produces
42+
@Tenant("acme")
43+
public AgentExecutor acmeExecutor() {
44+
return new AcmeAgentExecutor();
45+
}
46+
47+
// Default extended agent card (no @Tenant qualifier)
48+
@Produces
49+
@ExtendedAgentCard
50+
public AgentCard defaultExtendedCard() {
51+
return AgentCard.builder()
52+
.name("Default Agent")
53+
.description("Default agent for all tenants")
54+
// ...
55+
.build();
56+
}
57+
58+
// Tenant-specific extended agent card
59+
@Produces
60+
@Tenant("acme")
61+
@ExtendedAgentCard
62+
public AgentCard acmeExtendedCard() {
63+
return AgentCard.builder()
64+
.name("Acme Agent")
65+
.description("Specialized agent for Acme Corp")
66+
// ...
67+
.build();
68+
}
69+
}
70+
```
71+
72+
## Fallback Behavior
73+
74+
When a request arrives with a `tenant` value:
75+
76+
1. The router looks for a bean qualified with `@Tenant("value")`
77+
2. If found, that tenant-specific bean is used
78+
3. If not found, the **unqualified default** bean is used
79+
80+
A `null`, blank, or missing tenant always resolves to the default bean. Unknown tenants also fall back to the default — they do not produce an error.
81+
82+
This means single-tenant deployments (no `@Tenant` beans) continue to work unchanged when the module is on the classpath.
83+
84+
## Tenant Source
85+
86+
The tenant is read from the **request payload** — the `tenant` field in JSON-RPC params (e.g. `MessageSendParams.tenant()`, `CancelTaskParams.tenant()`) and protobuf request messages. For the REST transport, the tenant can also be extracted from the URL path (e.g. `/\\{tenant}/extendedAgentCard`); the payload value takes precedence when both are present.
87+
88+
A tenant must be a **simple identifier** — only `a-zA-Z0-9_-.` characters are allowed. Path elements like `/` and `?` are rejected.
89+
90+
Both the execute and cancel flows propagate the tenant to the `RequestContext`, so `AgentExecutor` implementations can access it via `context.getTenant()`.
91+
92+
## Per-Tenant Agent Cards
93+
94+
### Extended Agent Card
95+
96+
The `getExtendedAgentCard` method is tenant-aware. When the multitenancy module is present:
97+
98+
- A request with `tenant: "acme"` returns the `@Tenant("acme") @ExtendedAgentCard` card
99+
- A request with no tenant or an unknown tenant returns the default `@ExtendedAgentCard` card
100+
101+
This works across all transports (JSON-RPC, gRPC, REST).
102+
103+
### Public Agent Card
104+
105+
The public agent card is also tenant-aware via the URL path `/.well-known/\\{tenant}/agent-card.json`. To provide a tenant-specific public card, declare a producer with only the `@Tenant` qualifier (do **not** add `@PublicAgentCard` — that would cause CDI ambiguity):
106+
107+
```java
108+
// Tenant-specific public agent card
109+
@Produces
110+
@Tenant("acme")
111+
public AgentCard acmePublicCard() {
112+
return AgentCard.builder()
113+
.name("Acme Agent")
114+
.description("Acme-specific public card")
115+
// ...
116+
.build();
117+
}
118+
```
119+
120+
- `GET /.well-known/agent-card.json` always returns the default `@PublicAgentCard` card
121+
- `GET /.well-known/acme/agent-card.json` returns the `@Tenant("acme")` card, or falls back to the default if none is configured
122+
123+
## Without the Module
124+
125+
When the `extras/multitenancy` module is **not** on the classpath, no routers are registered. The server behaves exactly as a single-tenant deployment:
126+
127+
- The default `AgentExecutor` handles all requests
128+
- The default `@ExtendedAgentCard` card is returned for `getExtendedAgentCard`
129+
- The `tenant` field in request payloads is silently ignored
130+
131+
## Limitations
132+
133+
- **TaskStore and QueueManager are shared** across tenants — tasks are keyed by UUID, not partitioned by tenant
134+
- **Per-tenant TaskAuthorizationProvider** is not yet supported — the single `TaskAuthorizationProvider` applies to all tenants
135+
- **Public agent card** — Tenant-specific public cards use `@Tenant` without `@PublicAgentCard` due to CDI qualifier matching constraints (see [Per-Tenant Agent Cards](#per-tenant-agent-cards))

‎docs/content/dev/server.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,10 @@ public class CloseStreamsHook implements TaskStreamLifecycleHook {
223223

224224
See the [`examples/stream-lifecycle`](https://github.com/a2aproject/a2a-java/tree/main/examples/stream-lifecycle) directory for a complete working example with server, client, and integration tests for all three transports.
225225

226+
## Multi-Tenancy (Optional)
227+
228+
Serve multiple tenants from a single server with per-tenant `AgentExecutor` and `AgentCard` beans. See [Multi-Tenancy](multi-tenancy) for setup and configuration.
229+
226230
## Observability (Optional)
227231

228232
Add distributed tracing to your server with the [OpenTelemetry extras module](extra/opentelemetry). It decorates the request handler to create spans for every A2A protocol method, with automatic error tracking and optional request/response extraction.

‎docs/data/versions/dev.yml‎

Lines changed: 3 additions & 0 deletions

0 commit comments

Comments
 (0)