---
title: "A2A Hub"
---

In large-scale multi-agent systems, Agents need to discover each other's addresses and capabilities. The **A2A Hub** is a lightweight registry provided by VeADK that centrally manages Agents' [Agent Cards](https://a2a-protocol.org/latest/) by **group**, so an Agent can dynamically discover other Agents in the same group without hardcoding each other's addresses.

The A2A Hub consists of two parts:

- **`A2AHubServer`**: A FastAPI-based registry service that stores groups and the Agent Cards under each group.
- **`A2AHubClient`**: A client that lets an Agent process register itself and query the Agent Cards of other Agents in the same group.

## Start the Hub Server

`A2AHubServer` exposes HTTP endpoints for creating groups, registering Agents, and querying groups and Agent Cards. Instantiate it and call `serve` to start the service (it uses `uvicorn` under the hood):

```python title="hub_server.py"
from veadk.a2a.hub.a2a_hub_server import A2AHubServer

server = A2AHubServer()

# kwargs are passed through to uvicorn.run; set host, port, etc.
server.serve(host="0.0.0.0", port=8000)
```

The server provides the following endpoints:

| Method | Path | Description |
| :- | :- | :- |
| `GET` | `/ping` | Health check; returns `{"msg": "pong!"}` |
| `POST` | `/create_group` | Create a group (parameter `group_id`) |
| `POST` | `/register_agent` | Register an Agent to a specified group |
| `GET` | `/group/{group_id}/agents` | Get all Agents in a specified group |
| `GET` | `/group/{group_id}/agent/{agent_id}` | Get the Agent Card of an Agent in a group |
| `GET` | `/groups` | Get all registered groups |

## Use the Hub Client

`A2AHubClient` performs a health check against the server during initialization. Through it you can create groups, register Agent Cards, and pull Agent Cards within the same group.

```python title="hub_client.py"
from a2a.types import AgentCard
from veadk.a2a.hub.a2a_hub_client import A2AHubClient

client = A2AHubClient(server_host="127.0.0.1", server_port=8000)

# Create a group
client.create_group(group_id="weather-team")

# Register this Agent's Agent Card into the group
agent_card: AgentCard = ...  # from your A2AServer
client.register_agent(
    group_id="weather-team",
    agent_id="weather_agent",
    agent_card=agent_card,
)

# Pull all Agent Cards in the group
agent_infos = client.get_agent_cards(group_id="weather-team")

# Or pull only the Agent Cards of specific Agents
agent_infos = client.get_agent_cards(
    group_id="weather-team",
    target_agents=["weather_agent"],
)
```

`get_agent_cards` returns a list where each element contains an `agent_id` and its corresponding `agent_card`. When `target_agents` is empty, it returns all Agents in the group; otherwise it returns only the Agents whose IDs match the list.

## Typical Workflow

1. Deploy an `A2AHubServer` as the centralized registry.
2. When each Agent process starts, use `A2AHubClient` to call `create_group` (if the group does not yet exist), then call `register_agent` to register its own Agent Card.
3. Agents that need to collaborate use `get_agent_cards` to discover other Agents in the same group, and use the addresses in their Agent Cards to establish an A2A connection via [`RemoteVeAgent`](/en/docs/framework/multi-agent/a2a).

<Callout type="info" title="Note">
The A2A Hub solves the "discovery" problem for Agents; the actual request/response still flows through the A2A protocol between `RemoteVeAgent` and `A2AServer`. The two are typically used together.
</Callout>
