# a2a协议

**Repository Path**: chen_dl/a2a-protocol

## Basic Information

- **Project Name**: a2a协议
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# A2A Protocol C++ 实现(A2A v1.0)

Agent-to-Agent（A2A）协议 v1.0 的 C++ 协议实现与库：包含协议数据模型、
JSON-RPC/HTTP/SSE 服务端与客户端、任务生命周期与存储、Agent Card 发现、
多进程部署示例与 CI。

> 本项目对齐 **A2A v1.0.0**（2026-03 发布，规范见
> [a2aproject/A2A](https://github.com/a2aproject/A2A)）。v1.0 与早期 0.2/0.3 的
> wire 格式不兼容（方法名、枚举、Part 结构均有变化），若需兼容旧版请反馈，可再拆分支。

## 当前结构

```text
.
├── CMakeLists.txt          # 顶层构建：静态库 a2a + 示例 + 测试（可选开关）
├── cmake/
│   └── a2aConfig.cmake.in  # find_package(a2a) 包导出模板
├── include/a2a/            # 公共头文件（安装后位于 include/a2a/ 下）
│   ├── core/               # JSON-RPC 信封、错误码、HTTP/SSE、base64/时间等
│   ├── models/             # Part/Message/Task/AgentCard/Security 等协议模型
│   ├── client/             # A2AClient / AgentCardResolver / 工厂
│   └── server/             # AgentServer / TaskManager / 存储 / 注册中心
├── src/                    # 与 include/ 对应的实现
├── examples/               # demo、多 agent、多进程部署、SQLite/性能演示
├── tests/                  # smoke/golden/transport/sqlite（GTest + CTest）
└── third_party/            # vendored nlohmann/json 3.11.3（单头文件）
```

### 分层职责

| 目录 | 内容 | 对应规范 |
| --- | --- | --- |
| `core` | `JsonRpcRequest/Response/Error`、标准与 A2A 错误码、ErrorInfo 构造 | 规范 §9 JSON-RPC 绑定 |
| `models` | `Part`、`Message`、`Task/TaskStatus/Artifact`、流事件、`AgentCard` 及配套类型 | `specification/a2a.proto`（规范源） |
| `server` | `AgentServer`：按方法名注册 handler、JSON-RPC 信封分发、异常→错误响应 | 规范 §3 抽象操作 + §9 |
| `client` | 高层客户端、Agent Card 发现与接口选择 | 规范 §8/§9 |

数据模型直接对照 `a2a.proto`，JSON 序列化遵循规范 §5.5 的 ProtoJSON 约定：

- 字段名统一 **camelCase**：`messageId`、`contextId`、`mediaType`…
- 枚举按 proto 名输出 **SCREAMING_SNAKE_CASE**：`ROLE_USER`、`TASK_STATE_WORKING`
- 时间戳为 ISO 8601 UTC 字符串，例如 `2026-09-02T07:29:06.495Z`
- `Part` 的 `content` 是 oneof：`text` / `raw`(base64) / `url` / `data`

## 构建与运行

要求：CMake ≥ 3.21、C++20 编译器（GCC 11+/Clang 14+）、libcurl 开发库。
测试/HTTP/SQLite 依赖（GTest、cpp-httplib、sqlite amalgamation）在配置时由
FetchContent 自动拉取（可分别用 `A2A_BUILD_TESTS` /
`A2A_BUILD_HTTP_SERVER` / `A2A_BUILD_SQLITE_STORE` 关闭）。

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
ctest --test-dir build --output-on-failure
./build/examples/a2a_demo
```

以子项目方式集成，或安装后 `find_package`：

```bash
cmake --install build --prefix /usr/local   # 安装
find_package(a2a CONFIG REQUIRED)           # 消费者 CMake 中
target_link_libraries(your_target PRIVATE a2a::a2a)
```

## 使用示例

```cpp
using namespace a2a;

AgentServer server(BuildAgentCard());   // models::AgentCard
server.RegisterMethod(
    std::string(core::kMethodSendMessage),
    [](const nlohmann::json& params) {
      models::Message msg = params.at("message").get<models::Message>();
      // ... 执行业务逻辑 ...
      models::SendMessageResponse response;
      response.task = ...;              // 返回 Task 或直接 Message
      return nlohmann::json(response);
    });

// 传输层收到一个 JSON-RPC 请求体后交给分发器即可：
if (auto reply = server.HandleRequest(raw_request_json)) {
  // reply：JSON-RPC 响应（result 或 error）；通知（无 id）返回 nullopt
}
```

错误处理：handler 内抛 `core::JsonRpcException`（A2A 错误用
`core::MakeA2AErrorInfo`/`MakeA2AError` 附带 `google.rpc.ErrorInfo`），分发器会
转成规范 §9.5 的错误响应；未注册方法返回 `-32601 Method not found`。

## 多进程部署示例

`examples/deploy/` 提供独立进程形态：echo agent、math agent 各跑一个
HTTP 服务进程，orchestrator 通过发现端点 + `Connect()` 调用它们：

```bash
cmake --build build -j
bash examples/deploy/run_deploy.sh   # 启动两个 agent -> 跑 orchestrator -> 自动清理
```

单进程多 agent demo（含注册中心、并发委托与降级）见
`examples/multi_agent_demo/`。SQLite 持久化演示见
`build/examples/a2a_sqlite_demo`（写入 `build/db/demo_tasks.db`）。

CI（GitHub Actions）在 `.github/workflows/ci.yml`：格式化检查 → 构建 →
`ctest` → 多进程部署演示。

## 现状与下一步

已具备：v1.0 数据模型（含 SecurityScheme 类型化）、JSON-RPC 信封、
生命周期/存储层（内存 + SQLite）、HTTP/SSE 服务端与客户端、Agent Card
发现与工厂、多进程部署演示、GTest/golden wire 测试、CI、安装导出
(`include/a2a/` 前缀)与性能基准。

可选项：HTTP+JSON REST 绑定、gRPC 绑定、Redis 版 TaskStore、webhook
推送的实际发送、基于 `a2a.proto` 的生成代码路线。

## 参考

- 规范 v1.0.0：[a2aproject/A2A `specification/`](https://github.com/a2aproject/A2A/tree/v1.0.0/specification)
- 文档站点：[a2a-protocol.org](https://a2a-protocol.org)