feat: native multi-agent support via MultiAgentRegistry by malladinagarjuna2 · Pull Request #1031 · a2aproject/a2a-java

malladinagarjuna2 · 2026-08-09T23:44:57Z

Overview

This PR introduces native support for deploying multiple Server Agents within a single Quarkus application instance for the reference-jsonrpc extension, resolving the operational overhead of 1:1 Kubernetes pod mappings.

Fixes #898

Changes

MultiAgentRegistry Interface: Introduced a registry interface that users can implement as a CDI bean to provide a map of agentId to JSONRPCHandler.
Dynamic Routing in A2AServerRoutes: The server router now checks for the presence of a MultiAgentRegistry. If found, it iterates over all registered agents and dynamically creates Vert.x routes for /{agentId} and /{agentId}/.well-known/agent-card.json.
Backward Compatibility: If no registry is provided, the router falls back to the default single-agent singleton behavior (/ and /.well-known/agent-card.json).

This allows production deployments to scale infinitely to hundreds of agents in a single JVM with zero custom routing code.

This adds native support for multiple agents in the reference-jsonrpc Quarkus extension. If a CDI bean implements MultiAgentRegistry, the A2AServerRoutes will automatically dynamically register endpoints for each agent, mapping '/{agentId}' to its JSONRPCHandler and '/{agentId}/.well-known/agent-card.json'.

kabir

Thanks for the PR :-) The MultiAgentRegistry approach is interesting.

A few things to address before this can be merged:

Support for all transports (REST, gRPC), not just JSON-RPC — as noted inline
The tenant extraction / agent ID path conflict
Compile issues in the tests

It would also be interesting to see if this could be enhanced with @mescaja's database-driven approach from #898 (comment) — either in this PR or as a follow-up.

kabir · 2026-08-11T09:38:24Z

+    Instance<JSONRPCHandler> jsonRpcHandler;
+
+    @Inject
+    Instance<org.a2aproject.sdk.server.apps.quarkus.registry.MultiAgentRegistry> multiAgentRegistry;


Use an import

fixed, now it imports multiagentresgistry instead of using the fully-qualified name

kabir · 2026-08-11T09:43:39Z

+                String pathPrefix = "/" + agentId;
+                registerAgentRoutes(router, pathPrefix, entry.getValue());
+            }
+        } else if (!jsonRpcHandler.isUnsatisfied()) {


Better to use isResolvable()

replaced both !isUnsatisfied() checks (this one and the jsonRpcHandler one right below it) with isResolvable(), since isUnsatisfied() doesn't catch the ambiguous-resolution case (.get() would throw AmbiguousResolutionException).

kabir · 2026-08-11T09:44:54Z

+    /**
+     * @return a map of agent ID (path segment) to their JSONRPCHandler
+     */
+    Map<String, JSONRPCHandler> getAgents();


We should also include the other transports

extended the same MultiAgentRegistry pattern to REST (routes registered under //...) and gRPC (dispatched via a new X-A2A-Agent-Id metadata header, since gRPC has no per-path routing). Also verified live locally ,JSON-RPC calls to two different registered agents each get routed to and served by their own handler correctly.

kabir · 2026-08-11T09:53:54Z

+    }
+
+    private void registerAgentRoutes(Router router, String pathPrefix, JSONRPCHandler handler) {
+        String rpcPath = pathPrefix.isEmpty() ? "/" : pathPrefix;


The tenant extraction will conflict with multi-agent routing. extractTenant() reads the normalized path, so a request to POST /myagent would return "myagent" as the tenant. The agent ID prefix needs to be stripped before tenant extraction — registerAgentRoutes should pass the pathPrefix length so extractTenant can skip it, or use a Vert.x path parameter (e.g. /:agentId/*) instead of a fixed path.

went with your suggestion: registerAgentRoutes now stores the reistered path prefix on the routing context, and extractTenant() strips it before computing the tenant from the remaining path. So POST/myagent now correctly resolves to an empty tentant instead of treating "myagent" as the tenant.

- Import MultiAgentRegistry instead of using its fully-qualified name - Use Instance.isResolvable() instead of !isUnsatisfied(), which also matches on ambiguous (multi-bean) resolution and would throw on get() - Strip the registered agent path prefix before computing the tenant, so a request to POST /myagent no longer treats "myagent" as the tenant - Fix pre-existing test compile errors (isUnsatisfied()/get() stubbed on the wrong mock) and the resulting compile break in MultiVersionJSONRPCRoutes, which still called the old 2-arg invokeJSONRPCHandler

Mirrors the JSON-RPC MultiAgentRegistry pattern across REST and gRPC: - REST: MultiAgentRegistry (Map<String, RestHandler>), routes each agent under /<agentId>/ with the ID as a literal regex prefix ahead of the tenant capture group. - gRPC: MultiAgentRegistry (Map<String, GrpcAgent>), dispatches by a new X-A2A-Agent-Id metadata header, falling back to the default single-agent beans when absent/unknown. Also fixes the compile break this causes in MultiVersionRestRoutes.

Signed-off-by: malladi nagarjuna <zombmalladinags69@gmail.com>

malladinagarjuna2 · 2026-08-15T12:26:43Z

@kabir thanks for the review. All four points are addressed, details below, plus a note on the database-driven follow-up.

Support for all transports

MultiAgentRegistry now exists for all three:

JSON-RPC — Map<String, JSONRPCHandler>, routes registered under /<agentId>/ and /<agentId>/.well-known/agent-card.json
REST — Map<String, RestHandler>, same path scheme
gRPC — Map<String, GrpcAgent>, dispatched on the X-A2A-Agent-Id metadata header, since gRPC has no per-path routing. GrpcAgent bundles the card, optional extended card, and request handler. Calls with no header, or naming an unregistered agent, fall back to the single-agent beans if those are configured.

In every transport the registry bean is optional: if no MultiAgentRegistry is resolvable, the server behaves exactly as before.

Tenant extraction / agent ID path conflict

Fixed as you suggested. registerAgentRoutes stores the registered path prefix on the RoutingContext (a2aAgentPathPrefix), and extractTenant() strips it before computing the tenant from the remaining path. So POST /myagent now resolves to an empty tenant instead of treating myagent as the tenant, and POST /myagent/tenant1 resolves to tenant tenant1.

isResolvable()

Both !isUnsatisfied() checks are now isResolvable(). isUnsatisfied() doesn't catch the ambiguous-resolution case, where the subsequent .get() would throw AmbiguousResolutionException.

Test compile issues

Resolved. A2AServerRoutesTest (JSON-RPC and REST) and the new QuarkusGrpcHandlerTest cover multi-agent registration, per-agent routing, and single-agent fallback.

On @mescaja's database-driven approach, and @omatheusmesmo's capabilities question

One thing worth making explicit, since it came up in #898: the capabilities problem doesn't apply to this design. @omatheusmesmo noted that the handlers gate operations on a single resolved card:

if (!resolveAgentCard().capabilities().streaming()) { ... }

In registry mode each registered agent has its own handler instance carrying its own AgentCard, and those checks read that instance's card. So streaming, pushNotifications, extendedAgentCard, and the protocol-version validation are all per-agent — N agents in one app do not share capabilities. The gRPC path resolves the card per-call from the header for the same reason.

On the database-driven card store: I'd prefer to keep it out of this PR and do it as a follow-up. It's a different concern , this PR is about routing requests to the right handler, whereas @mescaja's approach and @ehsavoie's suggestion of an extras module are both about storing and serving cards, which the spec covers under Registries/Catalogs (§8.2). The two compose rather than compete: an application can already back its MultiAgentRegistry implementation with a database today, since it's just a CDI bean returning a map. A card-store extras module would slot in underneath without changing anything here.

mescaja · 2026-08-15T12:58:13Z

thanks a lot @malladinagarjuna2. It's a nice feature that you put together that will simplify the handling of multiple AgentCard. For more complex enterprise agentic platform that requires deploy agent at scale both corporate and remote one i think other options would be preferred in my view.

Sorry to ask you for a favor but it'd appreciate if you could have a look at this ticket i raised yesterday which i believe it's a critical one and have your view on it. Not expecting to pick it up straightaway if it's a bug, just quick little look and let me know your thoughts.
#1068

malladinagarjuna2 · 2026-08-15T13:55:45Z

well @mescaja thanks a lot

sure will have a look on #1068.

malladinagarjuna2 · 2026-08-18T11:23:24Z

@kabir could you please review it

kabir mentioned this pull request Aug 11, 2026

docs: add multi-agent reference architecture #1030

Closed

kabir requested changes Aug 11, 2026

View reviewed changes

malladinagarjuna2 added 4 commits August 13, 2026 20:48

merge upstream/main into feat-multi-agent-support

a9900d9

fix: resolve javadoc doclint failures blocking release-profile CI

72a5380

Signed-off-by: malladi nagarjuna <zombmalladinags69@gmail.com>

malladinagarjuna2 force-pushed the feat-multi-agent-support branch from a665080 to 72a5380 Compare August 13, 2026 19:33

malladinagarjuna2 requested a review from kabir August 13, 2026 19:49

merge upstream/main into feat-multi-agent-support

a127428

docs: add multi-agent deployments guide

c59eac5

Merge branch 'main' into feat-multi-agent-support

8754c73

Navigation Menu

Uh oh!

feat: native multi-agent support via MultiAgentRegistry - #1031

feat: native multi-agent support via MultiAgentRegistry#1031
malladinagarjuna2 wants to merge 8 commits into
a2aproject:mainfrom
malladinagarjuna2:feat-multi-agent-support

malladinagarjuna2 commented Aug 9, 2026

Uh oh!

kabir left a comment

Uh oh!

kabir Aug 11, 2026

Uh oh!

malladinagarjuna2 Aug 13, 2026

Uh oh!

kabir Aug 11, 2026

Uh oh!

malladinagarjuna2 Aug 13, 2026

Uh oh!

kabir Aug 11, 2026

Uh oh!

malladinagarjuna2 Aug 13, 2026

Uh oh!

kabir Aug 11, 2026

Uh oh!

malladinagarjuna2 Aug 13, 2026

Uh oh!

malladinagarjuna2 commented Aug 15, 2026

Uh oh!

mescaja commented Aug 15, 2026

Uh oh!

malladinagarjuna2 commented Aug 15, 2026

Uh oh!

malladinagarjuna2 commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

malladinagarjuna2 commented Aug 9, 2026

Overview

Changes

Uh oh!

kabir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

malladinagarjuna2 commented Aug 15, 2026

Uh oh!

mescaja commented Aug 15, 2026

Uh oh!

malladinagarjuna2 commented Aug 15, 2026

Uh oh!

malladinagarjuna2 commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants