Merged
merge develop into main #264
merge develop into main #264
Merged
wangyuejoannaAdd on Jul 21
Total: 463 files changed+71125-5974

【openlibing.ci】检测到当前PR中存在代码检查告警抑制 31 处,详情见下表,请Committer检视合理性。 / Detected 31 code check alert suppression(s) in this PR, see table below. Committers please review.

文件路径/File 行号/Line 代码片段/Snippet 工具/Tool
A2A/cpp-sdk/scripts/install_deps.sh 17 # shellcheck disable=SC1091 ShellCheck
AgentRegistry/a2x_registry/
a2x/search/models.py
7 from a2x_registry.common.models import SearchResult # noqa: F401 — re-exported flake8,ruff
AgentRegistry/a2x_registry/
a2x/utils/llm_client.py
3 from a2x_registry.common.llm_client import ( # noqa: F401 flake8,ruff
AgentRegistry/a2x_registry/
backend/app.py
124 except Exception: # noqa: BLE001 — shutdown must not raise flake8,ruff
AgentRegistry/a2x_registry/
backend/app.py
132 except Exception: # noqa: BLE001 — shutdown must not raise flake8,ruff
AgentRegistry/a2x_registry/
cluster/auth_handshake.py
43 except Exception: # noqa: BLE001 — any auth failure → unauthenticated flake8,ruff
AgentRegistry/a2x_registry/
cluster/membership.py
148 except Exception: # noqa: BLE001 — skip a malformed record flake8,ruff
AgentRegistry/a2x_registry/
cluster/membership.py
167 except Exception: # noqa: BLE001 — skip a malformed record flake8,ruff
AgentRegistry/a2x_registry/
cluster/membership.py
476 except Exception as exc: # noqa: BLE001 — never kill the loop flake8,ruff
AgentRegistry/a2x_registry/
cluster/membership.py
502 except Exception: # noqa: BLE001 — any auth failure → unauthorized flake8,ruff
AgentRegistry/a2x_registry/
cluster/store.py
108 except Exception as exc: # noqa: BLE001 — corrupt file must not crash boot flake8,ruff
AgentRegistry/a2x_registry/
cluster/store.py
503 except Exception as exc: # noqa: BLE001 — best-effort; don't propagate flake8,ruff
AgentRegistry/a2x_registry/
cluster/store.py
734 except Exception: # noqa: BLE001 — skip a malformed replica flake8,ruff
AgentRegistry/a2x_registry/
cluster/sweepers.py
42 except Exception as exc: # noqa: BLE001 — never kill the loop flake8,ruff
AgentRegistry/a2x_registry/
cluster/sweepers.py
51 except Exception as exc: # noqa: BLE001 — never kill the loop flake8,ruff
AgentRegistry/a2x_registry/
cluster/sweepers.py
81 except Exception as exc: # noqa: BLE001 — defensive flake8,ruff
AgentRegistry/a2x_registry/
cluster/sweepers.py
119 except Exception as exc: # noqa: BLE001 — defensive flake8,ruff
AgentRegistry/a2x_registry/
heartbeat/router.py
97 except Exception as exc: # noqa: BLE001 flake8,ruff
AgentRegistry/a2x_registry/
heartbeat/sweeper.py
22 from .errors import HeartbeatError # noqa: F401 — re-exported via __init__ flake8,ruff
AgentRegistry/a2x_registry/
heartbeat/sweeper.py
89 except Exception as exc: # noqa: BLE001 — sweeper must survive any error flake8,ruff
AgentRegistry/a2x_registry/
heartbeat/sweeper.py
100 except Exception as exc: # noqa: BLE001 — defensive flake8,ruff
AgentRegistry/a2x_registry/
traditional/search/traditional_search.py
15 from a2x_registry.common.models import SearchResult # noqa: F401 flake8,ruff
AgentRegistry/a2x_registry/
vector/search/vector_search.py
12 from a2x_registry.common.models import SearchResult # noqa: F401 flake8,ruff
AgentRegistry/client/
a2x_registry_client/async_client.py
250 except Exception as exc: # noqa: BLE001 flake8,ruff
AgentRegistry/client/
a2x_registry_client/client.py
324 except Exception as exc: # noqa: BLE001 — best-effort flake8,ruff
AgentRegistry/client/
a2x_registry_client/heartbeat.py
90 except Exception as exc: # noqa: BLE001 — daemon must survive flake8,ruff
AgentRegistry/client/
a2x_registry_client/heartbeat.py
150 import asyncio as _asyncio # noqa: E402 — keep below sync types to avoid flake8,ruff
AgentRegistry/client/
a2x_registry_client/heartbeat.py
152 from typing import Awaitable # noqa: E402 flake8,ruff
AgentRegistry/client/
a2x_registry_client/heartbeat.py
217 except Exception as exc: # noqa: BLE001 flake8,ruff
AgentRegistry/client/
a2x_registry_client/models.py
22 allowed = {f.name for f in fields(cls)} # type: ignore[arg-type] mypy
AgentRegistry/client/
a2x_registry_client/models.py
24 return cls(**kwargs) # type: ignore[call-arg] mypy
likedislike
@@ -1,120 +1,85 @@
1cmake_minimum_required(VERSION 3.15)1cmake_minimum_required(VERSION 3.15)
2- 2+project(a2a_cpp LANGUAGES CXX C)
3-project(a2a LANGUAGES CXX C)
4 3 
5set(CMAKE_CXX_STANDARD 17)4set(CMAKE_CXX_STANDARD 17)
6set(CMAKE_CXX_STANDARD_REQUIRED ON)5set(CMAKE_CXX_STANDARD_REQUIRED ON)
6+set(CMAKE_CXX_EXTENSIONS OFF)
7 7 
8+option(A2A_BUILD_CLIENT "Build A2A client components" ON)
9+option(A2A_BUILD_SERVER "Build A2A server components" ON)
10+option(A2A_ENABLE_EXAMPLES "Build example binaries" OFF)
8option(A2A_ENABLE_TESTS "Build unit tests" OFF)11option(A2A_ENABLE_TESTS "Build unit tests" OFF)
9-option(A2A_ENABLE_EXAMPLES "Build examples" OFF)12+option(A2A_ENABLE_COVERAGE "Enable code coverage instrumentation" OFF)
10-option(A2A_ENABLE_COVERAGE "Enable code coverage" OFF)
11 13 
12-include(third_party/third_party.cmake)14+if(A2A_ENABLE_COVERAGE)
15+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
16+ set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --coverage")
17+ link_libraries(--coverage)
18+endif()
19+ 
20+if(DEFINED ASAN AND ASAN STREQUAL "enable")
21+ add_compile_options(-fsanitize=address -fno-omit-frame-pointer)
22+ add_link_options(-fsanitize=address)
23+endif()
24+ 
25+include(${CMAKE_SOURCE_DIR}/third_party/third_party.cmake)
26+ 
27+add_subdirectory(src)
28+ 
29+if(A2A_ENABLE_EXAMPLES)
30+ add_subdirectory(examples)
31+endif()
13 32 
14find_package(OpenSSL REQUIRED)33find_package(OpenSSL REQUIRED)
15find_package(CURL REQUIRED)34find_package(CURL REQUIRED)
16 35 
17-add_compile_options(-fPIC)36+set(_a2a_link_libs pthread dl OpenSSL::SSL OpenSSL::Crypto http_parser)
18-add_compile_options(-ftrapv)
19 37 
20-if(A2A_ENABLE_COVERAGE)
21- message(STATUS "Code coverage is enabled")
22- 
23- if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
24- add_compile_options(-fprofile-arcs -ftest-coverage)
25- add_link_options(-fprofile-arcs -ftest-coverage)
26- else()
27- message(WARNING "Code coverage not supported for compiler: ${CMAKE_CXX_COMPILER_ID}")
28- endif()
29-endif()
30- 
31-# Set compiler flags based on build type
32-set(CMAKE_CXX_FLAGS_DEBUG "-g -O0 -DDEBUG")
33-set(CMAKE_CXX_FLAGS_RELEASE "-g -O2")
34-set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-O2 -g")
35-set(CMAKE_CXX_FLAGS_MINSIZEREL "-Os -DNDEBUG")
36- 
37-# Common compiler flags
38-add_compile_options(-Wall -Werror -Wno-error=unused-variable -Wfloat-equal -Wtrampolines -fno-strict-aliasing -fstack-protector-strong)
39- 
40-# Linker flags for security hardening
41-set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-z,noexecstack,-z,relro,-z,now -rdynamic -pie")
42-set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,noexecstack,-z,relro,-z,now -rdynamic")
43- 
44-if(CMAKE_BUILD_TYPE STREQUAL "Release")
45- set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s")
46- set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -s")
47-endif()
48- 
49-# Skip RPATH to avoid hardcoded paths in binaries
50-set(CMAKE_SKIP_RPATH TRUE)
51- 
52-# Ensure debug symbols are included
53-if(CMAKE_BUILD_TYPE STREQUAL "Debug")
54- message(STATUS "Building in Debug mode with full debug symbols")
55-elseif(CMAKE_BUILD_TYPE STREQUAL "RelWithDebInfo")
56- message(STATUS "Building in Release with Debug Info mode")
57-endif()
58- 
59-# Add all sources and target definition for a2a from src/
60-add_subdirectory(src)
61- 
62-## Link against libevent. Prefer the imported target provided by FetchContent or the
63-## package config; fall back to `event` which is what libevent's CMake creates when
64-## fetched by FetchContent in many setups.
65-set(_a2a_libevent_target "")
66if(TARGET event)38if(TARGET event)
67- set(_a2a_libevent_target event)39+ list(APPEND _a2a_link_libs event)
68elseif(TARGET libevent)40elseif(TARGET libevent)
69- set(_a2a_libevent_target libevent)41+ list(APPEND _a2a_link_libs libevent)
70-elseif(TARGET "libevent::event")
71- set(_a2a_libevent_target libevent::event)
72-elseif(TARGET libevent_core)
73- set(_a2a_libevent_target libevent_core)
74-else()
75- message(WARNING "No imported libevent target found; attempting to link 'event' (may fail).")
76- set(_a2a_libevent_target event)
77endif()42endif()
78 43 
79-target_link_libraries(a2a PUBLIC ${_a2a_libevent_target} nlohmann_json::nlohmann_json http_parser CURL::libcurl OpenSSL::SSL OpenSSL::Crypto)
80- 
81-# Pull in libevent's pthread helper when available so evthread_use_pthreads resolves.
82if(TARGET event_pthreads)44if(TARGET event_pthreads)
83- target_link_libraries(a2a PUBLIC event_pthreads)45+ list(APPEND _a2a_link_libs event_pthreads)
84elseif(TARGET libevent_pthreads)46elseif(TARGET libevent_pthreads)
85- target_link_libraries(a2a PUBLIC libevent_pthreads)47+ list(APPEND _a2a_link_libs libevent_pthreads)
86-elseif(TARGET "libevent::pthread")
87- target_link_libraries(a2a PUBLIC libevent::pthread)
88else()48else()
89 find_library(_a2a_event_pthreads_lib NAMES event_pthreads libevent_pthreads)49 find_library(_a2a_event_pthreads_lib NAMES event_pthreads libevent_pthreads)
90 if(_a2a_event_pthreads_lib)50 if(_a2a_event_pthreads_lib)
91- target_link_libraries(a2a PUBLIC ${_a2a_event_pthreads_lib})51+ list(APPEND _a2a_link_libs ${_a2a_event_pthreads_lib})
92- else()
93- message(WARNING "libevent pthread helper target not found; thread support may fail at link time.")
94 endif()52 endif()
95endif()53endif()
96 54 
97-set_target_properties(a2a PROPERTIES55+if(TARGET nlohmann_json::nlohmann_json)
98- OUTPUT_NAME "a2a"56+ list(APPEND _a2a_link_libs nlohmann_json::nlohmann_json)
99-)
100- 
101-if(TARGET http_parser)
102- target_link_libraries(a2a PRIVATE http_parser)
103-endif()
104- 
105-if (TARGET OpenSSL::SSL AND OpenSSL::Crypto)
106- target_link_libraries(a2a PUBLIC OpenSSL::SSL OpenSSL::Crypto)
107endif()57endif()
108 58 
109if(TARGET CURL::libcurl)59if(TARGET CURL::libcurl)
110- target_link_libraries(a2a PUBLIC CURL::libcurl)60+ list(APPEND _a2a_link_libs CURL::libcurl)
61+elseif(TARGET libcurl)
62+ list(APPEND _a2a_link_libs libcurl)
63+endif()
64+ 
65+target_link_libraries(a2a PUBLIC ${_a2a_link_libs})
66+ 
67+set_target_properties(a2a PROPERTIES
68+ LIBRARY_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/output/lib
69+ RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/output/lib
70+)
71+ 
72+if(A2A_ENABLE_EXAMPLES)
73+ foreach(_example_target helloworld_client helloworld_server streaming_client streaming_server)
74+ if(TARGET ${_example_target})
75+ set_target_properties(${_example_target} PROPERTIES
76+ RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/output/bin
77+ )
78+ endif()
79+ endforeach()
111endif()80endif()
112 81 
113if(A2A_ENABLE_TESTS)82if(A2A_ENABLE_TESTS)
114 enable_testing()83 enable_testing()
115 add_subdirectory(tests)84 add_subdirectory(tests)
116endif()85endif()
117- 
118-if(A2A_ENABLE_EXAMPLES)
119- add_subdirectory(examples)
120-endif()
@@ -1,188 +1,225 @@
1-# a2a_cpp1+# A2A C++ SDK
2 2 
3-## 简介3+## 目录
4 4 
5-**A2A C++ SDK**是基于agent to agent协议的C++实现,旨在帮助开发者快速构建多智能体协作系统、任务编排系统、AI Agent平台、边缘智能设备通信等场景。[A2A协议规范](https://a2a-protocol.org/v0.3.0/specification/)是一套用于智能体之间通信的标准化协议,定义了任务、消息、时间、智能体能力描述等核心结构。SDK提供统一的数据结构、序列化能力、协议校验机制以及通信接口,让智能体之间的交互更加稳定、高效、可维护。5+- [概述](#概述)
6+- [文档](#文档)
7+- [环境要求](#环境要求)
8+- [快速入门](#快速入门)
9+- [构建与安装](#构建与安装)
10+- [运行示例](#运行示例)
11+- [运行测试](#运行测试)
12+- [参与贡献](#参与贡献)
13+- [License](#license)
6 14 
15+## 概述
7 16 
8-## 快速开始17+A2A C++ SDK 是 [Agent-to-Agent 协议 v1.0](https://a2a-protocol.org/v1.0.0/specification/) 的 C++ 实现,提供 A2A 客户端与服务器能力,支持基于 **HTTP + JSON-RPC** 的智能体间通信。
9 18 
10-### 安装19+- 构建 A2A 客户端:发现 Agent Card、发送消息、查询/取消任务、接收流式事件
20+- 构建 A2A 服务器:注册 `AgentExecutor`、管理任务生命周期、暴露 JSON-RPC 端点
21+- 支持多模态 `Part`、推送通知配置、请求拦截器、自定义 `TaskStore` 等扩展能力(详见示例与 API 文档)
11 22 
12-#### 环境要求23+## 文档
13-- C++17 或以上编译器(GCC/Clang)
14-- **CMake >= 3.15**(与仓库根 `CMakeLists.txt` 一致)
15-- Git、pthread、常规构建工具(`make` 或 `ninja`)
16-- 操作系统:以 **Linux** 为主进行验证
17 24 
18-#### 安装构建依赖25+| 文档 | 说明 |
19- 
20-以下为 **CMake 直接依赖** 或 **`third_party/third_party.cmake` 拉取/查找** 的组件及 **建议版本**(满足或高于该版本通常即可通过 `find_package` / 编译;若系统包过旧,可依赖 FetchContent 离线源码目录或联网拉取)。
21- 
22-| 依赖 | 角色 | 建议版本 / 备注 |
23-|------|------|-----------------|
24-| **OpenSSL**(开发包 `libssl-dev` / `openssl-devel` 等) | TLS、加解密 | **>= 1.1.1**(常见为 1.1.1 系或 3.x) |
25-| **libcurl**(开发包 `libcurl4-openssl-dev` / `libcurl-devel` 等) | HTTP 客户端(JSON-RPC 等) | **>= 7.68**;新发行版往往更高 |
26-| **libevent** | 事件循环 | 系统包 **2.1.x** 或与 FetchContent 默认 **`release-2.1.12-stable`** 等价能力 |
27-| **nlohmann_json** | JSON 序列化 | **>= 3.11.2**(FetchContent 默认 **`v3.11.2`**) |
28-| **http_parser**(nodejs/http-parser) | HTTP 报文解析 | FetchContent 默认 **`v2.9.4`**;亦可使用本地 `third_party/http_parser-src/` 离线构建 |
29- 
30-**说明:** 当前本仓库 **A2A C++ SDK 的 CMake 配置未使用 cpp-httplib**;若文档其它处仍出现该依赖,可忽略或与历史模板区分。
31- 
32-CMake 会通过 **`find_package(OpenSSL)`、`find_package(CURL)`** 使用系统 **OpenSSL**、**libcurl**;并通过 **`third_party/third_party.cmake`** 解析 **libevent**、**nlohmann_json**、**http_parser**(优先系统包,缺失时 **FetchContent** 拉源码,需网络与 Git;亦可预先放置与 `third_party` 约定一致的源码目录以离线构建)。
33- 
34-**Ubuntu / Debian(示例)**
35- 
36-```bash
37-sudo apt-get update
38-sudo apt-get install -y build-essential cmake pkg-config git \
39- libssl-dev libcurl4-openssl-dev libevent-dev nlohmann-json3-dev
40-```
41- 
42-**Fedora / RHEL / CentOS Stream(示例)**
43- 
44-```bash
45-sudo dnf install -y gcc-c++ cmake pkg-config git openssl-devel libcurl-devel libevent-devel nlohmann-json-devel
46-```
47- 
48-**macOS(示例)**
49- 
50-```bash
51-brew install cmake pkg-config openssl libcurl libevent nlohmann-json
52-```
53- 
54-其他发行版请安装 **等价开发包**;若系统无对应包,由 `third_party/third_party.cmake` 尝试 FetchContent(需可访问 GitHub 等)。
55- 
56-#### 编译(含示例)
57- 
58-在 **`A2A/cpp-sdk`** 目录下执行(推荐一键脚本):
59- 
60-```bash
61-cd A2A/cpp-sdk
62-bash scripts/build.sh -e
63-```
64- 
65-默认生成目录为 **`build/`**(可用 `bash scripts/build.sh -e -b <目录名>` 修改)。脚本等价于在构建目录执行:
66- 
67-```bash
68-cmake <sdk根目录> -DCMAKE_BUILD_TYPE=Release -DA2A_ENABLE_EXAMPLES=ON
69-cmake --build . -j"$(nproc)"
70-```
71- 
72-也可自行 `mkdir build && cd build` 后传入 **`-DA2A_ENABLE_EXAMPLES=ON`**;**未打开该选项时不会生成示例可执行文件**。
73- 
74-#### 构建产物说明
75- 
76-| 路径 | 内容 |
77|------|------|26|------|------|
78-| **`build/src/liba2a.so`**(或平台等价动态库名) | 主库,链接示例时依赖此文件 |27+| [依赖说明](docs/dependencies.md) | 运行/编译依赖、版本、各发行版安装命令 |
79-| **`build/examples/`** | **`helloworld_server`**、**`helloworld_client`**、**`streaming_server`**、**`streaming_client`**(仅在 `A2A_ENABLE_EXAMPLES=ON` 时生成) |28+| [测试说明](docs/testing.md) | 单元测试、覆盖率、ASAN |
80-| **`output/`** | 在 **`a2a` 目标构建完成后** 复制 **`liba2a.so`**、`include/` 头文件及 **nlohmann** 头文件,便于打包分发;**不包含示例二进制** |29+| [API 文档索引](docs/api/README.md) | Client / Server API、协议对照 |
30+| [错误处理说明](docs/errors.md) | 错误码、异常类型与处理建议 |
31+| [日志说明](docs/logging.md) | SDK 诊断日志、`A2A_LOG` / `SetLogCallback` 用法 |
81 32 
82-运行示例前,请将 **`build/src`**(以及 `build` 根目录,若需要)加入动态库搜索路径,例如:33+## 环境要求
34+ 
35+- **操作系统**:Linux(glibc 或 musl,主要验证平台)
36+- **编译器**:C++17 及以上(GCC 9+ / Clang 10+)
37+- **CMake**:≥ 3.15(见根目录 `CMakeLists.txt`)
38+- **依赖**:见 [docs/dependencies.md](docs/dependencies.md)
39+ 
40+## 快速入门
41+ 
42+在仓库 `A2A/cpp-sdk` 目录下,按以下顺序执行(约 5–15 分钟,视网络与编译环境而定):
83 43 
84```bash44```bash
85-export LD_LIBRARY_PATH="/path/to/A2A/cpp-sdk/build/src:/path/to/A2A/cpp-sdk/build:${LD_LIBRARY_PATH:-}"45+# 1. 安装系统依赖(curl、openssl、libevent 等;部分发行版需 sudo)
86-```46+sudo bash scripts/install_deps.sh
87 47 
88-将 **`/path/to/A2A/cpp-sdk`** 换成本机 SDK 根目录的绝对路径。48+# 2. 编译 SDK 与示例(产物:output/lib/liba2a.so、output/bin/*)
49+bash scripts/build.sh -e
89 50 
90-#### 运行示例(命令行)51+# 3. 一键冒烟测试全部示例(脚本内会先后台起 Server,再跑 Client)
91- 
92-以下端口仅为示例,**`-p` 可改为任意本机可用端口**;客户端 **`ip` / `port` 须与服务端一致**。
93- 
94-**Hello World(非流式)**
95- 
96-```bash
97-/path/to/A2A/cpp-sdk/build/examples/helloworld_server -i 127.0.0.1 -p 8080
98-/path/to/A2A/cpp-sdk/build/examples/helloworld_client -i 127.0.0.1 -p 8080
99-```
100- 
101-客户端末尾有 **`getchar()`**,需按回车结束进程;在脚本或非交互环境可向 stdin 送入换行,例如:`printf '\n' | .../helloworld_client ...`。
102- 
103-**Streaming(与 `streaming_server` 配套)**
104- 
105-```bash
106-/path/to/A2A/cpp-sdk/build/examples/streaming_server -i 127.0.0.1 -p 8080
107-/path/to/A2A/cpp-sdk/build/examples/streaming_client -i 127.0.0.1 -p 8080
108-```
109- 
110-#### 冒烟自检(可选)
111- 
112-在配置好 **`LD_LIBRARY_PATH`** 后,可在 SDK 根目录执行:
113- 
114-```bash
115bash scripts/run_example.sh52bash scripts/run_example.sh
116```53```
117 54 
118-默认使用端口 **`8888`**(可通过环境变量 **`A2A_EXAMPLE_PORT`** 覆盖);脚本内会对服务端做 JSON-RPC 探测,并启动两个 client(通过 **`printf '\n'`** 避免 **`getchar()`** 阻塞)。55+默认示例端口:`8888`。JSON-RPC 端点:`http://127.0.0.1:8888/jsonrpc`。指定端口示例:
119 56 
120-### 样例57+```bash
121- 58+A2A_EXAMPLE_PORT=9000 bash scripts/run_example.sh
122-完整可编译示例在仓库 **`examples/`** 目录:
123- 
124-| 文件 | 说明 |
125-|------|------|
126-| **`helloworld_server.cpp` / `helloworld_client.cpp`** | 非流式服务端与客户端(手写 **`A2A::AgentCard`**,与服务器配置一致) |
127-| **`streaming_server.cpp` / `streaming_client.cpp`** | 流式编排示例与客户端(**`ClientCallContext`**、`AddEventConsumer` 等) |
128- 
129-下面给出与当前 SDK 一致的 **客户端最小思路**(省略 `getopt` 等,细节以 `helloworld_client.cpp` 为准):使用 **`A2A::Client::ClientFactory::Create`**,**`ClientEvent`** 为 **`std::variant<A2A::Message, std::pair<A2A::Task, ...>>`**,按需使用 **`std::holds_alternative` / `std::visit`** 处理返回。
130- 
131-```cpp
132-#include "client/client_factory.h"
133-#include "types.h"
134- 
135-// 与 helloworld_server 中 AgentCard 字段保持一致(含 url 指向 .../jsonrpc)
136-A2A::AgentCard card;
137-card.name = "ExampleAgent";
138-card.url = "http://127.0.0.1:8080/jsonrpc";
139-card.version = "1.0.0";
140-card.defaultInputModes = {"text"};
141-card.defaultOutputModes = {"text"};
142-card.capabilities.streaming = false;
143-card.preferredTransport = A2A::JSONRPC_TRANSPORT;
144- 
145-A2A::Client::ClientConfig cfg;
146-cfg.streaming = false;
147-cfg.supportedTransports = {"JSONRPC"};
148-auto client = A2A::Client::ClientFactory::Create(card, cfg);
149- 
150-A2A::Message msg;
151-msg.role = A2A::Role::USER;
152-msg.messageId = "123";
153-// ... 组装 parts 后 client->SendMessage(msg, nullptr, handler);
154```59```
155 60 
156-服务端请使用 **`A2A::Server::HttpServerBuilder::Build`** 与 **`A2A::Server::AgentExecutor`**,完整流程见 **`examples/helloworld_server.cpp`**。61+**方式一:单终端一键(推荐首次验证)**
157 62 
158-**说明:** `include/client/a2a_card_resolver.h` 提供 **`A2A::Client::A2ACardResolver`** 抽象接口(异步 **`GetAgentCard`**);当前示例采用 **手写 AgentCard**,便于与示例服务器对齐。若需从 **`/.well-known/agent-card.json`** 拉取卡片,需在应用侧自行实现 **`A2ACardResolver`** 或使用项目内其它 HTTP 解析逻辑。63+```bash
64+bash scripts/run_example.sh # 依次跑 helloworld / streaming:后台起 Server → Client 检查 → 停止 Server
65+```
159 66 
67+**方式二:双终端(Server 常驻,便于反复调试 Client)**
160 68 
161-**A2A C++ SDK**采用模块化设计,核心模块包括:69+```bash
70+export LD_LIBRARY_PATH="$(pwd)/output/lib:${LD_LIBRARY_PATH:-}"
162 71 
163-* **SDK接口层**:定义 **`A2A::Client::Client`**、**`A2A::Server::HttpServerBuilder`**、**`A2A::Client::A2ACardResolver`**(抽象)、**`A2A::Server::AgentExecutor`** 等,便于搭建客户端与服务端。72+# 终端 1:前台运行 Server(Ctrl+C 停止)
73+./output/bin/helloworld_server -i 127.0.0.1 -p 8888
164 74 
165-* **协议结构层**:定义Message、Task、Event、AgentCard等结构,提供字段校验、默认值处理等功能。75+# 终端 2:Server 已监听后再跑 Client
76+./output/bin/helloworld_client -i 127.0.0.1 -p 8888
77+```
166 78 
167-* **传输层**:抽象底层传输,对上层功能实现提供统一接口,便于底层不同传输类型的扩展。79+`streaming_server` / `streaming_client` 同理,须先 Server 后 Client,且两端端口一致。
168 80 
169-## 功能特性81+**注意**:
170 82 
171-### **智能体能力获取**83+- **必须先有 Server 再跑 Client**;同一终端里直接连跑两条命令时,Client 会因 Server 未就绪而失败。
172-A2A C++ SDK提供根据智能体url获取智能体能力的功能,查询智能体支持的基本信息、支持的功能、认证方式、输入输出模式、所有技能列表84+- `run_example.sh`:无参数时在同一脚本内后台起 Server、跑 Client 后自动清理进程。
85+- 手动启动前须先 `bash scripts/build.sh -e`,并设置 `LD_LIBRARY_PATH`(见下文「运行示例」)。
173 86 
174-### **智能体之间标准化调用**87+## 构建与安装
175-A2A C++ SDK支持任务管理、状态同步、多模态数据、实时通信等,让用户可以快速简单的在智能体之间传递消息,进行多智能体协作,完成实时推送与流式交互
176 88 
89+统一入口为 `scripts/build.sh`(不是仓库根目录下的 `build.sh`)。`scripts/` 下脚本均为 **Bash**,请使用 `bash scripts/...` 调用,勿用 `sh`(见 [依赖说明 - 脚本解释器](docs/dependencies.md#脚本解释器说明))。
90+ 
91+```bash
92+# Release 构建(默认,仅核心库)
93+bash scripts/build.sh
94+ 
95+# Release 构建 + 示例
96+bash scripts/build.sh -e
97+ 
98+# Debug 构建(含调试符号)
99+bash scripts/build.sh -t Debug
100+ 
101+# 编译并启用单元测试
102+bash scripts/build.sh -u -t Debug
103+ 
104+# 覆盖率构建 + 运行测试报告(见 docs/testing.md)
105+bash scripts/build.sh -c
106+ 
107+# AddressSanitizer 调试构建
108+bash scripts/build.sh -u -t Debug --asan
109+```
110+ 
111+常用 CMake 裁剪选项(经 `build.sh` 传入):
112+ 
113+| 选项 | 含义 |
114+|------|------|
115+| `-h, --help` | 显示帮助信息并退出 |
116+| `-e, --with-examples` | 编译 `examples/` 下示例程序 |
117+| `-u, --with-tests` | 编译单元测试 |
118+| `-c, --coverage` | 启用覆盖率(隐含 `-u`,Debug) |
119+| `--no-client` | 不编译 Client 组件 |
120+| `--no-server` | 不编译 Server 组件 |
121+| `--asan` | 启用 AddressSanitizer(自动使用 Debug) |
122+| `-t, --type <type>` | CMake 构建类型:`Debug`、`Release`、`RelWithDebInfo`、`MinSizeRel`(默认 `Release`;日常开发/测试常用 `Debug`,发布用 `Release`) |
123+| `-b, --build-dir <dir>` | 构建目录,默认 `build` |
124+| `-g, --generator <name>` | CMake 生成器(如 `Ninja`、`NMake Makefiles`) |
125+ 
126+**构建产物**:
127+ 
128+| 路径 | 说明 |
129+|------|------|
130+| `output/lib/liba2a.so` | 共享库 |
131+| `output/include/` | 公共头文件(`types.h`、`client/`、`server/` 等) |
132+| `output/bin/` | 示例二进制(需 `-e`) |
133+ 
134+集成到自己工程时,链接 `liba2a.so` 并添加头文件路径 `output/include`(或源码树 `include/`)。运行时需要将 `output/lib` 加入 `LD_LIBRARY_PATH`。详见 `examples/CMakeLists.txt`。
135+ 
136+## 运行示例
137+ 
138+示例位于 `examples/` 目录。可使用统一脚本 `scripts/run_example.sh` 做冒烟测试,也可手动分终端启动 Server 与 Client。
139+ 
140+**方式一:单终端(`run_example.sh`)**
141+ 
142+```bash
143+bash scripts/build.sh -e
144+bash scripts/run_example.sh
145+```
146+ 
147+脚本会对 `helloworld`、`streaming` 各执行一轮:**后台起 Server → HTTP/JSON-RPC 检查 → 跑 Client → 停止 Server**。
148+ 
149+**方式二:双终端(手动,Server 常驻)**
150+ 
151+```bash
152+export LD_LIBRARY_PATH="$(pwd)/output/lib:${LD_LIBRARY_PATH:-}"
153+ 
154+# 终端 1
155+./output/bin/helloworld_server -i 127.0.0.1 -p 8080
156+ 
157+# 终端 2(须等 Server 监听后再执行)
158+./output/bin/helloworld_client -i 127.0.0.1 -p 8080
159+```
160+ 
161+**注意**:
162+ 
163+- **必须先有 Server 再跑 Client**;Server 在前台运行时会占用终端,Client 应在另一终端连接同一 `-i` / `-p`。
164+- 运行示例二进制前须 `bash scripts/build.sh -e`,并将 `output/lib` 加入 `LD_LIBRARY_PATH`。
165+ 
166+| 示例 | 源文件 | 说明 |
167+|------|--------|------|
168+| Hello World Server | `examples/helloworld_server.cpp` | HTTP Server,非流式消息处理 |
169+| Hello World Client | `examples/helloworld_client.cpp` | 获取 Agent Card、发送消息 |
170+| Streaming Server | `examples/streaming_server.cpp` | 流式任务状态与产物推送 |
171+| Streaming Client | `examples/streaming_client.cpp` | `message/stream` 流式接收 |
172+ 
173+API 与协议细节见 [docs/api/README.md](docs/api/README.md)。
174+ 
175+## 运行测试
176+ 
177+```bash
178+# 构建 + 运行 ctest(含覆盖率与 ASAN,默认)
179+bash scripts/run_ut.sh
180+ 
181+# 跳过覆盖率,更快
182+bash scripts/run_ut.sh --no-coverage
183+ 
184+# 跳过 ASAN
185+bash scripts/run_ut.sh --no-coverage --no-asan
186+# 或
187+A2A_SKIP_ASAN=1 bash scripts/run_ut.sh --no-coverage
188+```
189+ 
190+也可手动构建后运行:
191+ 
192+```bash
193+bash scripts/build.sh -u -t Debug
194+cd build
195+export LD_LIBRARY_PATH="../output/lib:${LD_LIBRARY_PATH:-}"
196+ctest --output-on-failure
197+```
198+ 
199+覆盖率与报告说明见 [docs/testing.md](docs/testing.md)。
200+ 
201+## 日志
202+ 
203+SDK 默认将诊断日志输出到 **stdout**,输出前缀含 `[LEVEL]`(`DEBUG` / `INFO` / `WARN` / `ERROR` / `FATAL`)。若 stdout 被应用占用,可通过 `SetLogCallback` 重定向到 stderr 或文件。详见 [docs/logging.md](docs/logging.md)。
177 204 
178## 参与贡献205## 参与贡献
179 206 
180-我们欢迎所有形式的贡献,包括但不限于:207+欢迎提交 Issue、文档改进与代码贡献。提交 PR 前请运行:
181-- 提交问题和功能建议
182-- 改进文档
183-- 提交代码
184-- 分享使用经验
185 208 
186-## 开源许可证209+```bash
210+bash scripts/run_ut.sh --no-coverage
211+```
187 212 
188-本项目依据Apache-2.0许可证授权。213+确保单元测试通过。
214+ 
215+## License
216+ 
217+本项目依据 Apache-2.0 许可证授权。
218+ 
219+## Copyright
220+ 
221+Copyright (c) 2025-2026 Huawei Technologies Co., Ltd. All rights reserved.
222+ 
223+## Third-Party Notices
224+ 
225+本项目包含或依赖第三方开源软件,其版权和许可证信息均归原作者所有,并在相应文件中予以说明。
@@ -1,66 +0,0 @@
1- 
2-FROM gcc:13
3- 
4-RUN apt-get update && \
5- apt-get install -y --no-install-recommends \
6- cmake \
7- make \
8- gcc \
9- g++ \
10- git \
11- libcurl4 \
12- libcurl4-openssl-dev \
13- nlohmann-json3-dev \
14- libevent-dev \
15- python3 \
16- python3-pip \
17- gcovr \
18- && rm -rf /var/lib/apt/lists/* \
19- && pip3 install --break-system-packages junit2html
20- 
21-# 下载并安装 nlohmann-json-schema-validator
22-RUN curl -L https://github.com/pboettch/json-schema-validator/archive/refs/tags/2.3.0.tar.gz \
23- -o /tmp/json-schema-validator.tar.gz \
24- && tar -xzf /tmp/json-schema-validator.tar.gz -C /tmp \
25- && cd /tmp/json-schema-validator-2.3.0 \
26- && mkdir build && cd build \
27- && cmake .. \
28- -DCMAKE_BUILD_TYPE=Release \
29- -DCMAKE_INSTALL_PREFIX=/usr/local \
30- -DBUILD_SHARED_LIBS=ON \
31- -DJSON_VALIDATOR_BUILD_EXAMPLES=OFF \
32- -DJSON_VALIDATOR_BUILD_TESTS=OFF \
33- && make -j$(nproc) \
34- && make install \
35- && ldconfig \
36- && rm -rf /tmp/*
37- 
38-# 下载并安装 http_parser v2.9.4
39-RUN curl -L https://github.com/nodejs/http-parser/archive/refs/tags/v2.9.4.tar.gz \
40- -o /tmp/http_parser.tar.gz \
41- && tar -xzf /tmp/http_parser.tar.gz -C /tmp \
42- && cd /tmp/http-parser-2.9.4 \
43- && make package \
44- && make install \
45- && ldconfig \
46- && rm -rf /tmp/*
47- 
48-# 下载并安装 GoogleTest v1.16.0
49-RUN curl -L https://github.com/google/googletest/archive/refs/tags/v1.16.0.tar.gz \
50- -o /tmp/gtest.tar.gz \
51- && tar -xzf /tmp/gtest.tar.gz -C /tmp \
52- && cd /tmp/googletest-1.16.0 \
53- && cmake -B build -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_INSTALL_PREFIX=/usr/local \
54- && cmake --build build --target install -j$(nproc) \
55- && rm -rf /tmp/*
56- 
57-# 下载 cpp-httplib v0.18.7
58-RUN curl -L https://github.com/yhirose/cpp-httplib/archive/refs/tags/v0.18.7.tar.gz \
59- -o /tmp/httplib.tar.gz \
60- && tar -xzf /tmp/httplib.tar.gz -C /tmp \
61- && cp /tmp/cpp-httplib-0.18.7/httplib.h /usr/local/include/ \
62- && rm -rf /tmp/*
63- 
64-WORKDIR /workspace
65- 
66-CMD ["/bin/bash"]
@@ -0,0 +1,66 @@
1+# A2A C++ SDK API 文档
2+ 
3+本目录为 **公共 API 使用说明**(手写文档)。完整声明见 `include/*.h`。
4+ 
5+## 文档索引
6+ 
7+| 文档 | 内容 |
8+|------|------|
9+| [client.md](client.md) | 客户端创建、Card 解析、消息发送、任务与流式事件 |
10+| [server.md](server.md) | 服务端创建、AgentExecutor、HTTP 监听 |
11+| [protocol-mapping.md](protocol-mapping.md) | A2A 协议方法 ↔ C++ API 对照 |
12+| [../errors.md](../errors.md) | 错误码、异常类型与处理建议 |
13+| [../logging.md](../logging.md) | SDK 日志与协议事件说明 |
14+ 
15+## 头文件一览
16+ 
17+| 头文件 | 说明 |
18+|--------|------|
19+| `types.h` | 协议 DTO、`A2AErrorCode`、`Message`、`Task`、`AgentCard` 等 |
20+| `error.h` | `A2AClientException`、`A2AServerError` |
21+| `a2a_log.h` | `A2A_LOG`、`SetLogLevel`、`SetLogCallback` |
22+| `client/client.h` | `Client` 高层 API |
23+| `client/client_factory.h` | `ClientFactory` |
24+| `client/a2a_card_resolver.h` | `A2ACardResolver` |
25+| `client/http_card_resolver_builder.h` | HTTP Card 解析器工厂 |
26+| `client/jsonrpc_transport.h` | JSON-RPC 传输抽象 |
27+| `client/client_call_interceptor.h` | 请求拦截器 |
28+| `server/server.h` | `Server` 生命周期 |
29+| `server/http_server_builder.h` | `HttpServerBuilder`、`HttpConfig` |
30+| `server/agent_executor.h` | `AgentExecutor` |
31+| `server/task_store.h` | `TaskStore` |
32+| `server/task_updater.h` | `TaskUpdater` |
33+ 
34+## 架构概览
35+ 
36+```
37+HttpCardResolverBuilder / ClientFactory
38+ ↓
39+ Client + ClientTransport(JSON-RPC)
40+ ↓
41+ HTTP → Agent Server(/jsonrpc)
42+ 
43+HttpServerBuilder
44+ ↓
45+ Server + AgentExecutor + TaskStore
46+ ↓
47+ HTTP JSON-RPC + /.well-known/agent-card.json
48+```
49+ 
50+## 示例与测试
51+ 
52+| 能力 | 示例 | 测试(参考) |
53+|------|------|--------------|
54+| Client 非流式 | `examples/helloworld_client.cpp` | `tests/ut/client/` |
55+| Server 非流式 | `examples/helloworld_server.cpp` | `tests/ut/server/` |
56+| Client 流式 | `examples/streaming_client.cpp` | `tests/ut/transport/` |
57+| Server 流式 | `examples/streaming_server.cpp` | `tests/ut/server/` |
58+| Card Resolver | `examples/helloworld_client.cpp` | `tests/ut/client/test_http_card_resolver.cpp` |
59+ 
60+## 相关文档
61+ 
62+- [依赖说明](../dependencies.md)
63+- [测试说明](../testing.md)
64+- [错误处理说明](../errors.md)
65+- [日志说明](../logging.md)
66+- [主 README](../../README.md)
@@ -0,0 +1,134 @@
1+# A2A Client API
2+ 
3+## 发现 Agent Card
4+ 
5+### HTTP Card Resolver(推荐)
6+ 
7+```cpp
8+#include "client/http_card_resolver_builder.h"
9+ 
10+std::string baseUrl = "http://127.0.0.1:8888";
11+auto resolver = A2A::Client::HttpCardResolverBuilder::Build(baseUrl);
12+ 
13+auto cardFuture = resolver->GetAgentCard();
14+A2A::AgentCard card = cardFuture.get();
15+```
16+ 
17+默认路径为 `/.well-known/agent-card.json`(A2A 标准推荐方式)。
18+ 
19+## 创建客户端
20+ 
21+```cpp
22+#include "client/client_factory.h"
23+#include "client/client.h"
24+ 
25+A2A::Client::ClientConfig config;
26+config.streaming = false; // 非流式 message/send
27+config.polling = false;
28+ 
29+auto client = A2A::Client::ClientFactory::Create(card, config);
30+```
31+ 
32+也可传入自定义 `ClientTransport` 或 `ClientCallInterceptor` 列表,见 `client_factory.h`。
33+ 
34+## 生命周期
35+ 
36+推荐顺序:
37+ 
38+```
39+解析 AgentCard → 创建 Client → (注册 Consumer / Interceptor)→ RPC 调用 → Close()
40+```
41+ 
42+```cpp
43+// 发送消息(非流式)
44+std::mutex mtx;
45+std::condition_variable cv;
46+bool done = false;
47+ 
48+client->SendMessage(msg, nullptr, [&](const A2A::Client::ClientEvent& ev,
49+ const A2A::AgentCard&) {
50+ // 处理 Message / A2AError / Task 更新
51+ std::lock_guard<std::mutex> lock(mtx);
52+ done = true;
53+ cv.notify_one();
54+}).get();
55+ 
56+client->Close();
57+```
58+ 
59+- 多数 RPC 返回 `std::future`;通过 `future.get()` 等待完成或捕获异常。
60+- 远端 JSON-RPC 错误在 `future.get()` 时以 `A2A::A2AClientException` 子类抛出。
61+- 完整错误语义见 [errors.md](../errors.md)。
62+ 
63+## 常用 RPC
64+ 
65+| 方法 | 说明 |
66+|------|------|
67+| `GetCard()` | 获取 Agent Card(JSON-RPC `GetAgentCard` 或经传输层) |
68+| `SendMessage(msg, ctx, handler, timeout)` | 发送消息(`SendMessage` / `SendStreamingMessage`) |
69+| `GetTask(params)` | 查询任务(`GetTask`) |
70+| `CancelTask(params)` | 取消任务(`CancelTask`) |
71+| `Resubscribe(params, ctx, handler)` | 重新订阅任务事件(`SubscribeToTask`) |
72+| `SetTaskPushNotificationConfig` 等 | 推送通知配置 CRUD |
73+| `AddEventConsumer(c)` | 注册全局事件消费者 |
74+| `AddRequestMiddleware(m)` | 注册请求拦截器 |
75+| `Close()` | 关闭客户端并释放资源 |
76+ 
77+## 流式消息
78+ 
79+```cpp
80+A2A::Client::ClientConfig config;
81+config.streaming = true;
82+ 
83+auto client = A2A::Client::ClientFactory::Create(card, config);
84+ 
85+client->SendMessage(msg, &ctx, [](const A2A::Client::ClientEvent& ev,
86+ const A2A::AgentCard& agentCard) {
87+ // 可能多次回调:Task + StatusUpdate / ArtifactUpdate
88+}, 0);
89+```
90+ 
91+流式示例见 `examples/streaming_client.cpp`。
92+ 
93+## 回调与事件
94+ 
95+`ClientEvent` 类型:
96+ 
97+```cpp
98+std::variant<Message, A2AError, std::pair<Task, UpdateEvent>>
99+```
100+ 
101+| 组件 | 说明 |
102+|------|------|
103+| `Consumer` | 全局事件回调 |
104+| `ResponseHandler` | 单次 `SendMessage` / `Resubscribe` 的响应回调 |
105+| `ClientCallContext` | 每请求的 `state` / `headers` |
106+ 
107+## 配置要点
108+ 
109+`ClientConfig`(`client/client.h`):
110+ 
111+| 字段 | 说明 |
112+|------|------|
113+| `streaming` | 是否使用 `SendStreamingMessage` |
114+| `polling` | 非流式时是否轮询任务状态 |
115+| `supportedTransports` | 客户端支持的传输标签 |
116+| `acceptedOutputModes` | 接受的输出模式 |
117+| `pushNotificationConfigs` | 默认推送通知配置 |
118+ 
119+## 日志
120+ 
121+- **SDK 内部日志**:`A2A_LOG` + `SetLogLevel` / `SetLogCallback`(见 `a2a_log.h`)
122+- **协议数据**:`ClientEvent` 中的 `Message`、`A2AError`、任务更新(见 [protocol-mapping.md](protocol-mapping.md))
123+ 
124+## 示例
125+ 
126+- 完整流程:`examples/helloworld_client.cpp`
127+- 流式:`examples/streaming_client.cpp`
128+- 冒烟脚本:`scripts/run_example.sh`
129+ 
130+## 参见
131+ 
132+- [server.md](server.md)
133+- [protocol-mapping.md](protocol-mapping.md)
134+- 头文件:`include/client/client.h`
@@ -0,0 +1,67 @@
1+# A2A 协议方法 ↔ C++ API 对照
2+ 
3+SDK 内部 JSON-RPC 方法名见 `src/shared/common_types.h`。下表列出与 A2A 协议及公开 Client API 的对应关系。
4+ 
5+## Client 发起的请求
6+ 
7+| JSON-RPC method(SDK) | A2A 协议能力 | C++ API(`A2A::Client::Client`) |
8+|----------------------|--------------|----------------------------------|
9+| `SendMessage` | message/send | `SendMessage`(`streaming=false`) |
10+| `SendStreamingMessage` | message/stream | `SendMessage`(`streaming=true`) |
11+| `GetTask` | tasks/get | `GetTask(params)` |
12+| `CancelTask` | tasks/cancel | `CancelTask(params)` |
13+| `SubscribeToTask` | tasks/resubscribe | `Resubscribe(params, ctx, handler)` |
14+| `CreateTaskPushNotificationConfig` | tasks/pushNotificationConfig/set | `SetTaskPushNotificationConfig` |
15+| `GetTaskPushNotificationConfig` | tasks/pushNotificationConfig/get | `GetTaskPushNotificationConfig` |
16+| `ListTaskPushNotificationConfigs` | tasks/pushNotificationConfig/list | `ListTaskPushNotificationConfigs` |
17+| `DeleteTaskPushNotificationConfig` | tasks/pushNotificationConfig/delete | `DeleteTaskPushNotificationConfig` |
18+| `GetAgentCard` | agent/getCard(SDK 扩展标识) | `GetCard()` |
19+ 
20+> **Agent Card HTTP 路径(推荐)**:`GET /.well-known/agent-card.json`,经 `HttpCardResolverBuilder` / `A2ACardResolver::GetAgentCard()` 获取,无需 JSON-RPC。
21+ 
22+## Server 侧(由 SDK 路由 + 应用实现)
23+ 
24+| JSON-RPC method | Server 组件 |
25+|-----------------|-------------|
26+| `SendMessage` / `SendStreamingMessage` | `DefaultRequestHandler` → `AgentExecutor::Execute` |
27+| `GetTask` / `CancelTask` / `SubscribeToTask` | `TaskManager` + `AgentExecutor` |
28+| Push Notification 系列 | `PushNotificationConfigStore` + Client API 对应方法 |
29+| `GetAgentCard` | `JsonRpcHandler::OnGetAgentCard` + HTTP Agent Card 端点 |
30+ 
31+应用侧主要实现 **`AgentExecutor`**(及可选 **`TaskStore`**),无需直接注册每个 JSON-RPC 方法。
32+ 
33+## 流式响应事件类型
34+ 
35+Server 通过 SSE / 流式 JSON 推送时,SDK 解析为 `ClientEvent`:
36+ 
37+| 流类型常量 | 含义 |
38+|------------|------|
39+| `task` | 完整 Task 对象 |
40+| `status-update` | `TaskStatusUpdateEvent` |
41+| `artifact-update` | `TaskArtifactUpdateEvent` |
42+ 
43+Client 侧通过 `SendMessage` 的 `ResponseHandler` 或 `AddEventConsumer` 接收。
44+ 
45+## 运行时信息 vs 诊断日志
46+ 
47+| 概念 | API | 用途 |
48+|------|-----|------|
49+| SDK 诊断日志 | `A2A_LOG`、`SetLogCallback` | 调试 SDK 与应用程序(默认 stdout,见 [logging.md](../logging.md)) |
50+| 协议运行时数据 | `ClientEvent`、`Message`、`A2AError`、任务状态事件 | 智能体业务消息、任务状态、对外错误 |
51+ 
52+A2A **没有** MCP 式的 `notifications/message` 协议日志通道;任务进度与错误应通过上述协议事件传递。
53+ 
54+## 示例索引
55+ 
56+| 协议能力 | 示例路径 |
57+|----------|----------|
58+| 非流式 message/send | `examples/helloworld_client.cpp` / `helloworld_server.cpp` |
59+| 流式 message/stream | `examples/streaming_client.cpp` / `streaming_server.cpp` |
60+| Agent Card(HTTP) | `examples/helloworld_client.cpp`(`HttpCardResolverBuilder`) |
61+| JSON-RPC 冒烟 | `scripts/run_example.sh` |
62+ 
63+## 相关文档
64+ 
65+- [client.md](client.md)
66+- [server.md](server.md)
67+- [errors.md](../errors.md)
@@ -0,0 +1,133 @@
1+# A2A Server API
2+ 
3+## 创建服务端
4+ 
5+### HTTP Server
6+ 
7+```cpp
8+#include "server/http_server_builder.h"
9+#include "server/agent_executor.h"
10+#include "types.h"
11+ 
12+A2A::Server::HttpConfig httpConfig;
13+httpConfig.ip = "127.0.0.1";
14+httpConfig.port = 8888;
15+httpConfig.endpoint = "/jsonrpc"; // 默认
16+ 
17+A2A::AgentCard agentCard{};
18+agentCard.name = "ExampleAgent";
19+agentCard.version = "1.0.0";
20+// ... 配置 capabilities、supportedInterfaces 等
21+ 
22+auto executor = std::make_shared<MyAgentExecutor>();
23+ 
24+auto server = A2A::Server::HttpServerBuilder::Build(
25+ httpConfig,
26+ agentCard,
27+ {}, // extendedAgentCard(可选)
28+ executor,
29+ nullptr // taskStore(nullptr = 内存存储)
30+);
31+```
32+ 
33+Agent Card 同时通过 HTTP 暴露:`GET /.well-known/agent-card.json`。
34+ 
35+## 生命周期
36+ 
37+```
38+创建 → 实现 AgentExecutor → Build() → Start() → (处理请求)→ Stop()
39+```
40+ 
41+```cpp
42+int ret = server->Start();
43+if (ret != 0) {
44+ // 启动失败,检查 A2A_LOG 日志
45+ return 1;
46+}
47+ 
48+// 阻塞运行,直到收到退出信号
49+server->Stop();
50+```
51+ 
52+- `Start()` 成功返回 `0`,失败返回非 0(错误信息见日志)。
53+- `Start()` 可能抛出 `std::runtime_error`(如 transport bind 失败)。
54+- 注册与 handler 异常、JSON-RPC 错误映射见 [errors.md](../errors.md)。
55+- `Stop()` 后不应再处理新请求。
56+ 
57+## 实现 AgentExecutor
58+ 
59+```cpp
60+class MyAgentExecutor : public A2A::Server::AgentExecutor {
61+public:
62+ void Execute(std::shared_ptr<A2A::Server::RequestContext> context,
63+ std::shared_ptr<A2A::Server::TaskUpdater> taskUpdater) override
64+ {
65+ taskUpdater->StartWork();
66+ 
67+ A2A::Message response;
68+ response.role = A2A::Role::AGENT;
69+ // ... 构造 response.parts
70+ 
71+ taskUpdater->SendResponseMessage(response);
72+ }
73+ 
74+ void Cancel(std::shared_ptr<A2A::Server::RequestContext> context,
75+ std::shared_ptr<A2A::Server::TaskUpdater> taskUpdater) override
76+ {
77+ taskUpdater->Cancel();
78+ }
79+};
80+```
81+ 
82+- **同步处理**:在 `Execute` 内直接通过 `TaskUpdater` 推送状态与消息。
83+- **流式处理**:多次调用 `taskUpdater` 发布 `TaskStatusUpdateEvent` / `TaskArtifactUpdateEvent`。
84+- 不可恢复错误可抛出 `A2AServerError` 子类。
85+ 
86+## TaskUpdater 常用方法
87+ 
88+| 方法 | 说明 |
89+|------|------|
90+| `StartWork()` | 任务进入 WORKING 状态 |
91+| `SendResponseMessage(msg)` | 发送 Agent 回复消息 |
92+| `Cancel()` | 标记任务已取消 |
93+| 状态/产物更新 API | 流式场景下推送事件(见 `task_updater.h`) |
94+ 
95+## 自定义 TaskStore
96+ 
97+```cpp
98+auto store = std::make_shared<MyTaskStore>();
99+auto server = A2A::Server::HttpServerBuilder::Build(
100+ httpConfig, agentCard, {}, executor, store);
101+```
102+ 
103+默认 `nullptr` 使用内存 `InMemoryTaskStore`。
104+ 
105+## 配置要点
106+ 
107+`HttpConfig`:
108+ 
109+| 字段 | 说明 |
110+|------|------|
111+| `ip` | 监听 IP |
112+| `port` | 监听端口 |
113+| `endpoint` | JSON-RPC 路径,默认 `/jsonrpc` |
114+| `ioThreadNum` | I/O 事件循环线程数 |
115+ 
116+`AgentCard` 中 `supportedInterfaces` 应包含指向 `http://host:port/jsonrpc` 的 JSON-RPC 接口描述。
117+ 
118+## 日志
119+ 
120+- **SDK 诊断日志**:`A2A_LOG`(见 [logging.md](../logging.md))
121+- **对外错误**:通过 JSON-RPC error 或流式 `A2AError` 事件返回,非 SDK 日志
122+ 
123+## 示例
124+ 
125+- 非流式 Server:`examples/helloworld_server.cpp`
126+- 流式 Server:`examples/streaming_server.cpp`
127+- 冒烟脚本:`scripts/run_example.sh`
128+ 
129+## 参见
130+ 
131+- [client.md](client.md)
132+- [protocol-mapping.md](protocol-mapping.md)
133+- 头文件:`include/server/http_server_builder.h`
@@ -0,0 +1,90 @@
1+# A2A C++ SDK 依赖说明
2+ 
3+## 依赖分类
4+ 
5+| 类别 | 依赖 | 获取方式 |
6+|------|------|----------|
7+| **系统(需手动/脚本安装)** | OpenSSL、libcurl、libevent、nlohmann_json | `scripts/install_deps.sh` 或系统包管理器 |
8+| **CMake 自动拉取** | http_parser、Google Test 等 | 构建时 `third_party/third_party.cmake`(系统包优先,否则 FetchContent) |
9+| **测试专用** | Google Test、gcovr | 启用 `--with-tests` / `run_ut.sh` 时按需安装 |
10+ 
11+## 脚本解释器说明
12+ 
13+`scripts/` 下脚本均为 **Bash**(`#!/usr/bin/env bash`,含 `set -o pipefail` 等语法)。请使用 `bash scripts/...` 调用,**勿用 `sh`**;在 dash 等环境下 `sh scripts/build.sh` 会报错(如 `set: Illegal option -o pipefail`)。
14+ 
15+| 脚本 | 解释器 | 用途 |
16+|------|--------|------|
17+| `scripts/install_deps.sh` | **bash** | 安装 OpenSSL、libcurl、libevent 等系统开发包 |
18+| `scripts/build.sh` | **bash** | 配置与编译 SDK、示例、单元测试 |
19+| `scripts/run_ut.sh` | **bash** | 运行 CTest 并生成测试/覆盖率报告 |
20+| `scripts/run_example.sh` | **bash** | 示例冒烟测试 |
21+ 
22+## 版本要求
23+ 
24+| 依赖 | 最低版本 | 用途 |
25+|------|----------|------|
26+| C++ 编译器 | C++17 | 语言标准 |
27+| CMake | 3.15 | 构建系统 |
28+| OpenSSL | 1.1.1 | TLS、加密 |
29+| libcurl | 7.x+ | HTTP Client 传输 |
30+| nlohmann_json | 3.11.2 | JSON 序列化 |
31+| libevent | 2.1.12 | 事件循环(Server I/O) |
32+| http_parser | 2.9.4 | HTTP 解析 |
33+ 
34+## 系统包安装
35+ 
36+### 一键检查与安装(推荐)
37+ 
38+```bash
39+cd A2A/cpp-sdk
40+bash scripts/install_deps.sh
41+```
42+ 
43+脚本会检测 Ubuntu/Debian、RHEL/CentOS/Fedora/EulerOS、Arch 等,并安装 **libcurl**、**OpenSSL**、**libevent**、**nlohmann_json** 等开发包。
44+ 
45+### Ubuntu / Debian(手动)
46+ 
47+```bash
48+sudo apt-get update
49+sudo apt-get install -y \
50+ build-essential cmake \
51+ libssl-dev \
52+ libcurl4-openssl-dev \
53+ libevent-dev \
54+ nlohmann-json3-dev
55+```
56+ 
57+### CentOS / RHEL / Fedora / EulerOS(手动)
58+ 
59+```bash
60+sudo yum install -y \
61+ gcc-c++ cmake \
62+ openssl-devel \
63+ libcurl-devel \
64+ libevent-devel
65+```
66+ 
67+### Arch Linux(手动)
68+ 
69+```bash
70+sudo pacman -S --needed base-devel cmake openssl curl libevent nlohmann-json
71+```
72+ 
73+## 验证依赖
74+ 
75+```bash
76+# OpenSSL
77+openssl version
78+ 
79+# libcurl
80+curl-config --version
81+ 
82+# CMake
83+cmake --version
84+```
85+ 
86+## 说明
87+ 
88+- 其余第三方库在首次 `cmake` 配置时由 `third_party/third_party.cmake` 处理,一般无需单独安装。
89+- 若需离线构建,可预先安装上述系统包,并配置 CMake 使用系统提供的 json/libevent 等(见 `A2A_USE_SYSTEM_*` 选项)。
90+- 从其他机器同步工程时,建议清理 `third_party/*-subbuild` 后再配置,避免 CMakeCache 路径不一致。
@@ -0,0 +1,165 @@
1+# A2A C++ SDK 错误处理说明
2+ 
3+本文说明 SDK 中 **错误码、异常类型与返回值** 的语义及推荐处理方式。公开类型定义见 `include/error.h`、`include/types.h`。
4+ 
5+## 错误表达方式概览
6+ 
7+SDK 同时使用多种机制表达失败,**彼此不自动转换**:
8+ 
9+| 表达方式 | 典型场景 | 如何感知 |
10+|----------|----------|----------|
11+| `A2AClientException` 及子类 | Client 传输层、JSON-RPC、A2A 协议错误 | RPC:`future.get()` 抛异常 |
12+| `A2AServerError` 及子类 | Server handler 内不可恢复错误 | 映射为 JSON-RPC error 响应 |
13+| `A2AError`(结构体) | 流式 `ClientEvent` 中的协议错误 | `ResponseHandler` / `Consumer` 回调 |
14+| `int`(`Server::Start()`) | Server 启动失败 | 返回非 0,详情见日志 |
15+ 
16+## 公开类型:`A2AErrorCode` 与 `A2AError`
17+ 
18+### JSON-RPC 标准错误码
19+ 
20+```cpp
21+enum class A2AErrorCode : int {
22+ JSONRPC_PARSE_ERROR = -32700,
23+ JSONRPC_INVALID_REQUEST = -32600,
24+ JSONRPC_METHOD_NOT_FOUND = -32601,
25+ JSONRPC_INVALID_PARAMS = -32602,
26+ JSONRPC_INTERNAL_ERROR = -32603,
27+ // A2A 扩展码 -32001 … -32009、Client 码 -32101 … 等
28+};
29+```
30+ 
31+`A2AError` 结构体携带 `code`、`message` 等字段;`types.h` 中提供 `TaskNotFoundError`、`InvalidParamsError` 等便捷子类型。
32+ 
33+### Client 异常层次
34+ 
35+| 类型 | 说明 |
36+|------|------|
37+| `A2AClientException` | 基类;`errorCode` + `message` |
38+| `A2AClientHTTPError` | 非 2xx HTTP 响应;`statusCode` 为 HTTP 状态码 |
39+| `A2AClientJSONError` | JSON-RPC / A2A 协议错误;`errorCode` 为 wire code |
40+| `A2AClientTimeoutError` | 请求超时 |
41+ 
42+辅助 API:
43+ 
44+| 方法 | 说明 |
45+|------|------|
46+| `A2AClientException::Make(code, msg)` | 构造 `exception_ptr` 供 future 使用 |
47+| `A2AClientException::TryParse(e, out)` | 从 `std::exception` 解析为 `A2AError` |
48+ 
49+> **注意**:`A2AClientException` 继承 `std::runtime_error`。捕获时建议 **先** `catch (const A2A::A2AClientJSONError&)` / 子类,再 `catch (const A2A::A2AClientException&)`,最后 `catch (const std::runtime_error&)`。
50+ 
51+## Client 侧
52+ 
53+### RPC 与 `future.get()`
54+ 
55+`SendMessage`、`GetTask`、`CancelTask`、`GetCard` 等返回 `std::future`。在 `future.get()` 时可能抛出:
56+ 
57+| 异常 | 原因 |
58+|------|------|
59+| `A2AClientJSONError` | 对端返回 JSON-RPC / A2A error |
60+| `A2AClientHTTPError` | HTTP 传输失败(非 2xx) |
61+| `A2AClientTimeoutError` | 请求超时 |
62+| `A2AClientException` | 其他 Client 错误 |
63+| `std::runtime_error` | SDK 本地状态错误等 |
64+ 
65+**推荐捕获顺序:**
66+ 
67+```cpp
68+try {
69+ auto task = client->GetTask(params).get();
70+} catch (const A2A::A2AClientJSONError& e) {
71+ // 协议错误:读 e.errorCode、e.message
72+} catch (const A2A::A2AClientHTTPError& e) {
73+ // HTTP 错误:读 e.statusCode
74+} catch (const A2A::A2AClientException& e) {
75+ // 其他 Client 错误
76+} catch (const std::runtime_error& e) {
77+ // SDK 本地错误
78+}
79+```
80+ 
81+### 流式 `SendMessage` 与 `ClientEvent`
82+ 
83+`SendMessage` 的 `ResponseHandler` 可能收到 `ClientEvent`:
84+ 
85+```cpp
86+std::variant<Message, A2AError, std::pair<Task, UpdateEvent>>
87+```
88+ 
89+- **非流式**:通常收到 `Message` 或 `A2AError`。
90+- **流式**:可能多次收到 `std::pair<Task, UpdateEvent>`(状态/产物更新)。
91+ 
92+协议层错误可能 **同时** 通过 handler 中的 `A2AError` 与 `future.get()` 异常表达,调用方应处理两种路径。
93+ 
94+### 常见 Client 场景
95+ 
96+| 场景 | 表现 | 处理建议 |
97+|------|------|----------|
98+| 远端方法不存在 | `A2AClientJSONError`,code 多为 `-32601` | 检查 Agent Card URL 与 Server 版本 |
99+| 任务不存在 | code 常为 `TASK_NOT_FOUND`(-32001) | 校验 taskId |
100+| HTTP 连接失败 | `A2AClientHTTPError` | 检查网络与 `LD_LIBRARY_PATH` |
101+| Card 解析失败 | `A2AClientJSONError` | 检查 `/.well-known/agent-card.json` |
102+ 
103+## Server 侧
104+ 
105+### 启动与生命周期
106+ 
107+| 场景 | 表现 | 处理建议 |
108+|------|------|----------|
109+| `Start()` 失败 | 返回非 0 | 查 `A2A_LOG` 日志(端口占用、bind 失败等) |
110+| `HttpServerBuilder::Build` 配置非法 | `std::runtime_error` | 修正 `HttpConfig` / AgentCard |
111+| `AgentExecutor::Execute` 抛 `A2AServerError` | 映射为 JSON-RPC error | 使用合适的 `statusCode` |
112+ 
113+`Start()` **一般不抛异常**;失败原因需通过日志排查。
114+ 
115+### 请求处理中的 JSON-RPC 错误
116+ 
117+Server 收到请求后,常见映射:
118+ 
119+| 情况 | 典型 `A2AErrorCode` |
120+|------|---------------------|
121+| 未知 method | `JSONRPC_METHOD_NOT_FOUND`(-32601) |
122+| params 类型/字段错误 | `JSONRPC_INVALID_PARAMS`(-32602) |
123+| 任务不存在 | `TASK_NOT_FOUND`(-32001) |
124+| 方法未实现 | `MethodNotImplementedError` → -32601 |
125+| 内部未预期异常 | `JSONRPC_INTERNAL_ERROR`(-32603) |
126+ 
127+### AgentExecutor 业务错误
128+ 
129+在 `Execute` / `Cancel` 中通过 `TaskUpdater` 发布状态与消息是推荐路径;不可恢复错误可抛出 `A2AServerError` 或其子类,由 SDK 转为 JSON-RPC error。
130+ 
131+## 错误传播路径(Client RPC)
132+ 
133+```
134+远端 JSON-RPC error
135+ → 传输层解析
136+ → promise::set_exception(A2AClientJSONError)
137+ → future.get() 抛出 A2AClientJSONError
138+```
139+ 
140+传输失败等本地路径可能抛出 `A2AClientHTTPError` 或 `A2AClientTimeoutError`。
141+ 
142+## 与协议事件的区别
143+ 
144+| 概念 | 相关 API | 说明 |
145+|------|----------|------|
146+| 错误 / 异常 | `A2AClientException`、`A2AError` | 调用失败或任务错误 |
147+| 任务状态 / 消息 | `ClientEvent`、`TaskStatusUpdateEvent` | 正常协议数据流,**不是** SDK 诊断日志 |
148+ 
149+详见 [logging.md](logging.md)。
150+ 
151+## 示例与测试参考
152+ 
153+| 场景 | 参考 |
154+|------|------|
155+| Client 异常解析 | `tests/ut/shared/test_error.cpp` |
156+| JSON-RPC 错误响应 | `tests/ut/server/test_default_request_handler.cpp` |
157+| HTTP 错误 | `tests/ut/client/test_http_card_resolver.cpp` |
158+| 示例中的错误处理 | `examples/helloworld_client.cpp` |
159+ 
160+## 相关文档
161+ 
162+- [client.md](api/client.md) — Client API
163+- [server.md](api/server.md) — Server 生命周期
164+- [protocol-mapping.md](api/protocol-mapping.md) — 协议方法对照
165+- [error.h](../include/error.h) — 类型定义
@@ -0,0 +1,103 @@
1+# A2A C++ SDK 日志说明
2+ 
3+## 两套日志体系
4+ 
5+SDK 中存在 **SDK 诊断日志** 与 **协议运行时数据** 两类机制,彼此不自动联动:
6+ 
7+| 体系 | API | 输出目标 | 用途 |
8+|------|-----|----------|------|
9+| **SDK 诊断日志** | `A2A_LOG`、`SetLogLevel`、`SetLogCallback` | 默认 **stdout**(可自定义) | SDK 与应用程序内部调试 |
10+| **协议运行时数据** | `ClientEvent`、`TaskStatusUpdateEvent`、`A2AError` 等 | JSON-RPC 响应 / SSE 流 | 任务状态、业务消息、对外错误 |
11+ 
12+A2A 协议当前 **未定义** 独立的协议级日志推送通道。协议方法对照见 [api/protocol-mapping.md](api/protocol-mapping.md#运行时信息-vs-诊断日志)。
13+ 
14+## SDK 诊断日志(`a2a_log.h`)
15+ 
16+### 基本用法
17+ 
18+```cpp
19+#include "a2a_log.h"
20+ 
21+A2A::Log::SetLogLevel(A2A::Log::A2A_LOG_LEVEL::INFO); // 默认 INFO
22+ 
23+A2A_LOG(A2A::Log::A2A_LOG_LEVEL::INFO,
24+ std::string("server started on port ") + std::to_string(port));
25+```
26+ 
27+`A2A_LOG` 第一个参数为级别,第二个参数为 **已拼接好的 `std::string`**(不支持 `printf` 风格占位符)。
28+ 
29+### 级别
30+ 
31+| 常量 | 数值 | 说明 |
32+|------|------|------|
33+| `A2A_LOG_LEVEL::DEBUG` | 3 | 调试 |
34+| `A2A_LOG_LEVEL::INFO` | 4 | 信息(默认阈值) |
35+| `A2A_LOG_LEVEL::WARN` | 5 | 警告 |
36+| `A2A_LOG_LEVEL::ERROR` | 6 | 错误 |
37+| `A2A_LOG_LEVEL::FATAL` | 7 | 致命 |
38+ 
39+`SetLogLevel` 设置全局阈值;**低于阈值的日志在 `A2A_LOG` 入口即被过滤**,自定义 callback 收到的也是过滤后的消息。默认 sink `A2aPrintfImpl` 在输出前也会再次检查级别。
40+ 
41+无效级别(小于 `DEBUG` 或大于 `FATAL`)调用 `SetLogLevel` 会返回 `-1`,级别保持不变。
42+ 
43+### 输出格式
44+ 
45+通过 `A2A_LOG` 输出的每行前缀格式为:
46+ 
47+```text
48+[YYYY-MM-DD HH:MM:SS.mmm] [tid] [LEVEL] file.cpp::Function:[line] message
49+```
50+ 
51+其中 `LEVEL` 为 `DEBUG` / `INFO` / `WARN` / `ERROR` / `FATAL` 之一;`tid` 为 Linux 线程 ID(`syscall(SYS_gettid)`)。级别名由 SDK 自动写入;`A2aLogCallback` 的第一个参数仍为枚举值 `A2A_LOG_LEVEL`。
52+ 
53+### 默认输出:stdout
54+ 
55+默认回调 `A2aPrintfImpl` 通过 `printf` 写入 **stdout**(末尾自动换行)。
56+ 
57+> **注意**:若应用将 **stdout** 用于其他用途(如管道输出、与协议数据混写),建议在进程启动早期通过 `SetLogCallback` 将日志重定向到 **stderr** 或文件:
58+ 
59+```cpp
60+void StderrLogCallback(A2A::Log::A2A_LOG_LEVEL /*level*/, std::string message) {
61+ fprintf(stderr, "%s\n", message.c_str());
62+}
63+ 
64+A2A::Log::SetLogCallback(StderrLogCallback);
65+```
66+ 
67+A2A 传输基于 HTTP + JSON-RPC,通常不受 stdout 日志影响;上述注意主要适用于自定义集成场景。
68+ 
69+### 自定义回调
70+ 
71+```cpp
72+void MyLogCallback(A2A::Log::A2A_LOG_LEVEL level, std::string message) {
73+ // level 已通过 SetLogLevel 过滤;此处无需再次判断
74+ my_logger.write(message);
75+}
76+ 
77+A2A::Log::SetLogCallback(MyLogCallback);
78+```
79+ 
80+行为说明:
81+ 
82+- `SetLogCallback` **进程内仅可成功调用一次**;重复调用返回 `-1`,并向 stdout 打印提示 `log callback can only be set once`。
83+- 设置自定义回调后 **无法通过 API 恢复** 默认 `A2aPrintfImpl`;如需切换 sink,应在自定义回调内部分发。
84+- 若 `logCallback` 为 `nullptr`,`A2A_LOG` **不会输出**。
85+ 
86+### 与常见日志库集成
87+ 
88+将 `A2A_LOG` 桥接到 spdlog、glog 等时,在 `SetLogCallback` 注册的函数内转发 `message` 即可;级别映射需自行对照上表。
89+ 
90+## 示例
91+ 
92+| 场景 | 参考 |
93+|------|------|
94+| 级别设置与过滤 | `tests/ut/log/test_logger.cpp` |
95+| `LogInternal` / `GetLogLevelName` | `tests/ut/log/test_a2a_log_internal.cpp` |
96+| SDK 内部用法 | `src/client/connection/libcurl_conn.cpp`、`src/server/net/tcp_listener.cpp` 等 |
97+| 协议事件对照 | [api/protocol-mapping.md](api/protocol-mapping.md) |
98+ 
99+## 相关文档
100+ 
101+- [client.md](api/client.md) — 客户端 API
102+- [server.md](api/server.md) — 服务端 API
103+- [testing.md](testing.md) — 测试说明
@@ -0,0 +1,134 @@
1+# A2A C++ SDK 测试说明
2+ 
3+## 概述
4+ 
5+测试基于 **Google Test**,通过 **CTest** 发现与运行。测试源码位于 `tests/ut/`,默认**不编译**(需显式开启 `A2A_ENABLE_TESTS`)。
6+ 
7+构建与跑测脚本(`build.sh`、`run_ut.sh`、`install_deps.sh`)均为 **Bash**,请使用 `bash scripts/...` 调用,勿用 `sh`(详见 [依赖说明 - 脚本解释器](dependencies.md#脚本解释器说明))。
8+ 
9+## 快速运行
10+ 
11+```bash
12+cd A2A/cpp-sdk
13+ 
14+# 1. Debug + 启用测试 + 运行 ctest(默认含覆盖率与 ASAN)
15+bash scripts/run_ut.sh
16+ 
17+# 2. 更快:跳过覆盖率与 ASAN
18+bash scripts/run_ut.sh --no-coverage --no-asan
19+```
20+ 
21+手动构建后运行:
22+ 
23+```bash
24+bash scripts/build.sh -u -t Debug
25+cd build
26+export LD_LIBRARY_PATH="../output/lib:${LD_LIBRARY_PATH:-}"
27+ctest --output-on-failure -V
28+```
29+ 
30+## 构建选项
31+ 
32+通过 `scripts/build.sh` 传入:
33+ 
34+| 选项 | CMake 变量 | 说明 |
35+|------|------------|------|
36+| `-t, --type <type>` | `CMAKE_BUILD_TYPE` | 构建类型:`Debug`、`Release`、`RelWithDebInfo`、`MinSizeRel`(默认 `Release`) |
37+| `-u, --with-tests` | `A2A_ENABLE_TESTS=ON` | 编译单元测试 |
38+| `-c, --coverage` | `A2A_ENABLE_COVERAGE=ON` | 启用覆盖率(隐含 `--with-tests`) |
39+| `--no-client` | `A2A_BUILD_CLIENT=OFF` | 跳过 Client 模块 |
40+| `--no-server` | `A2A_BUILD_SERVER=OFF` | 跳过 Server 模块 |
41+| `--asan` | `ASAN=enable` | 启用 AddressSanitizer(Debug) |
42+ 
43+`run_ut.sh` 默认启用 **AddressSanitizer** 与 **覆盖率**(gcovr)。可通过 `--no-coverage`、`--no-asan` 或 `A2A_SKIP_ASAN=1` 关闭。
44+ 
45+## 覆盖率与报告
46+ 
47+```bash
48+# 带覆盖率编译并运行(run_ut.sh 默认)
49+bash scripts/run_ut.sh
50+ 
51+# 仅构建覆盖率
52+bash scripts/build.sh -t Debug -c
53+```
54+ 
55+报告默认输出:
56+ 
57+| 文件 | 说明 |
58+|------|------|
59+| `build/coverage_report.html` | 覆盖率 HTML(需 gcovr) |
60+ 
61+`run_ut.sh` 会在缺少 gcovr 时跳过 HTML 报告并给出安装提示(`pip install gcovr`)。
62+ 
63+## 测试模块结构
64+ 
65+```
66+tests/ut/
67+├── client/ # 客户端、Card Resolver、Transport
68+├── server/ # 服务端、HTTP Server、Request Handler
69+├── shared/ # 错误、HTTP、UUID、定时器等
70+├── transport/ # HTTP Server Transport、流式发射器
71+├── event/ # 事件系统
72+├── log/ # 日志模块
73+├── utils/ # 消息工具、ID 生成
74+└── fixtures/ # 共享 mock 与辅助工具
75+```
76+ 
77+编写约定:
78+ 
79+- 测试源文件命名 `test_<module>.cpp`,尽量与 `src/<module>/` 对应。
80+- `a2a_ut_test` 二进制链接 `liba2a.so`,不重复编译全部 SDK 源码。
81+- 需要 bind/listen 的测试优先使用 `A2A::Test::GetFreeTcpPort()`(`fixtures/test_network.h`),避免硬编码端口。
82+- 复用 `fixtures/` 中的 mock(`mock_agent_executor.h`、`mock_task_store.h`、`test_agent_card.h` 等)。
83+- 禁止占位测试(如 `EXPECT_TRUE(true)`);每个用例须断言真实行为。
84+ 
85+## 常见问题
86+ 
87+### 构建目录不存在
88+ 
89+```
90+Error: Build directory not found
91+```
92+ 
93+先执行:`bash scripts/build.sh -u -t Debug`
94+ 
95+### 无测试用例
96+ 
97+确认构建时使用了 `--with-tests`,且未使用 `--no-client` / `--no-server` 裁剪掉被测模块。
98+ 
99+### 运行时找不到 liba2a.so
100+ 
101+```bash
102+export LD_LIBRARY_PATH="$(pwd)/output/lib:$(pwd)/build:${LD_LIBRARY_PATH:-}"
103+```
104+ 
105+### CMake 配置失败(stale FetchContent 缓存)
106+ 
107+从其他机器 rsync 后可能出现路径不一致。清理后重编:
108+ 
109+```bash
110+rm -rf third_party/*-subbuild third_party/*-build build _deps
111+bash scripts/run_ut.sh --no-coverage --no-asan
112+```
113+ 
114+### 端口冲突
115+ 
116+部分测试使用动态端口;若仍失败,可单独运行模块测试:
117+ 
118+```bash
119+cd build
120+ctest -R LoggerTest --output-on-failure
121+```
122+ 
123+## 与示例的关系
124+ 
125+- **单元测试**:验证 SDK 内部模块与协议逻辑。
126+- **示例冒烟**:`scripts/run_example.sh` 验证可执行示例链路,不属于 CTest。
127+ 
128+两者互补,发布前建议均跑通。
129+ 
130+## 相关文档
131+ 
132+- [README.md](../README.md) — 快速入门与构建选项
133+- [api/README.md](api/README.md) — 公开 API 索引
134+- [logging.md](logging.md) — 日志说明
@@ -1,18 +1,21 @@
1- 
2include_directories(${CMAKE_SOURCE_DIR}/include)1include_directories(${CMAKE_SOURCE_DIR}/include)
3 2 
4-add_executable(helloworld_server helloworld_server.cpp)3+if(A2A_BUILD_CLIENT)
5-set_property(TARGET helloworld_server PROPERTY C_STANDARD 11)4+ add_executable(helloworld_client helloworld_client.cpp)
6-target_link_libraries(helloworld_server PRIVATE a2a pthread)5+ set_property(TARGET helloworld_client PROPERTY C_STANDARD 11)
6+ target_link_libraries(helloworld_client PRIVATE a2a)
7 7 
8-add_executable(streaming_server streaming_server.cpp)8+ add_executable(streaming_client streaming_client.cpp)
9-set_property(TARGET streaming_server PROPERTY C_STANDARD 11)9+ set_property(TARGET streaming_client PROPERTY C_STANDARD 11)
10-target_link_libraries(streaming_server PRIVATE a2a pthread)10+ target_link_libraries(streaming_client PRIVATE a2a)
11+endif()
11 12 
12-add_executable(helloworld_client helloworld_client.cpp)13+if(A2A_BUILD_SERVER)
13-set_property(TARGET helloworld_client PROPERTY C_STANDARD 11)14+ add_executable(helloworld_server helloworld_server.cpp)
14-target_link_libraries(helloworld_client PRIVATE a2a pthread)15+ set_property(TARGET helloworld_server PROPERTY C_STANDARD 11)
16+ target_link_libraries(helloworld_server PRIVATE a2a pthread)
15 17 
16-add_executable(streaming_client streaming_client.cpp)18+ add_executable(streaming_server streaming_server.cpp)
17-set_property(TARGET streaming_client PROPERTY C_STANDARD 11)19+ set_property(TARGET streaming_server PROPERTY C_STANDARD 11)
18-target_link_libraries(streaming_client PRIVATE a2a pthread)20+ target_link_libraries(streaming_server PRIVATE a2a pthread)
21+endif()
@@ -5,6 +5,7 @@
5#ifndef A2A_LOG_INCLUDE_H_5#ifndef A2A_LOG_INCLUDE_H_
6#define A2A_LOG_INCLUDE_H_6#define A2A_LOG_INCLUDE_H_
7 7 
8+#include <stdint.h>
8#include <string.h>9#include <string.h>
9#include <sys/syscall.h>10#include <sys/syscall.h>
10#include <sys/types.h>11#include <sys/types.h>
@@ -15,56 +16,101 @@
15#include <sstream>16#include <sstream>
16#include <string>17#include <string>
17 18 
18-// Time-related constants for logging19+namespace A2A::Log {
20+ 
21+/** @brief Nanoseconds per millisecond, used for timestamp formatting. */
19constexpr int32_t A2A_NANOS_PER_MILLISECOND = 1000000;22constexpr int32_t A2A_NANOS_PER_MILLISECOND = 1000000;
23+ 
24+/** @brief Width of the millisecond field in log timestamps. */
20constexpr int32_t A2A_TIMESTAMP_MILLIS_WIDTH = 3;25constexpr int32_t A2A_TIMESTAMP_MILLIS_WIDTH = 3;
21 26 
22-enum A2A_LOG_LEVEL {27+/**
23- A2A_LOG_LEVEL_DEBUG = 3,28+ * @brief Log severity levels (ordered from most to least verbose).
24- A2A_LOG_LEVEL_INFO = 4,29+ * @note 日志级别,数值越大表示越严重。
25- A2A_LOG_LEVEL_WARN = 5,30+ */
26- A2A_LOG_LEVEL_ERROR = 6,31+enum class A2A_LOG_LEVEL {
27- A2A_LOG_LEVEL_FATAL = 732+ DEBUG = 3,
33+ INFO = 4,
34+ WARN = 5,
35+ ERROR = 6,
36+ FATAL = 7
28};37};
29 38 
30-typedef void (*A2aLogCallback)(A2A_LOG_LEVEL logLevel, std::string message);39+/**
31-extern A2aLogCallback g_logCallback;40+ * @brief User-provided callback invoked for each log line.
41+ * @param logLevel Severity of the message.
42+ * @param message Fully formatted log line.
43+ */
44+using A2aLogCallback = void (*)(A2A_LOG_LEVEL logLevel, std::string message);
32 45 
46+/** @brief Active log sink; defaults to @ref A2aPrintfImpl. nullptr suppresses all output. */
47+extern A2aLogCallback logCallback;
48+ 
49+/**
50+ * @brief Default log sink: writes to stdout via @c printf (appends newline).
51+ * @param logLevel Severity of the message (filtered against @ref GetLogLevel).
52+ * @param message Fully formatted log line without trailing newline.
53+ */
33void A2aPrintfImpl(A2A_LOG_LEVEL logLevel, std::string message);54void A2aPrintfImpl(A2A_LOG_LEVEL logLevel, std::string message);
34 55 
35-int32_t SetLogCallback(A2aLogCallback logCallback);56+/**
36-int32_t SetLogLevel(A2A_LOG_LEVEL logLevel);57+ * @brief Register a custom log callback (process-wide, once only).
58+ * @param[in] a2aLogCallback Callback to receive formatted log lines.
59+ * @return 0 on success, @c -1 if a callback was already registered.
60+ */
61+int32_t SetLogCallback(const A2aLogCallback a2aLogCallback);
62+ 
63+/**
64+ * @brief Set the minimum severity that is emitted.
65+ * @param[in] logLevel Minimum level to log.
66+ * @return 0 on success, non-zero on failure.
67+ */
68+int32_t SetLogLevel(const A2A_LOG_LEVEL logLevel);
69+ 
70+/**
71+ * @brief Get the current minimum log level.
72+ * @return Active minimum severity.
73+ */
37A2A_LOG_LEVEL GetLogLevel(void);74A2A_LOG_LEVEL GetLogLevel(void);
38 75 
39-// Helper function to get current timestamp76+/**
77+ * @brief Get the string name for a log level (e.g. @c "INFO").
78+ * @param[in] level Log severity.
79+ * @return @c "DEBUG" / @c "INFO" / @c "WARN" / @c "ERROR" / @c "FATAL", or @c "UNKNOWN".
80+ */
81+const char* GetLogLevelName(A2A_LOG_LEVEL level);
82+ 
83+/**
84+ * @brief Format the current wall-clock time into a string.
85+ * @param[out] timestamp Receives "YYYY-MM-DD HH:MM:SS.mmm".
86+ */
40static inline void GetCurrentTimeStamp(std::string& timestamp)87static inline void GetCurrentTimeStamp(std::string& timestamp)
41{88{
42- // Get current time with millisecond precision using clock_gettime
43 struct timespec ts;89 struct timespec ts;
44 struct tm tmInfo;90 struct tm tmInfo;
45 clock_gettime(CLOCK_REALTIME, &ts);91 clock_gettime(CLOCK_REALTIME, &ts);
46 localtime_r(&ts.tv_sec, &tmInfo);92 localtime_r(&ts.tv_sec, &tmInfo);
47 93 
48- // Format: YYYY-MM-DD HH:MM:SS.mmm
49 char dateTimeBuf[32] = {0};94 char dateTimeBuf[32] = {0};
50 std::strftime(dateTimeBuf, sizeof(dateTimeBuf), "%Y-%m-%d %H:%M:%S", &tmInfo);95 std::strftime(dateTimeBuf, sizeof(dateTimeBuf), "%Y-%m-%d %H:%M:%S", &tmInfo);
51 96 
52 int32_t millis = static_cast<int32_t>(ts.tv_nsec / A2A_NANOS_PER_MILLISECOND);97 int32_t millis = static_cast<int32_t>(ts.tv_nsec / A2A_NANOS_PER_MILLISECOND);
53 98 
54 std::ostringstream oss;99 std::ostringstream oss;
55- oss << dateTimeBuf << '.'100+ oss << dateTimeBuf << '.' <<
56- << std::setfill('0') << std::setw(A2A_TIMESTAMP_MILLIS_WIDTH) << millis;101+ std::setfill('0') << std::setw(A2A_TIMESTAMP_MILLIS_WIDTH) << millis;
57 timestamp = oss.str();102 timestamp = oss.str();
58}103}
59 104 
60-namespace A2A::Log {105+// Internal helper to reduce macro lines and handle C++ string formatting.
61- 
62-// Internal helper to reduce macro lines and handle C++ string formatting
63template<typename... Args>106template<typename... Args>
64inline void LogInternal(A2A_LOG_LEVEL level, const char* file, const char* func, int line,107inline void LogInternal(A2A_LOG_LEVEL level, const char* file, const char* func, int line,
65 const std::string& format, Args&&... args)108 const std::string& format, Args&&... args)
66{109{
67- if (g_logCallback == nullptr) {110+ if (logCallback == nullptr) {
111+ return;
112+ }
113+ if (level < GetLogLevel()) {
68 return;114 return;
69 }115 }
70 116 
@@ -73,18 +119,25 @@ inline void LogInternal(A2A_LOG_LEVEL level, const char* file, const char* func,
73 const char* filename = strrchr(file, '/');119 const char* filename = strrchr(file, '/');
74 filename = filename ? filename + 1 : file;120 filename = filename ? filename + 1 : file;
75 121 
76- std::string prefix = "[" + timestamp + "] [" + std::to_string(syscall(SYS_gettid)) + "] " +122+ std::string prefix = "[" + timestamp + "] [" + std::to_string(syscall(SYS_gettid)) + "] [" +
77- std::string(filename) + "::" + std::string(func) + ":[" + std::to_string(line) + "] ";123+ std::string(GetLogLevelName(level)) + "] " + std::string(filename) + "::" +
78- std::ostringstream oss;124+ std::string(func) + ":[" + std::to_string(line) + "] ";
79- oss << prefix << format;125+ 
80- g_logCallback(level, oss.str());126+ static_assert(sizeof...(Args) == 0,
127+ "A2A_LOG expects C++-style string composition");
128+ logCallback(level, prefix + format);
81}129}
82 130 
83} // namespace A2A::Log131} // namespace A2A::Log
84 132 
133+/**
134+ * @brief Log a diagnostic message via @ref LogInternal.
135+ * @param level One of @c A2A::Log::A2A_LOG_LEVEL values.
136+ * @param format Message body as a pre-composed @c std::string (not printf-style).
137+ */
85#define A2A_LOG_COMMON(logLevel, format, ...) \138#define A2A_LOG_COMMON(logLevel, format, ...) \
86- ::A2A::Log::LogInternal(logLevel, __FILE__, __FUNCTION__, __LINE__, format, ##__VA_ARGS__)139+ ::A2A::Log::LogInternal(::A2A::Log::logLevel, __FILE__, __FUNCTION__, __LINE__, format, ##__VA_ARGS__)
87 140 
88#define A2A_LOG(level, format, ...) A2A_LOG_COMMON(level, format, ##__VA_ARGS__)141#define A2A_LOG(level, format, ...) A2A_LOG_COMMON(level, format, ##__VA_ARGS__)
89 142 
90-#endif143+#endif
@@ -1,41 +1,45 @@
1-/*1+/*
2- * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.2+ * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
3- */3+ */
4- 4+ 
5-#ifndef A2A_CARD_RESOLVER5+#ifndef A2A_CARD_RESOLVER
6-#define A2A_CARD_RESOLVER6+#define A2A_CARD_RESOLVER
7- 7+ 
8-#include <optional>8+#include <optional>
9-#include <string>9+#include <string>
10-#include <future>10+#include <future>
11- 11+ 
12-#include "types.h"12+#include "types.h"
13- 13+ 
14-namespace A2A::Client {14+namespace A2A::Client {
15- 15+ 
16-class A2ACardResolver {16+/**
17-public:17+ * @brief Resolves AgentCard documents from a remote or local source.
18- /**18+ * @note 代理卡片解析器抽象接口。
19- * @brief destructor19+ */
20- */20+class A2ACardResolver {
21- virtual ~A2ACardResolver() = default;21+public:
22- 22+ /** @brief Virtual destructor. */
23- /**23+ virtual ~A2ACardResolver() = default;
24- * @brief get AgentCard from relative path24+ 
25- *25+ /**
26- * @param[in] relativeCardPath relative card path26+ * @brief Fetch an agent card from a relative path.
27- * @return future to valid AgentCard if read successful27+ * @param[in] relativeCardPath Optional path relative to the resolver base URL.
28- */28+ * @return Future that completes with the resolved AgentCard.
29- virtual std::future<AgentCard> GetAgentCard(29+ * @throws A2AClientHTTPError on non-2xx HTTP status.
30- const std::optional<std::string>& relativeCardPath = std::nullopt) const = 0;30+ * @throws A2AClientJSONError on invalid card JSON.
31- 31+ */
32- /**32+ virtual std::future<AgentCard> GetAgentCard(
33- * @brief get all AgentCard from local path33+ const std::optional<std::string>& relativeCardPath = std::nullopt) const = 0;
34- *34+ 
35- * @return future to vector of AgentCards35+ /**
36- */36+ * @brief Fetch all agent cards from the resolver source.
37- virtual std::future<std::vector<AgentCard>> GetAllAgentCards() const = 0;37+ * @return Future that completes with a vector of AgentCard objects.
38-};38+ * @throws A2AClientHTTPError on transport failure.
39-} // namespace A2A::Client39+ */
40- 40+ virtual std::future<std::vector<AgentCard>> GetAllAgentCards() const = 0;
41-#endif // A2A_CARD_RESOLVER41+};
42+ 
43+} // namespace A2A::Client
44+ 
45+#endif // A2A_CARD_RESOLVER
@@ -1,160 +1,180 @@
1-/*1+/*
2- * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.2+ * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
3- */3+ */
4- 4+ 
5-#ifndef A2A_CLIENT5+#ifndef A2A_CLIENT
6-#define A2A_CLIENT6+#define A2A_CLIENT
7- 7+ 
8-#include <functional>8+#include <functional>
9-#include <future>9+#include <future>
10-#include <string>10+#include <string>
11-#include <memory>11+#include <memory>
12- 12+#include <vector>
13-#include "client/client_call_interceptor.h"13+ 
14-#include "types.h"14+#include "client/client_call_interceptor.h"
15- 15+#include "types.h"
16-namespace A2A::Client {16+ 
17- 17+namespace A2A::Client {
18-struct ClientConfig {18+ 
19- bool streaming = true; // Whether client supports streaming19+/**
20- bool polling = false; // Prefer polling for message/send20+ * @brief Configuration for A2A client behaviour.
21- std::vector<std::string> supportedTransports; // ordered labels (e.g., "JSONRPC")21+ */
22- bool useClientPreference = false; // Prefer client list over server preferences22+struct ClientConfig {
23- std::vector<std::string> acceptedOutputModes; // accepted output modes23+ /** @brief Whether the client supports streaming (message/stream). */
24- std::vector<PushNotificationConfig> pushNotificationConfigs; // default push configs24+ bool streaming = true;
25-};25+ /** @brief Prefer polling over streaming for message/send. */
26- 26+ bool polling = false;
27-// Event alias: (Task, optional update) or a Message27+ /** @brief Ordered transport labels (e.g. "JSONRPC"). */
28-using UpdateEvent = std::variant<std::monostate, TaskStatusUpdateEvent, TaskArtifactUpdateEvent>;28+ std::vector<std::string> supportedTransports;
29-using ClientEvent = std::variant<Message, std::pair<Task, UpdateEvent>>;29+ /** @brief Prefer client transport list over server preferences. */
30- 30+ bool useClientPreference = false;
31-// Consumer: receives ClientEvent or Message with AgentCard31+ /** @brief Accepted output modes for message/send. */
32-using Consumer = std::function<void(const ClientEvent&, const A2A::AgentCard&)>;32+ std::optional<std::vector<std::string>> acceptedOutputModes;
33-using ResponseHandler = std::function<void(const ClientEvent&, const A2A::AgentCard&)>;33+ /** @brief Default push-notification configs. */
34- 34+ std::vector<PushNotificationConfig> pushNotificationConfigs;
35-class Client {35+};
36-public:36+ 
37- /**37+/** @brief Streaming update payload: status or artifact event. */
38- * @brief destructor38+using UpdateEvent = std::variant<std::monostate, TaskStatusUpdateEvent, TaskArtifactUpdateEvent>;
39- */39+ 
40- virtual ~Client() = default;40+/** @brief Client-side event: message, error, or task update. */
41- 41+using ClientEvent = std::variant<Message, A2AError, std::pair<Task, UpdateEvent>>;
42- /**42+ 
43- * @brief send message to server and get return via consumers43+/** @brief Callback that receives ClientEvent updates with the agent card. */
44- * For streaming, this will synchronously call consumer per update; for non-streaming, a single event.44+using Consumer = std::function<void(const ClientEvent&, const A2A::AgentCard&)>;
45- * message/send or messag/stream45+ 
46- *46+/** @brief Per-request response handler (alias of Consumer). */
47- * @param[in] msg message to be sent47+using ResponseHandler = std::function<void(const ClientEvent&, const A2A::AgentCard&)>;
48- * @param[in] context client call context48+ 
49- * @param[in] handler response handler49+/**
50- */50+ * @brief High-level A2A client API (message/send, tasks, push notifications).
51- virtual void SendMessage(const Message& msg, const ClientCallContext* context,51+ * @note 对应 A2A JSON-RPC 方法的客户端封装。
52- ResponseHandler handler) = 0;52+ */
53- 53+class Client {
54- /**54+public:
55- * @brief retrieve a task by query params55+ /** @brief Virtual destructor. */
56- * tasks/get56+ virtual ~Client() = default;
57- *57+ 
58- * @param[in] params params of the task to fetch58+ /**
59- * @param[in] context client call context, defaults to nullptr59+ * @brief Send a message and receive responses via handler (message/send or message/stream).
60- * @return future to a Task object containing details of the requested task60+ * @param[in] msg Message to send.
61- */61+ * @param[in] context Per-request client context.
62- virtual std::future<Task> GetTask(const TaskQueryParams& params, const ClientCallContext* context = nullptr) = 0;62+ * @param[in] handler Called per streaming update or once for non-streaming.
63- 63+ * @param[in] timeout Request timeout in seconds (0 = default).
64- /**64+ * @return Future that completes when the request finishes.
65- * @brief cancel a task by task id65+ * @throws A2AClientException via future on transport or protocol errors.
66- * tasks/cancel66+ * @note 流式模式下 handler 会被同步多次调用。
67- *67+ */
68- * @param[in] params task id param68+ virtual std::future<void> SendMessage(const Message& msg, const ClientCallContext* context,
69- * @param[in] context client call context, defaults to nullptr69+ ResponseHandler handler, int timeout = 0) = 0;
70- * @return future to a Task object representing the canceled task state70+ 
71- */71+ /**
72- virtual std::future<Task> CancelTask(const TaskIdParams& params, const ClientCallContext* context = nullptr) = 0;72+ * @brief Retrieve a task by ID (tasks/get).
73- 73+ * @param[in] params Task query parameters.
74- /**74+ * @param[in] context Per-request client context.
75- * @brief set or update the push notification callback configuration for tasks75+ * @param[in] timeout Request timeout in seconds (0 = default).
76- * tasks/pushNotificationConfig/set76+ * @return Future that completes with the Task object.
77- *77+ * @throws A2AClientException via future on error.
78- * @param[in] config configuration object specifying callback details78+ */
79- * @param[in] context client call context, defaults to nullptr79+ virtual std::future<Task> GetTask(const TaskQueryParams& params, const ClientCallContext* context = nullptr,
80- * @return future to TaskPushNotificationConfig80+ int timeout = 0) = 0;
81- */81+ 
82- virtual std::future<TaskPushNotificationConfig> SetTaskPushNotificationConfig(const TaskPushNotificationConfig& cfg,82+ /**
83- const ClientCallContext* context = nullptr) = 0;83+ * @brief Cancel a task by ID (tasks/cancel).
84- 84+ * @param[in] params Task ID parameters.
85- /**85+ * @param[in] context Per-request client context.
86- * @brief retrieve the push notification callback configuration for a specific task86+ * @param[in] timeout Request timeout in seconds (0 = default).
87- * tasks/pushNotificationConfig/get87+ * @return Future that completes with the canceled Task.
88- *88+ * @throws A2AClientException via future on error.
89- * @param[in] params task param89+ */
90- * @param[in] context client call context, defaults to nullptr90+ virtual std::future<Task> CancelTask(const TaskIdParams& params, const ClientCallContext* context = nullptr,
91- * @return future to the push notification callback configuration for a specific task91+ int timeout = 0) = 0;
92- */92+ 
93- virtual std::future<TaskPushNotificationConfig> GetTaskPushNotificationConfig(93+ /**
94- const GetTaskPushNotificationConfigParams& params, const ClientCallContext* context = nullptr) = 0;94+ * @brief Create or update push-notification config (tasks/pushNotificationConfig/set).
95- 95+ * @param[in] cfg Push-notification configuration.
96- /**96+ * @param[in] context Per-request client context.
97- * @brief retrieve the list of push notification callback configuration for a specific task97+ * @param[in] timeout Request timeout in seconds (0 = default).
98- * tasks/pushNotificationConfig/list98+ * @return Future that completes with the saved config.
99- *99+ * @throws A2AClientException via future on error.
100- * @param[in] params task param specifying task information100+ */
101- * @param[in] context client call context, defaults to nullptr101+ virtual std::future<TaskPushNotificationConfig> SetTaskPushNotificationConfig(const TaskPushNotificationConfig& cfg,
102- * @return future to the list of push notification callback configuration for a specific task102+ const ClientCallContext* context = nullptr, int timeout = 0) = 0;
103- */103+ 
104- virtual std::future<std::vector<TaskPushNotificationConfig>> ListTaskPushNotificationConfigs(104+ /**
105- const ListTaskPushNotificationConfigParams& params, const ClientCallContext* context = nullptr) = 0;105+ * @brief Get push-notification config for a task (tasks/pushNotificationConfig/get).
106- 106+ * @param[in] params Query parameters.
107- /**107+ * @param[in] context Per-request client context.
108- * @brief delete the list of push notification callback configuration for a specific task108+ * @param[in] timeout Request timeout in seconds (0 = default).
109- * tasks/pushNotificationConfig/delete109+ * @return Future that completes with the config.
110- *110+ * @throws A2AClientException via future on error.
111- * @param[in] params task param specifying task information111+ */
112- * @param[in] context client call context, defaults to nullptr112+ virtual std::future<TaskPushNotificationConfig> GetTaskPushNotificationConfig(
113- * @return future to void113+ const GetTaskPushNotificationConfigParams& params, const ClientCallContext* context = nullptr,
114- */114+ int timeout = 0) = 0;
115- virtual std::future<void> DeleteTaskPushNotificationConfig(const DeleteTaskPushNotificationConfigParams& params,115+ 
116- const ClientCallContext* context = nullptr) = 0;116+ /**
117- 117+ * @brief List push-notification configs for a task (tasks/pushNotificationConfig/list).
118- /**118+ * @param[in] params Query parameters.
119- * @brief resubscribe to task events for a given task id119+ * @param[in] context Per-request client context.
120- *120+ * @param[in] timeout Request timeout in seconds (0 = default).
121- * @param[in] params task id params121+ * @return Future that completes with the config list.
122- * @param[in] context client call context122+ * @throws A2AClientException via future on error.
123- * @param[in] handler response handler123+ */
124- */124+ virtual std::future<std::vector<TaskPushNotificationConfig>> ListTaskPushNotificationConfigs(
125- virtual void Resubscribe(const TaskIdParams& params, const ClientCallContext* context,125+ const ListTaskPushNotificationConfigParams& params, const ClientCallContext* context = nullptr,
126- ResponseHandler handler) = 0;126+ int timeout = 0) = 0;
127- 127+ 
128- /**128+ /**
129- * @brief retrieve card information of agent129+ * @brief Delete a push-notification config (tasks/pushNotificationConfig/delete).
130- *130+ * @param[in] params Delete parameters.
131- * @param[in] context client call context, defaults to nullptr131+ * @param[in] context Per-request client context.
132- * @return future to AgentCard information132+ * @param[in] timeout Request timeout in seconds (0 = default).
133- */133+ * @return Future that completes when deletion succeeds.
134- virtual std::future<A2A::AgentCard> GetCard(const ClientCallContext* context = nullptr) = 0;134+ * @throws A2AClientException via future on error.
135- 135+ */
136- /**136+ virtual std::future<void> DeleteTaskPushNotificationConfig(const DeleteTaskPushNotificationConfigParams& params,
137- * @brief register a consumer to receive client events137+ const ClientCallContext* context = nullptr, int timeout = 0) = 0;
138- *138+ 
139- * @param[in] c consumer object139+ /**
140- */140+ * @brief Resubscribe to task events for a given task ID.
141- virtual void AddEventConsumer(Consumer c) = 0;141+ * @param[in] params Task ID parameters.
142- 142+ * @param[in] context Per-request client context.
143- /**143+ * @param[in] handler Called for each streaming event.
144- * @brief add request middleware144+ * @param[in] timeout Request timeout in seconds (0 = default).
145- *145+ * @throws A2AClientException on transport or protocol errors.
146- * @param[in] middleware interceptor object146+ */
147- */147+ virtual void Resubscribe(const TaskIdParams& params, const ClientCallContext* context,
148- virtual void AddRequestMiddleware(std::shared_ptr<ClientCallInterceptor> middleware) = 0;148+ ResponseHandler handler, int timeout = 0) = 0;
149- 149+ 
150- /**150+ /**
151- * @brief close client connection and release associated resources151+ * @brief Retrieve the agent card (agent/getCard).
152- *152+ * @param[in] context Per-request client context.
153- * @note after calling this, no further operations should be performed153+ * @param[in] timeout Request timeout in seconds (0 = default).
154- */154+ * @return Future that completes with the AgentCard.
155- virtual void Close() = 0;155+ * @throws A2AClientException via future on error.
156-};156+ */
157- 157+ virtual std::future<A2A::AgentCard> GetCard(const ClientCallContext* context = nullptr, int timeout = 0) = 0;
158-} // namespace A2A::Client158+ 
159- 159+ /**
160-#endif160+ * @brief Register a global event consumer.
161+ * @param[in] c Consumer callback.
162+ */
163+ virtual void AddEventConsumer(Consumer c) = 0;
164+ 
165+ /**
166+ * @brief Add a request interceptor middleware.
167+ * @param[in] middleware Interceptor instance.
168+ */
169+ virtual void AddRequestMiddleware(std::shared_ptr<ClientCallInterceptor> middleware) = 0;
170+ 
171+ /**
172+ * @brief Close the client and release all resources.
173+ * @note 调用后不应再执行任何操作。
174+ */
175+ virtual void Close() = 0;
176+};
177+ 
178+} // namespace A2A::Client
179+ 
180+#endif
@@ -5,7 +5,6 @@
5#ifndef A2A_CLIENT_CALL_INTERCEPTOR5#ifndef A2A_CLIENT_CALL_INTERCEPTOR
6#define A2A_CLIENT_CALL_INTERCEPTOR6#define A2A_CLIENT_CALL_INTERCEPTOR
7 7 
8-#include <nlohmann/json.hpp>
9#include <string>8#include <string>
10#include <map>9#include <map>
11 10 
@@ -13,26 +12,24 @@
13 12 
14namespace A2A::Client {13namespace A2A::Client {
15 14 
16-// Client-side call interceptor interface (sync, header/payload mutation)15+/**
16+ * @brief Client-side request interceptor for header and payload mutation.
17+ * @note 同步拦截器,在请求发出前修改 payload 与 headers。
18+ */
17class ClientCallInterceptor {19class ClientCallInterceptor {
18public:20public:
19- /**21+ /** @brief Virtual destructor. */
20- * @brief destructor
21- *
22- * @param[in] service credential service
23- */
24 virtual ~ClientCallInterceptor() = default;22 virtual ~ClientCallInterceptor() = default;
25 23 
26 /**24 /**
27- * @brief perform intercept with methodName, may mutate payload and headers25+ * @brief Intercept an outbound RPC call; may mutate payload and headers.
28- *26+ * @param[in] methodName JSON-RPC method name.
29- * @param[in] methodName method name to intercept27+ * @param[in,out] payload Serialized request body.
30- * @param[in/out] payload data payload28+ * @param[out] headers HTTP / transport headers to send.
31- * @param[out] headers headers29+ * @param[in] agentCard Agent card for this call; may be nullptr.
32- * @param[in] agentCard agent card related to this intercept. may be null30+ * @param[in] context Per-request client context; may be nullptr.
33- * @param[in] context client call context. may be null
34 */31 */
35- virtual void Intercept(const std::string& methodName, nlohmann::json& payload,32+ virtual void Intercept(const std::string& methodName, std::string& payload,
36 std::map<std::string, std::string>& headers, const A2A::AgentCard* agentCard,33 std::map<std::string, std::string>& headers, const A2A::AgentCard* agentCard,
37 const ClientCallContext* context) = 0;34 const ClientCallContext* context) = 0;
38};35};
@@ -1,43 +1,51 @@
1-/*1+/*
2- * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.2+ * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
3- */3+ */
4- 4+ 
5-#ifndef A2A_CLIENT_FACTORY5+#ifndef A2A_CLIENT_FACTORY
6-#define A2A_CLIENT_FACTORY6+#define A2A_CLIENT_FACTORY
7- 7+ 
8-#include <memory>8+#include <memory>
9-#include <vector>9+#include <vector>
10- 10+ 
11-#include "client/client.h"11+#include "client/client.h"
12-#include "client/client_transport.h"12+#include "client/client_transport.h"
13-#include "types.h"13+#include "types.h"
14- 14+ 
15-namespace A2A::Client {15+namespace A2A::Client {
16- 16+ 
17-class ClientFactory {17+/**
18-public:18+ * @brief Factory for creating configured A2A Client instances.
19- /**19+ */
20- * @brief destructor20+class ClientFactory {
21- */21+public:
22- ~ClientFactory();22+ /** @brief Destructor. */
23- 23+ ~ClientFactory();
24- /**24+ 
25- * @brief create client25+ /**
26- *26+ * @brief Create a client with the default JSON-RPC transport.
27- * @param[in] card agent card27+ * @param[in] card Resolved agent card.
28- * @param[in] config client config28+ * @param[in] config Client behaviour configuration.
29- * @param[in] consumers consumers of client being created29+ * @param[in] consumers Optional event consumers.
30- * @param[in] interceptors interceptors of client being created30+ * @param[in] interceptors Optional request interceptors.
31- * @return unique pointer of client been created31+ * @return Shared pointer to the created client.
32- */32+ */
33- static std::shared_ptr<Client> Create(const AgentCard& card, const ClientConfig& config,33+ static std::shared_ptr<Client> Create(const AgentCard& card, const ClientConfig& config,
34- const std::vector<Consumer>& consumers = {},34+ const std::vector<Consumer>& consumers = {},
35- const std::vector<std::shared_ptr<ClientCallInterceptor>>& interceptors = {});35+ const std::vector<std::shared_ptr<ClientCallInterceptor>>& interceptors = {});
36- 36+ 
37- static std::shared_ptr<Client> Create(const AgentCard& card, const ClientConfig& config,37+ /**
38- std::shared_ptr<ClientTransport> transport, const std::vector<Consumer>& consumers = {});38+ * @brief Create a client with a custom transport implementation.
39-};39+ * @param[in] card Resolved agent card.
40- 40+ * @param[in] config Client behaviour configuration.
41-} // namespace A2A::Client41+ * @param[in] transport Custom transport layer.
42- 42+ * @param[in] consumers Optional event consumers.
43-#endif43+ * @return Shared pointer to the created client.
44+ */
45+ static std::shared_ptr<Client> Create(const AgentCard& card, const ClientConfig& config,
46+ std::shared_ptr<ClientTransport> transport, const std::vector<Consumer>& consumers = {});
47+};
48+ 
49+} // namespace A2A::Client
50+ 
51+#endif
RA2A/cpp-sdk/src/client/client_transport.h→A2A/cpp-sdk/include/client/client_transport.h+89-76
@@ -11,143 +11,156 @@
11 11 
12#include "client/client.h"12#include "client/client.h"
13#include "types.h"13#include "types.h"
14-#include "common_types.h"
15-#include "client_conn.h"
16 14 
17namespace A2A::Client {15namespace A2A::Client {
18 16 
17+/**
18+ * @brief Transport-layer error delivered via TransportEventCallback.
19+ */
19struct TransportError {20struct TransportError {
21+ /** @brief A2AErrorCode or transport-specific code. */
20 int errorCode;22 int errorCode;
23+ /** @brief Human-readable error description. */
21 std::string errInfo;24 std::string errInfo;
22};25};
23 26 
27+/**
28+ * @brief Union of all event types a transport may deliver.
29+ */
24using TransportEvent = std::variant<TransportError, Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent,30using TransportEvent = std::variant<TransportError, Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent,
25 TaskPushNotificationConfig, std::vector<TaskPushNotificationConfig>, std::monostate, AgentCard>;31 TaskPushNotificationConfig, std::vector<TaskPushNotificationConfig>, std::monostate, AgentCard>;
32+ 
33+/**
34+ * @brief Callback invoked when a transport response arrives.
35+ * @param requestId Correlates with the outbound request ID.
36+ * @param event Parsed response event.
37+ */
26using TransportEventCallback = std::function<void(const std::string&, const TransportEvent&)>;38using TransportEventCallback = std::function<void(const std::string&, const TransportEvent&)>;
27 39 
40+/**
41+ * @brief Low-level A2A client transport interface (JSON-RPC over HTTP, etc.).
42+ * @note 异步回调模型;由 Client 层封装为 std::future。
43+ */
28class ClientTransport {44class ClientTransport {
29public:45public:
30- ~ClientTransport() = default;46+ /** @brief Virtual destructor. */
47+ virtual ~ClientTransport() = default;
31 48 
32 /**49 /**
33- * @brief send message to server and get response50+ * @brief Send a non-streaming message/send request.
34- *51+ * @param[in] requestId Correlation ID for the callback.
35- * @param[in] requestId requestId52+ * @param[in] request Message send parameters.
36- * @param[in] request request data info53+ * @param[in] context Per-request client context.
37- * @param[in] context client call context54+ * @param[in] timeout Timeout in seconds.
38 */55 */
39 virtual void SendMessage(const std::string& requestId, const MessageSendParams& request,56 virtual void SendMessage(const std::string& requestId, const MessageSendParams& request,
40- const ClientCallContext* context) = 0;57+ const ClientCallContext* context, int timeout) = 0;
41 58 
42 /**59 /**
43- * @brief send stream message to server and get response with callback60+ * @brief Send a streaming message/stream request.
44- *61+ * @param[in] requestId Correlation ID for the callback.
45- * @param[in] requestId requestId62+ * @param[in] request Message send parameters.
46- * @param[in] request request data info63+ * @param[in] context Per-request client context.
47- * @param[in] context client call context64+ * @param[in] timeout Timeout in seconds.
48 */65 */
49 virtual void SendMessageStreaming(const std::string& requestId, const MessageSendParams& request,66 virtual void SendMessageStreaming(const std::string& requestId, const MessageSendParams& request,
50- const ClientCallContext* context) = 0;67+ const ClientCallContext* context, int timeout) = 0;
51 68 
52 /**69 /**
53- * @brief retrieve task information from server70+ * @brief Send a tasks/get request.
54- *71+ * @param[in] requestId Correlation ID.
55- * @param[in] requestId requestId72+ * @param[in] params Task query parameters.
56- * @param[in] params query params73+ * @param[in] context Per-request client context.
57- * @param[in] context client call context74+ * @param[in] timeout Timeout in seconds.
58 */75 */
59 virtual void GetTask(const std::string& requestId, const TaskQueryParams& params,76 virtual void GetTask(const std::string& requestId, const TaskQueryParams& params,
60- const ClientCallContext* context) = 0;77+ const ClientCallContext* context, int timeout) = 0;
61 78 
62 /**79 /**
63- * @brief call server to cancel task80+ * @brief Send a tasks/cancel request.
64- *81+ * @param[in] requestId Correlation ID.
65- * @param[in] requestId requestId82+ * @param[in] params Task ID parameters.
66- * @param[in] params task id params83+ * @param[in] context Per-request client context.
67- * @param[in] context client call context84+ * @param[in] timeout Timeout in seconds.
68 */85 */
69 virtual void CancelTask(const std::string& requestId, const TaskIdParams& params,86 virtual void CancelTask(const std::string& requestId, const TaskIdParams& params,
70- const ClientCallContext* context) = 0;87+ const ClientCallContext* context, int timeout) = 0;
71 88 
72 /**89 /**
73- * @brief set push notification config for a specific task90+ * @brief Send a push-notification config set request.
74- *91+ * @param[in] requestId Correlation ID.
75- * @param[in] requestId requestId92+ * @param[in] config Push-notification configuration.
76- * @param[in] config push notification config93+ * @param[in] context Per-request client context.
77- * @param[in] context client call context94+ * @param[in] timeout Timeout in seconds.
78 */95 */
79 virtual void SetTaskPushNotificationConfig(const std::string& requestId, const TaskPushNotificationConfig& config,96 virtual void SetTaskPushNotificationConfig(const std::string& requestId, const TaskPushNotificationConfig& config,
80- const ClientCallContext* context) = 0;97+ const ClientCallContext* context, int timeout) = 0;
81 98 
82 /**99 /**
83- * @brief retrieve push notification config for a specific task100+ * @brief Send a push-notification config get request.
84- *101+ * @param[in] requestId Correlation ID.
85- * @param[in] requestId requestId102+ * @param[in] params Query parameters.
86- * @param[in] params task id and metadata information103+ * @param[in] context Per-request client context.
87- * @param[in] context client call context104+ * @param[in] timeout Timeout in seconds.
88 */105 */
89 virtual void GetTaskPushNotificationConfig(const std::string& requestId,106 virtual void GetTaskPushNotificationConfig(const std::string& requestId,
90- const GetTaskPushNotificationConfigParams& params, const ClientCallContext* context) = 0;107+ const GetTaskPushNotificationConfigParams& params, const ClientCallContext* context, int timeout) = 0;
91 108 
92 /**109 /**
93- * @brief retrieve the list of push notification config for a specific task110+ * @brief Send a push-notification config list request.
94- *111+ * @param[in] requestId Correlation ID.
95- * @param[in] requestId requestId112+ * @param[in] params Query parameters.
96- * @param[in] params task id and metadata information113+ * @param[in] context Per-request client context.
97- * @param[in] context client call context114+ * @param[in] timeout Timeout in seconds.
98 */115 */
99 virtual void ListTaskPushNotificationConfigs(const std::string& requestId,116 virtual void ListTaskPushNotificationConfigs(const std::string& requestId,
100- const ListTaskPushNotificationConfigParams& params, const ClientCallContext* context) = 0;117+ const ListTaskPushNotificationConfigParams& params, const ClientCallContext* context, int timeout) = 0;
101 118 
102 /**119 /**
103- * @brief delete the list of push notification config for a specific task120+ * @brief Send a push-notification config delete request.
104- *121+ * @param[in] requestId Correlation ID.
105- * @param[in] requestId requestId122+ * @param[in] params Delete parameters.
106- * @param[in] params task id and metadata information123+ * @param[in] context Per-request client context.
107- * @param[in] context client call context124+ * @param[in] timeout Timeout in seconds.
108 */125 */
109 virtual void DeleteTaskPushNotificationConfig(const std::string& requestId,126 virtual void DeleteTaskPushNotificationConfig(const std::string& requestId,
110- const DeleteTaskPushNotificationConfigParams& params, const ClientCallContext* context) = 0;127+ const DeleteTaskPushNotificationConfigParams& params, const ClientCallContext* context, int timeout) = 0;
111 128 
112 /**129 /**
113- * @brief resubscribe to server130+ * @brief Resubscribe to task streaming events.
114- *131+ * @param[in] requestId Correlation ID.
115- * @param[in] requestId requestId132+ * @param[in] params Task ID parameters.
116- * @param[in] params task id params133+ * @param[in] context Per-request client context.
117- * @param[in] context client call context134+ * @param[in] timeout Timeout in seconds.
118 */135 */
119 virtual void Resubscribe(const std::string& requestId, const TaskIdParams& params,136 virtual void Resubscribe(const std::string& requestId, const TaskIdParams& params,
120- const ClientCallContext* context) = 0;137+ const ClientCallContext* context, int timeout) = 0;
121 138 
122 /**139 /**
123- * @brief retrieve agent card from server140+ * @brief Send an agent/getCard request.
124- *141+ * @param[in] requestId Correlation ID.
125- * @param[in] requestId requestId142+ * @param[in] context Per-request client context.
126- * @param[in] context client call context143+ * @param[in] timeout Timeout in seconds.
127 */144 */
128- virtual void GetCard(const std::string& requestId, const ClientCallContext* context) = 0;145+ virtual void GetCard(const std::string& requestId, const ClientCallContext* context, int timeout) = 0;
129 146 
130 /**147 /**
131- * @brief set transport callback148+ * @brief Register the callback for inbound transport events.
132- *149+ * @param[in] callback Function invoked for each response event.
133- * @param[in] callback callback function triggered when receive response data
134 */150 */
135 virtual void SetTransportCallback(TransportEventCallback callback) = 0;151 virtual void SetTransportCallback(TransportEventCallback callback) = 0;
136 152 
137 /**153 /**
138- * @brief transport callback fuction154+ * @brief Close the transport and release resources.
139- *155+ * @note 调用后不应再执行任何操作。
140- * @param[in] message message payload
141- * @param[in] userData user data
142- */
143- virtual void OnTransportMessage(const ConnEventData& message, const UserData* userData) = 0;
144- 
145- /**
146- * @brief close client connection and release associated resources
147- *
148- * @note after calling this, no further operations should be performed
149 */156 */
150 virtual void Close() = 0;157 virtual void Close() = 0;
158+ 
159+ /**
160+ * @brief Add a request interceptor middleware.
161+ * @param[in] middleware Interceptor instance.
162+ */
163+ virtual void AddRequestMiddleware(const std::shared_ptr<ClientCallInterceptor>& middleware) = 0;
151};164};
152 165 
153} // namespace A2A::Client166} // namespace A2A::Client
@@ -1,38 +1,38 @@
1-/*1+/*
2- * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.2+ * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
3- */3+ */
4- 4+ 
5-#ifndef HTTP_CARD_RESOLVER_BUILDER5+#ifndef HTTP_CARD_RESOLVER_BUILDER
6-#define HTTP_CARD_RESOLVER_BUILDER6+#define HTTP_CARD_RESOLVER_BUILDER
7- 7+ 
8-#include <string>8+#include <string>
9-#include <future>9+#include <future>
10-#include <memory>10+#include <memory>
11- 11+ 
12-#include "client/a2a_card_resolver.h"12+#include "client/a2a_card_resolver.h"
13-#include "types.h"13+#include "types.h"
14- 14+ 
15-namespace A2A::Client {15+namespace A2A::Client {
16- 16+ 
17-class HttpCardResolverBuilder final {17+/**
18-public:18+ * @brief Factory for HTTP-based A2ACardResolver instances.
19- /**19+ */
20- * @brief destructor20+class HttpCardResolverBuilder final {
21- */21+public:
22- ~HttpCardResolverBuilder();22+ /** @brief Destructor. */
23- 23+ ~HttpCardResolverBuilder();
24- /**24+ 
25- * @brief build card resolver25+ /**
26- *26+ * @brief Build an HTTP card resolver.
27- * @param[in] baseUrl base url27+ * @param[in] baseUrl Server base URL (e.g. "http://host:port").
28- * @param[in] agentCardPath agent card path28+ * @param[in] agentCardPath Path to the agent card (default: /.well-known/agent-card.json).
29- * @param[in] httpKwargs http args29+ * @param[in] httpKwargs Extra HTTP headers or options.
30- * @return A shared pointer to the created card resolver instance30+ * @return Shared pointer to the created resolver.
31- */31+ */
32- static std::shared_ptr<A2ACardResolver> Build(std::string baseUrl, std::string agentCardPath,32+ static std::shared_ptr<A2ACardResolver> Build(std::string baseUrl, std::string agentCardPath,
33- const std::map<std::string, std::string>& httpKwargs = {});33+ const std::map<std::string, std::string>& httpKwargs = {});
34-};34+};
35- 35+ 
36-} // namespace A2A::Client36+} // namespace A2A::Client
37- 37+ 
38-#endif38+#endif
@@ -0,0 +1,174 @@
1+/*
2+ * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
3+ */
4+ 
5+#ifndef A2A_JSONRPC_TRANSPORT
6+#define A2A_JSONRPC_TRANSPORT
7+ 
8+#include <memory>
9+#include <vector>
10+ 
11+#include "client/client_call_interceptor.h"
12+#include "client/client_transport.h"
13+#include "types.h"
14+ 
15+namespace A2A {
16+ 
17+/** @brief Opaque HTTP client connection (libcurl). */
18+class ClientConn;
19+ 
20+namespace Client {
21+ 
22+/** @brief PIMPL holder for JsonRpcTransport. */
23+class JsonRpcTransportImpl;
24+ 
25+/**
26+ * @brief JSON-RPC over HTTP implementation of ClientTransport.
27+ * @note 默认客户端传输层,支持 SSE 流式响应。
28+ */
29+class JsonRpcTransport : public ClientTransport {
30+public:
31+ /**
32+ * @brief Construct a JSON-RPC transport.
33+ * @param[in] url JSON-RPC endpoint URL.
34+ * @param[in] agentCard Resolved agent card.
35+ * @param[in] config Client configuration.
36+ * @param[in] interceptors Request interceptors applied to every call.
37+ */
38+ JsonRpcTransport(const std::string& url, const AgentCard& agentCard, const ClientConfig& config,
39+ const std::vector<std::shared_ptr<ClientCallInterceptor>>& interceptors);
40+ 
41+ /** @brief Destructor; closes the underlying connection. */
42+ ~JsonRpcTransport() override;
43+ 
44+ /**
45+ * @brief Send a non-streaming message/send JSON-RPC request.
46+ * @param[in] requestId Correlation ID for the transport callback.
47+ * @param[in] request Message send parameters.
48+ * @param[in] context Per-request client context.
49+ * @param[in] timeout Timeout in seconds.
50+ */
51+ void SendMessage(const std::string& requestId, const MessageSendParams& request,
52+ const ClientCallContext* context, int timeout) override;
53+ 
54+ /**
55+ * @brief Send a streaming message/stream JSON-RPC request.
56+ * @param[in] requestId Correlation ID for the transport callback.
57+ * @param[in] request Message send parameters.
58+ * @param[in] context Per-request client context.
59+ * @param[in] timeout Timeout in seconds.
60+ */
61+ void SendMessageStreaming(const std::string& requestId, const MessageSendParams& request,
62+ const ClientCallContext* context, int timeout) override;
63+ 
64+ /**
65+ * @brief Send a tasks/get JSON-RPC request.
66+ * @param[in] requestId Correlation ID for the transport callback.
67+ * @param[in] params Task query parameters.
68+ * @param[in] context Per-request client context.
69+ * @param[in] timeout Timeout in seconds.
70+ */
71+ void GetTask(const std::string& requestId, const TaskQueryParams& params,
72+ const ClientCallContext* context, int timeout) override;
73+ 
74+ /**
75+ * @brief Send a tasks/cancel JSON-RPC request.
76+ * @param[in] requestId Correlation ID for the transport callback.
77+ * @param[in] params Task ID parameters.
78+ * @param[in] context Per-request client context.
79+ * @param[in] timeout Timeout in seconds.
80+ */
81+ void CancelTask(const std::string& requestId, const TaskIdParams& params,
82+ const ClientCallContext* context, int timeout) override;
83+ 
84+ /**
85+ * @brief Send a push-notification config set JSON-RPC request.
86+ * @param[in] requestId Correlation ID for the transport callback.
87+ * @param[in] config Push-notification configuration.
88+ * @param[in] context Per-request client context.
89+ * @param[in] timeout Timeout in seconds.
90+ */
91+ void SetTaskPushNotificationConfig(const std::string& requestId, const TaskPushNotificationConfig& config,
92+ const ClientCallContext* context, int timeout) override;
93+ 
94+ /**
95+ * @brief Send a push-notification config get JSON-RPC request.
96+ * @param[in] requestId Correlation ID for the transport callback.
97+ * @param[in] params Query parameters.
98+ * @param[in] context Per-request client context.
99+ * @param[in] timeout Timeout in seconds.
100+ */
101+ void GetTaskPushNotificationConfig(const std::string& requestId,
102+ const GetTaskPushNotificationConfigParams& params, const ClientCallContext* context, int timeout) override;
103+ 
104+ /**
105+ * @brief Send a push-notification config list JSON-RPC request.
106+ * @param[in] requestId Correlation ID for the transport callback.
107+ * @param[in] params Query parameters.
108+ * @param[in] context Per-request client context.
109+ * @param[in] timeout Timeout in seconds.
110+ */
111+ void ListTaskPushNotificationConfigs(const std::string& requestId,
112+ const ListTaskPushNotificationConfigParams& params, const ClientCallContext* context, int timeout) override;
113+ 
114+ /**
115+ * @brief Send a push-notification config delete JSON-RPC request.
116+ * @param[in] requestId Correlation ID for the transport callback.
117+ * @param[in] params Delete parameters.
118+ * @param[in] context Per-request client context.
119+ * @param[in] timeout Timeout in seconds.
120+ */
121+ void DeleteTaskPushNotificationConfig(const std::string& requestId,
122+ const DeleteTaskPushNotificationConfigParams& params, const ClientCallContext* context, int timeout) override;
123+ 
124+ /**
125+ * @brief Resubscribe to task streaming events via JSON-RPC.
126+ * @param[in] requestId Correlation ID for the transport callback.
127+ * @param[in] params Task ID parameters.
128+ * @param[in] context Per-request client context.
129+ * @param[in] timeout Timeout in seconds.
130+ */
131+ void Resubscribe(const std::string& requestId, const TaskIdParams& params,
132+ const ClientCallContext* context, int timeout) override;
133+ 
134+ /**
135+ * @brief Send an agent/getCard JSON-RPC request.
136+ * @param[in] requestId Correlation ID for the transport callback.
137+ * @param[in] context Per-request client context.
138+ * @param[in] timeout Timeout in seconds.
139+ */
140+ void GetCard(const std::string& requestId, const ClientCallContext* context, int timeout) override;
141+ 
142+ /**
143+ * @brief Register the callback for inbound transport events.
144+ * @param[in] callback Function invoked for each parsed JSON-RPC response event.
145+ */
146+ void SetTransportCallback(TransportEventCallback callback) override;
147+ 
148+ /**
149+ * @brief Close the transport and release the underlying HTTP connection.
150+ * @note 调用后不应再执行任何操作。
151+ */
152+ void Close() override;
153+ 
154+ /**
155+ * @brief Add a request interceptor middleware.
156+ * @param[in] middleware Interceptor applied to every outbound JSON-RPC call.
157+ */
158+ void AddRequestMiddleware(const std::shared_ptr<ClientCallInterceptor>& middleware) override;
159+ 
160+protected:
161+ /**
162+ * @brief Get the underlying HTTP connection (for testing / extension).
163+ * @return Shared pointer to the active ClientConn.
164+ */
165+ std::shared_ptr<ClientConn> GetConn();
166+ 
167+private:
168+ std::unique_ptr<JsonRpcTransportImpl> impl_;
169+};
170+ 
171+} // namespace Client
172+} // namespace A2A
173+ 
174+#endif
@@ -5,60 +5,131 @@
5#ifndef A2A_ERROR5#ifndef A2A_ERROR
6#define A2A_ERROR6#define A2A_ERROR
7 7 
8-#include <nlohmann/json.hpp>8+#include <exception>
9#include <stdexcept>9#include <stdexcept>
10#include <string>10#include <string>
11 11 
12+#include "types.h"
13+ 
12namespace A2A {14namespace A2A {
13-// Generic unsupported operation15+ 
14-struct UnsupportedOperationError : public std::runtime_error {16+/**
15- using std::runtime_error::runtime_error;17+ * @brief Base exception for A2A client-side errors.
18+ * @note errorCode 使用 A2AErrorCode 或 HTTP 状态码(传输层错误)。
19+ */
20+struct A2AClientException : public std::runtime_error {
21+ /** @brief Wire / SDK error code (A2AErrorCode or HTTP status). */
22+ int errorCode;
23+ /** @brief Human-readable error message. */
24+ std::string message;
25+ 
26+ /**
27+ * @brief Construct a client exception.
28+ * @param[in] code Error code.
29+ * @param[in] msg Error message.
30+ */
31+ A2AClientException(int code, std::string msg);
32+ 
33+ /**
34+ * @brief Create an exception_ptr wrapping A2AClientException.
35+ * @param[in] code Error code.
36+ * @param[in] message Error message.
37+ * @return std::exception_ptr suitable for std::future::set_exception.
38+ */
39+ static std::exception_ptr Make(int code, const std::string& message);
40+ 
41+ /**
42+ * @brief Parse an A2AError from a caught exception.
43+ * @param[in] e Exception to inspect.
44+ * @param[out] out Populated A2AError on success.
45+ * @return true if @p e is an A2AClientException.
46+ */
47+ static bool TryParse(const std::exception& e, A2AError& out);
16};48};
17 49 
18-// Base exception for server-side errors (parity with Python A2AServerError)50+/**
51+ * @brief Base exception for A2A server-side errors.
52+ * @note statusCode 映射到 JSON-RPC / A2A wire error code (A2AErrorCode)。
53+ */
19struct A2AServerError : public std::runtime_error {54struct A2AServerError : public std::runtime_error {
20- using std::runtime_error::runtime_error;55+ /** @brief JSON-RPC / A2A error code returned to the client. */
21-};
22- 
23-// Method not implemented on server handler (parity with Python MethodNotImplementedError)
24-struct MethodNotImplementedError : public A2AServerError {
25- explicit MethodNotImplementedError(const std::string& message = "This method is not implemented by the server")
26- : A2AServerError("Not Implemented operation Error: " + message)
27- {
28- }
29-};
30- 
31-// HTTP error with status code
32-struct A2AClientHTTPError : public std::runtime_error {
33 int statusCode;56 int statusCode;
34- explicit A2AClientHTTPError(int code, const std::string& message)57+ 
35- : std::runtime_error("HTTP Error " + std::to_string(code) + ": " + message), statusCode(code)58+ /**
59+ * @brief Construct with internal-error code (-32603).
60+ * @param[in] message Error description.
61+ */
62+ explicit A2AServerError(const std::string& message)
63+ : std::runtime_error(message),
64+ statusCode(static_cast<int>(A2AErrorCode::JSONRPC_INTERNAL_ERROR))
65+ {
66+ }
67+ 
68+ /**
69+ * @brief Construct with an explicit error code.
70+ * @param[in] message Error description.
71+ * @param[in] code A2AErrorCode value.
72+ */
73+ explicit A2AServerError(const std::string& message, int code)
74+ : std::runtime_error(message), statusCode(code)
36 {75 {
37 }76 }
38};77};
39 78 
40-// JSON parse/validation error79+/**
41-struct A2AClientJSONError : public std::runtime_error {80+ * @brief Thrown when the server does not implement the requested JSON-RPC method.
42- explicit A2AClientJSONError(const std::string& message) : std::runtime_error("JSON Error: " + message)81+ * @note 对应 JSON-RPC -32601 Method not found。
82+ */
83+struct MethodNotImplementedError : public A2AServerError {
84+ /**
85+ * @brief Construct a method-not-implemented error.
86+ * @param[in] message Optional detail appended to the error text.
87+ */
88+ explicit MethodNotImplementedError(const std::string& message = "This method is not implemented by the server")
89+ : A2AServerError("Not Implemented operation Error: " + message,
90+ static_cast<int>(A2AErrorCode::JSONRPC_METHOD_NOT_FOUND))
43 {91 {
44 }92 }
45};93};
46 94 
47-// Timeout error95+/**
48-struct A2AClientTimeoutError : public std::runtime_error {96+ * @brief Client exception for non-2xx HTTP responses.
49- explicit A2AClientTimeoutError(const std::string& message) : std::runtime_error("Timeout Error: " + message)97+ */
50- {98+struct A2AClientHTTPError : public A2AClientException {
51- }99+ /** @brief HTTP status code from the transport layer. */
100+ int statusCode;
101+ 
102+ /**
103+ * @brief Construct an HTTP transport error.
104+ * @param[in] httpStatusCode HTTP status code.
105+ * @param[in] message Error description.
106+ */
107+ explicit A2AClientHTTPError(int httpStatusCode, const std::string& message);
52};108};
53 109 
54-// JSON-RPC Error wrapper110+/**
55-struct A2AClientJSONRPCError : public std::runtime_error {111+ * @brief Client exception for JSON-RPC or A2A protocol errors in a response body.
56- nlohmann::json error;112+ */
57- explicit A2AClientJSONRPCError(const nlohmann::json& err)113+struct A2AClientJSONError : public A2AClientException {
58- : std::runtime_error("JSON-RPC Error: " + err.dump()), error(err)114+ /**
59- {115+ * @brief Construct a JSON / protocol error.
60- }116+ * @param[in] code A2AErrorCode value from the response.
117+ * @param[in] message Error description.
118+ */
119+ explicit A2AClientJSONError(int code, const std::string& message);
61};120};
121+ 
122+/**
123+ * @brief Client exception for request timeouts.
124+ */
125+struct A2AClientTimeoutError : public A2AClientException {
126+ /**
127+ * @brief Construct a timeout error.
128+ * @param[in] message Error description.
129+ */
130+ explicit A2AClientTimeoutError(const std::string& message);
131+};
132+ 
62} // namespace A2A133} // namespace A2A
63 134 
64-#endif135+#endif
@@ -12,30 +12,45 @@
12 12 
13namespace A2A::Server {13namespace A2A::Server {
14 14 
15+/**
16+ * @brief User-implemented agent logic for task execution and cancellation.
17+ * @note 实现此接口以处理 message/send 与 tasks/cancel 请求。
18+ */
15class AgentExecutor {19class AgentExecutor {
16public:20public:
17- /**21+ /** @brief Virtual destructor. */
18- * @brief destructor
19- */
20 virtual ~AgentExecutor() = default;22 virtual ~AgentExecutor() = default;
21 23 
22 /**24 /**
23- * @brief execute a task in given request context25+ * @brief Execute a task in the given request context.
24- *26+ * @param[in] context Request context with message and task info.
25- * @param[in] context request context containing task information27+ * @param[in] taskUpdater Updater for publishing status / artifact events.
26- * @param[in] taskUpdater updater used to update events28+ * @throws A2AServerError on unrecoverable execution errors.
27 */29 */
28- virtual void Execute(const RequestContext& context, std::shared_ptr<TaskUpdater> taskUpdater) = 0;30+ virtual void Execute(std::shared_ptr<RequestContext> context, std::shared_ptr<TaskUpdater> taskUpdater) = 0;
29 31 
30 /**32 /**
31- * @brief cancel a task in given request context33+ * @brief Execute a task for a custom JSON-RPC method (non SendMessage variants).
32- *34+ * @param[in] context Request context.
33- * @param[in] context request context cintaining task information35+ * @param[in] taskUpdater Updater for publishing events.
34- * @param[in] taskUpdater updater used to update events36+ * @param[in] method Custom JSON-RPC method name.
37+ * @note Default implementation delegates to Execute(context, taskUpdater).
35 */38 */
36- virtual void Cancel(const RequestContext& context, std::shared_ptr<TaskUpdater> taskUpdater) = 0;39+ virtual void Execute(std::shared_ptr<RequestContext> context, std::shared_ptr<TaskUpdater> taskUpdater,
40+ [[maybe_unused]] const std::string& method)
41+ {
42+ Execute(std::move(context), std::move(taskUpdater));
43+ }
44+ 
45+ /**
46+ * @brief Cancel a running task.
47+ * @param[in] context Request context containing task information.
48+ * @param[in] taskUpdater Updater for publishing cancellation status.
49+ * @throws A2AServerError if the task cannot be canceled.
50+ */
51+ virtual void Cancel(std::shared_ptr<RequestContext> context, std::shared_ptr<TaskUpdater> taskUpdater) = 0;
37};52};
38 53 
39} // namespace A2A::Server54} // namespace A2A::Server
40 55 
41-#endif56+#endif
@@ -14,35 +14,43 @@
14 14 
15namespace A2A::Server {15namespace A2A::Server {
16 16 
17+/**
18+ * @brief HTTP server binding and threading configuration.
19+ */
17struct HttpConfig {20struct HttpConfig {
21+ /** @brief Listen IP address. */
18 std::string ip;22 std::string ip;
23+ /** @brief Listen port. */
19 int port;24 int port;
25+ /** @brief Number of I/O event-loop threads. */
20 unsigned int ioThreadNum = 1;26 unsigned int ioThreadNum = 1;
27+ /** @brief JSON-RPC endpoint path. */
21 std::string endpoint = "/jsonrpc";28 std::string endpoint = "/jsonrpc";
22};29};
23 30 
31+/**
32+ * @brief Factory for creating HTTP-based A2A Server instances.
33+ */
24class HttpServerBuilder {34class HttpServerBuilder {
25public:35public:
26- /**36+ /** @brief Destructor. */
27- * @brief destructor
28- */
29 ~HttpServerBuilder();37 ~HttpServerBuilder();
30 38 
31 /**39 /**
32- * @brief create http server40+ * @brief Build and return a configured HTTP server.
33- *41+ * @param[in] config HTTP listen configuration.
34- * @param[in] config http config42+ * @param[in] agentCard Public agent card.
35- * @param[in] agentCard agent card object43+ * @param[in] extendedAgentCard Authenticated extended card (may be empty).
36- * @param[in] extendedAgentCard extended agent card object44+ * @param[in] agentExecutor User agent logic implementation.
37- * @param[in] agentExecutor agent executor object45+ * @param[in] taskStore Task persistence backend (nullptr = in-memory).
38- * @param[in] taskStore store object to store task object46+ * @return Shared pointer to the started-ready Server instance.
39- * @return A shared pointer to the created server instance47+ * @throws std::runtime_error on invalid configuration.
40- */48+ */
41 static std::shared_ptr<Server> Build(const HttpConfig& config, const AgentCard& agentCard,49 static std::shared_ptr<Server> Build(const HttpConfig& config, const AgentCard& agentCard,
42 const AgentCard& extendedAgentCard, std::shared_ptr<AgentExecutor> agentExecutor,50 const AgentCard& extendedAgentCard, std::shared_ptr<AgentExecutor> agentExecutor,
43 std::shared_ptr<TaskStore> taskStore = nullptr);51 std::shared_ptr<TaskStore> taskStore = nullptr);
44};52};
45 53 
46-}54+} // namespace A2A::Server
47 55 
48-#endif56+#endif
@@ -1,43 +0,0 @@
1-/*
2- * Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
3- */
4- 
5-#ifndef A2A_IPC_SERVER_BUILDER
6-#define A2A_IPC_SERVER_BUILDER
7- 
8-#include <memory>
9- 
10-#include "server.h"
11- 
12-namespace A2A::Server {
13- 
14-struct IpcConfig {
15- std::string elementName;
16- std::string rpcCode;
17- std::string cardCode;
18- std::string extCardCode;
19-};
20- 
21-class IpcServerBuilder {
22-public:
23- /**
24- * @brief destructor
25- */
26- ~IpcServerBuilder();
27- 
28- /**
29- * @brief create ipc server
30- *
31- * @param[in] config ipc config
32- * @param[in] agentCard agent card object
33- * @param[in] extendedAgentCard extended agent card object
34- * @param[in] taskStore store object to store task object
35- * @return A shared pointer to the created server instance
36- */
37- static std::shared_ptr<Server> Build(const IpcConfig& config, std::shared_ptr<AgentCard> agentCard,
38- std::shared_ptr<AgentCard> extendedAgentCard = nullptr, std::shared_ptr<TaskStore> taskStore = nullptr);
39-};
40- 
41-}
42- 
43-#endif
@@ -16,115 +16,94 @@
16 16 
17namespace A2A::Server {17namespace A2A::Server {
18 18 
19+/** @brief Opaque implementation of RequestContext (PIMPL). */
19class RequestContextImpl;20class RequestContextImpl;
20 21 
21-struct RequestContextParam {22+/**
22- std::optional<A2A::MessageSendParams> request = std::nullopt;23+ * @brief Per-request context passed to AgentExecutor.
23- std::optional<std::string> taskId = std::nullopt;24+ * @note 封装 message/send 请求的 message、task、扩展等信息。
24- std::optional<std::string> contextId = std::nullopt;25+ */
25- std::optional<A2A::Task> task = std::nullopt;
26- std::vector<A2A::Task> relatedTasks;
27- std::shared_ptr<A2A::Server::ServerCallContext> callContext;
28-};
29- 
30class RequestContext {26class RequestContext {
31public:27public:
32 /**28 /**
33- * @brief constructor29+ * @brief Construct from request parameters.
34- *30+ * @param[in] param Construction parameters.
35- * @param[in] param params used to construct RequestContext
36 */31 */
37- RequestContext(const RequestContextParam& param);32+ explicit RequestContext(const RequestContextParam& param);
33+ 
34+ /** @brief Destructor. */
35+ ~RequestContext();
38 36 
39 /**37 /**
40- * @brief extracts text content from the users's message parts38+ * @brief Extract text content from the user message parts.
41- *39+ * @param[in] delimiter String used when joining multiple text parts.
42- * @param[in] delimiter the string to use when joining multiple text parts40+ * @return Concatenated text from all user message parts.
43- * @return a single string containing akk text content from the user message
44 */41 */
45 std::string GetUserInput(const std::string& delimiter = "\n") const;42 std::string GetUserInput(const std::string& delimiter = "\n") const;
46 43 
47 /**44 /**
48- * @brief attach a related task to the context45+ * @brief Attach a related task to this context.
49- *46+ * @param[in] task Task to attach.
50- * @param[in] task the 'Task' object to attach
51 */47 */
52 void AttachRelatedTask(const A2A::Task& task);48 void AttachRelatedTask(const A2A::Task& task);
53 49 
54 /**50 /**
55- * @brief get the 'Message' object from the request, if available51+ * @brief Get the inbound Message from the request, if present.
56- *52+ * @return Pointer to the message, or nullptr.
57- * @return the 'Message' object from the request, if available
58 */53 */
59 const A2A::Message* GetMessage() const;54 const A2A::Message* GetMessage() const;
60 55 
61 /**56 /**
62- * @brief get a list of other tasks related to the current request57+ * @brief Get tasks related to the current request.
63- *58+ * @return Reference to the related-task list.
64- * @return a list of other tasks related to the current request
65 */59 */
66 const std::vector<A2A::Task>& GetRelatedTasks() const;60 const std::vector<A2A::Task>& GetRelatedTasks() const;
67 61 
68 /**62 /**
69- * @brief get the current 'Task' being processed63+ * @brief Get the task currently being processed.
70- *64+ * @return Shared pointer to the current task, or nullptr.
71- * @return the current 'Task' being processed
72 */65 */
73- const std::optional<A2A::Task>& GetCurrentTask() const;66+ std::shared_ptr<Task> GetCurrentTask() const;
74 67 
75 /**68 /**
76- * @brief set the current 'Task'69+ * @brief Get the task ID associated with this request.
77- *70+ * @return Task ID, or nullopt.
78- * @param[in] t the current 'Task' object
79- */
80- void SetCurrentTask(const A2A::Task& t);
81- 
82- /**
83- * @brief get the ID of the task associated with this task
84- *
85- * @return the ID of the task associated with this task
86 */71 */
87 const std::optional<std::string>& GetTaskId() const;72 const std::optional<std::string>& GetTaskId() const;
88 73 
89 /**74 /**
90- * @brief get the ID of the context associated with this task75+ * @brief Get the conversation context ID.
91- *76+ * @return Context ID, or nullopt.
92- * @return the ID of the context associated with this task
93 */77 */
94 const std::optional<std::string>& GetContextId() const;78 const std::optional<std::string>& GetContextId() const;
95 79 
96 /**80 /**
97- * @brief get the 'MessageSendConfiguration' from the request, if available81+ * @brief Get the MessageSendConfiguration from the request.
98- *82+ * @return Configuration, or nullptr.
99- * @return the 'MessageSendConfiguration' from the request
100 */83 */
101 std::shared_ptr<MessageSendConfiguration> GetConfiguration() const;84 std::shared_ptr<MessageSendConfiguration> GetConfiguration() const;
102 85 
103 /**86 /**
104- * @brief get server call context from the request, if available87+ * @brief Get the server call context for this request.
105- *88+ * @return Server call context, or nullptr.
106- * @return server call context from the request
107 */89 */
108 std::shared_ptr<ServerCallContext> GetCallContext() const;90 std::shared_ptr<ServerCallContext> GetCallContext() const;
109 91 
110 /**92 /**
111- * @brief get metadate associated whit the request, if available93+ * @brief Get request-level metadata JSON.
112- *94+ * @return Metadata string (may be empty).
113- * @return metadate associated whit the request
114 */95 */
115- nlohmann::json GetMetadata() const;96+ std::string GetMetadata() const;
116 97 
117 /**98 /**
118- * @brief add an extension to the set of activated extensions for this request99+ * @brief Record an activated protocol extension URI.
119- *100+ * @param[in] uri Extension URI.
120- * @param[in] uri uri of extension
121 */101 */
122 void AddActivatedExtension(const std::string& uri);102 void AddActivatedExtension(const std::string& uri);
123 103 
124 /**104 /**
125- * @brief get the extensions that the client requested to activate105+ * @brief Get extensions requested by the client.
126- *106+ * @return Set of requested extension URIs.
127- * @return a list of the extensions that the client requested to activate
128 */107 */
129 std::unordered_set<std::string> GetRequestedExtensions() const;108 std::unordered_set<std::string> GetRequestedExtensions() const;
130 109 
@@ -7,24 +7,28 @@
7 7 
8namespace A2A::Server {8namespace A2A::Server {
9 9 
10+/**
11+ * @brief Top-level A2A server interface.
12+ * @note 服务端生命周期:Start() → Stop()。
13+ */
10class Server {14class Server {
11public:15public:
12- /**16+ /** @brief Virtual destructor. */
13- * @brief destructor
14- */
15 virtual ~Server() = default;17 virtual ~Server() = default;
16 18 
17 /**19 /**
18- * @brief start server and listen20+ * @brief Start the server and begin listening for requests.
21+ * @return 0 on success, non-zero on failure.
22+ * @throws std::runtime_error if the transport fails to bind or start.
19 */23 */
20 virtual int Start() = 0;24 virtual int Start() = 0;
21 25 
22 /**26 /**
23- * @brief stop server27+ * @brief Stop the server and release listening resources.
24 */28 */
25 virtual void Stop() = 0;29 virtual void Stop() = 0;
26};30};
27 31 
28} // namespace A2A::Server32} // namespace A2A::Server
29 33 
30-#endif34+#endif
@@ -6,22 +6,48 @@
6#define A2A_SERVER_CALL_CONTEXT6#define A2A_SERVER_CALL_CONTEXT
7 7 
8#include <memory>8#include <memory>
9-#include <nlohmann/json.hpp>
10#include <string>9#include <string>
11#include <unordered_map>10#include <unordered_map>
12#include <unordered_set>11#include <unordered_set>
13 12 
13+#include "types.h"
14+ 
14namespace A2A::Server {15namespace A2A::Server {
15 16 
16-// Server-side call context analogous to Python's ServerCallContext17+/** @brief Forward declaration; see task_store.h. */
18+struct TaskStore;
19+ 
20+/**
21+ * @brief Per-request server-side call context (headers, auth, extensions).
22+ * @note 服务端单次请求的上下文,类比 Python ServerCallContext。
23+ */
17struct ServerCallContext {24struct ServerCallContext {
18- // Arbitrary per-request state (e.g., headers, auth info)25+ /** @brief Arbitrary per-request key-value state (e.g. headers, auth info). */
19- std::unordered_map<std::string, nlohmann::json> state;26+ std::unordered_map<std::string, std::string> state;
20- // Requested and activated protocol extensions27+ /** @brief Protocol extensions requested by the client. */
21 std::unordered_set<std::string> requestedExtensions;28 std::unordered_set<std::string> requestedExtensions;
29+ /** @brief Protocol extensions activated for this request. */
22 std::unordered_set<std::string> activatedExtensions;30 std::unordered_set<std::string> activatedExtensions;
23};31};
24 32 
33+/**
34+ * @brief Parameters used to construct a RequestContext.
35+ */
36+struct RequestContextParam {
37+ /** @brief Incoming message/send parameters, if any. */
38+ std::optional<A2A::MessageSendParams> request = std::nullopt;
39+ /** @brief Task ID associated with the request. */
40+ std::optional<std::string> taskId = std::nullopt;
41+ /** @brief Conversation context ID. */
42+ std::optional<std::string> contextId = std::nullopt;
43+ /** @brief Task persistence backend. */
44+ std::shared_ptr<TaskStore> taskStore = nullptr;
45+ /** @brief Tasks related to the current request. */
46+ std::vector<A2A::Task> relatedTasks;
47+ /** @brief Server call context for this request. */
48+ std::shared_ptr<ServerCallContext> callContext;
49+};
50+ 
25} // namespace A2A::Server51} // namespace A2A::Server
26 52 
27#endif53#endif
@@ -5,7 +5,6 @@
5#ifndef A2A_TASK_STORE5#ifndef A2A_TASK_STORE
6#define A2A_TASK_STORE6#define A2A_TASK_STORE
7 7 
8-#include <optional>
9#include <string>8#include <string>
10#include <memory>9#include <memory>
11 10 
@@ -14,33 +13,33 @@
14 13 
15namespace A2A::Server {14namespace A2A::Server {
16 15 
16+/**
17+ * @brief Persistence interface for A2A tasks.
18+ * @note 任务存储抽象;默认实现为内存存储。
19+ */
17struct TaskStore {20struct TaskStore {
18- /**21+ /** @brief Virtual destructor. */
19- * @brief constructor
20- */
21 virtual ~TaskStore() = default;22 virtual ~TaskStore() = default;
22 23 
23 /**24 /**
24- * @brief saves or updates a task in the store25+ * @brief Save or update a task.
25- *26+ * @param[in] task Task to persist.
26- * @param[in] task transport type27+ * @param[in] context Server call context.
27- * @param[in] context server call context
28 */28 */
29 virtual void Save(const A2A::Task& task, std::shared_ptr<ServerCallContext> context) = 0;29 virtual void Save(const A2A::Task& task, std::shared_ptr<ServerCallContext> context) = 0;
30 30 
31 /**31 /**
32- * @brief retrieves a task from the store by ID32+ * @brief Retrieve a task by ID.
33- *33+ * @param[in] taskId Task identifier.
34- * @param[in] taskId task id34+ * @param[in] context Server call context.
35- * @param[in] context server call context35+ * @return Shared pointer to the task, or nullptr if not found.
36 */36 */
37- virtual std::optional<A2A::Task> Get(const std::string& taskId, std::shared_ptr<ServerCallContext> context) = 0;37+ virtual std::shared_ptr<Task> Get(const std::string& taskId, std::shared_ptr<ServerCallContext> context) = 0;
38 38 
39 /**39 /**
40- * @brief delete a task from the store by ID40+ * @brief Delete a task by ID.
41- *41+ * @param[in] taskId Task identifier.
42- * @param[in] taskId task id42+ * @param[in] context Server call context.
43- * @param[in] context server call context
44 */43 */
45 virtual void Delete(const std::string& taskId, std::shared_ptr<ServerCallContext> context) = 0;44 virtual void Delete(const std::string& taskId, std::shared_ptr<ServerCallContext> context) = 0;
46};45};
RA2A/cpp-sdk/src/client/jsonrpc_transport.h→A2A/cpp-sdk/src/client/jsonrpc_transport_impl.h+56-46
RA2A/cpp-sdk/include/client/protocol_version_interceptor.h→A2A/cpp-sdk/src/client/protocol_version_interceptor.h+14-14
MREADME.md+15-12