docs: add multi-agent reference architecture

[malladinagarjuna2]

Overview

This PR adds a reference architecture documentation page detailing how to scale A2A Server Agents by hosting multiple distinct agents within a single Quarkus application.

Fixes #898

The Problem

Deploying a single agent per Quarkus app (1:1 mapping to kubernetes pods) incurs significant operational overhead and resource consumption when the number of agents grows into the hundreds. Users needed official guidance and a reference architecture for deploying multiple AgentCards and JSON-RPC handlers from a single application platform.

The Solution

Added a dedicated Multi-Agent Scaling page to the documentation site. The guide explains how to bypass the default @ApplicationScoped singletons and manually register Vert.x routing paths for individual agents (e.g., /{agentId}/.well-known/agent-card.json), allowing a single app to dynamically host an unlimited number of agents with minimal overhead.

[kabir]

Thanks for the PR :-)

Before we merge, I think we can take a better approach. Rather than documenting the low-level Vert.x wiring as pseudocode in a docs page, it could perhaps be more useful to add an actual utility class/method to the SDK that handles multi-agent registration. Then the docs page just shows how to use it.

A few reasons:

1. The current code example is incomplete — the JSON-RPC handler route body is // ..., and manually constructing a JSONRPCHandler outside CDI is non-trivial. A utility would encapsulate that complexity.
2. It's JSON-RPC-only — the same pattern applies to gRPC and REST transports. A utility can abstract across all three.
3. It's testable — unlike documentation pseudocode, a utility class can have tests to make sure it actually works.
4. Title inconsistency — the page says "Multi-Agent Deployments" but the menu says "Multi-Agent Scaling" (minor, but worth aligning).

Also, @mescaja shared a complementary approach on #898 (comment) using
database-backed agent cards and @PathParam. I've not looked enough to see if that is also something that is possible to pull into this utility.

The ideal outcome would be:

• A utility in the SDK that makes multi-agent setup easy
• A short docs page showing how to use it

What do you think?

[kabir]

Actually #1031 is probably the utility :-) #1031. I think these two PRs would be better put together into one so we get both docs and implementation in one go