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

在大规模多 Agent 系统中，Agent 之间需要相互发现对方的地址与能力。**A2A Hub** 是 VeADK 提供的一个轻量级注册中心（registry），用于按**分组（group）**集中管理 Agent 的 [Agent Card](https://a2a-protocol.org/latest/)，使一个 Agent 能够动态发现同组内的其他 Agent，而无需在代码中硬编码彼此的地址。

A2A Hub 由两部分组成：

- **`A2AHubServer`**：一个基于 FastAPI 的注册中心服务，负责保存分组与各分组下的 Agent Card。
- **`A2AHubClient`**：客户端，供 Agent 进程注册自身、查询同组内其他 Agent 的 Agent Card。

## 启动 Hub 服务器

`A2AHubServer` 暴露了创建分组、注册 Agent、查询分组与 Agent Card 的 HTTP 接口。直接实例化并调用 `serve` 即可启动服务（底层使用 `uvicorn`）：

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

server = A2AHubServer()

# kwargs 透传给 uvicorn.run，可设置 host、port 等
server.serve(host="0.0.0.0", port=8000)
```

服务器提供以下接口：

| 方法 | 路径 | 说明 |
| :- | :- | :- |
| `GET` | `/ping` | 健康检查，返回 `{"msg": "pong!"}` |
| `POST` | `/create_group` | 创建一个分组（参数 `group_id`） |
| `POST` | `/register_agent` | 向指定分组注册一个 Agent |
| `GET` | `/group/{group_id}/agents` | 获取指定分组内的全部 Agent |
| `GET` | `/group/{group_id}/agent/{agent_id}` | 获取指定分组内某个 Agent 的 Agent Card |
| `GET` | `/groups` | 获取全部已注册的分组 |

## 使用 Hub 客户端

`A2AHubClient` 在初始化时会对服务器执行一次健康检查。通过它可以创建分组、注册 Agent Card，以及拉取同组内的 Agent Card。

```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)

# 创建一个分组
client.create_group(group_id="weather-team")

# 将本 Agent 的 Agent Card 注册到分组中
agent_card: AgentCard = ...  # 来自您的 A2AServer
client.register_agent(
    group_id="weather-team",
    agent_id="weather_agent",
    agent_card=agent_card,
)

# 拉取同组内的全部 Agent Card
agent_infos = client.get_agent_cards(group_id="weather-team")

# 或仅拉取指定 Agent 的 Agent Card
agent_infos = client.get_agent_cards(
    group_id="weather-team",
    target_agents=["weather_agent"],
)
```

`get_agent_cards` 返回一个列表，每个元素包含 `agent_id` 与对应的 `agent_card`。当 `target_agents` 为空时返回该分组的全部 Agent；否则仅返回列表中匹配的 Agent。

## 典型工作流

1. 部署一个 `A2AHubServer` 作为中心化注册中心。
2. 每个 Agent 进程启动时，先用 `A2AHubClient` 调用 `create_group`（若分组尚不存在），再调用 `register_agent` 注册自身的 Agent Card。
3. 需要协作的 Agent 通过 `get_agent_cards` 发现同组内的其他 Agent，并据其 Agent Card 中的地址，使用 [`RemoteVeAgent`](/cn/docs/framework/multi-agent/a2a) 建立 A2A 连接。

<Callout type="info" title="提示">
A2A Hub 解决的是 Agent 的「发现」问题；实际的请求/响应仍通过 A2A 协议在 `RemoteVeAgent` 与 `A2AServer` 之间进行。两者通常配合使用。
</Callout>
