Merged
merge develop into main #264
wangyuejoannaAdd on Jul 21
merge develop into main #264
Merged
Merged fromgcw_XiLNLWHF/agent-protocolmainintoopenJiuwen/agent-protocolmain
Total: 463 files changed+71125-5974
| @@ -1,120 +1,85 @@ | |||
| 1 | cmake_minimum_required(VERSION 3.15) | 1 | cmake_minimum_required(VERSION 3.15) |
| 2 | - | 2 | +project(a2a_cpp LANGUAGES CXX C) |
| 3 | -project(a2a LANGUAGES CXX C) | ||
| 4 | 3 | ||
| 5 | set(CMAKE_CXX_STANDARD 17) | 4 | set(CMAKE_CXX_STANDARD 17) |
| 6 | set(CMAKE_CXX_STANDARD_REQUIRED ON) | 5 | set(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) | ||
| 8 | option(A2A_ENABLE_TESTS "Build unit tests" OFF) | 11 | option(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 | ||
| 14 | find_package(OpenSSL REQUIRED) | 33 | find_package(OpenSSL REQUIRED) |
| 15 | find_package(CURL REQUIRED) | 34 | find_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 "") | ||
| 66 | if(TARGET event) | 38 | if(TARGET event) |
| 67 | - set(_a2a_libevent_target event) | 39 | + list(APPEND _a2a_link_libs event) |
| 68 | elseif(TARGET libevent) | 40 | elseif(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) | ||
| 77 | endif() | 42 | endif() |
| 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. | ||
| 82 | if(TARGET event_pthreads) | 44 | if(TARGET event_pthreads) |
| 83 | - target_link_libraries(a2a PUBLIC event_pthreads) | 45 | + list(APPEND _a2a_link_libs event_pthreads) |
| 84 | elseif(TARGET libevent_pthreads) | 46 | elseif(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) | ||
| 88 | else() | 48 | else() |
| 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() |
| 95 | endif() | 53 | endif() |
| 96 | 54 | ||
| 97 | -set_target_properties(a2a PROPERTIES | 55 | +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) | ||
| 107 | endif() | 57 | endif() |
| 108 | 58 | ||
| 109 | if(TARGET CURL::libcurl) | 59 | if(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() | ||
| 111 | endif() | 80 | endif() |
| 112 | 81 | ||
| 113 | if(A2A_ENABLE_TESTS) | 82 | if(A2A_ENABLE_TESTS) |
| 114 | enable_testing() | 83 | enable_testing() |
| 115 | add_subdirectory(tests) | 84 | add_subdirectory(tests) |
| 116 | endif() | 85 | endif() |
| 117 | - | ||
| 118 | -if(A2A_ENABLE_EXAMPLES) | ||
| 119 | - add_subdirectory(examples) | ||
| 120 | -endif() | ||
| @@ -1,188 +1,225 @@ | |||
| 1 | -# a2a_cpp | 1 | +# 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 | ```bash | 44 | ```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 | ||
| 115 | bash scripts/run_example.sh | 52 | bash 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 | - | ||
| 2 | include_directories(${CMAKE_SOURCE_DIR}/include) | 1 | include_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 logging | 19 | +namespace A2A::Log { |
| 20 | + | ||
| 21 | +/** @brief Nanoseconds per millisecond, used for timestamp formatting. */ | ||
| 19 | constexpr int32_t A2A_NANOS_PER_MILLISECOND = 1000000; | 22 | constexpr int32_t A2A_NANOS_PER_MILLISECOND = 1000000; |
| 23 | + | ||
| 24 | +/** @brief Width of the millisecond field in log timestamps. */ | ||
| 20 | constexpr int32_t A2A_TIMESTAMP_MILLIS_WIDTH = 3; | 25 | constexpr 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 = 7 | 32 | + 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 | + */ | ||
| 33 | void A2aPrintfImpl(A2A_LOG_LEVEL logLevel, std::string message); | 54 | void 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 | + */ | ||
| 37 | A2A_LOG_LEVEL GetLogLevel(void); | 74 | A2A_LOG_LEVEL GetLogLevel(void); |
| 38 | 75 | ||
| 39 | -// Helper function to get current timestamp | 76 | +/** |
| 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 | + */ | ||
| 40 | static inline void GetCurrentTimeStamp(std::string& timestamp) | 87 | static 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 | ||
| 63 | template<typename... Args> | 106 | template<typename... Args> |
| 64 | inline void LogInternal(A2A_LOG_LEVEL level, const char* file, const char* func, int line, | 107 | inline 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::Log | 131 | } // 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 | -#endif | 143 | +#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_RESOLVER | 5 | +#ifndef A2A_CARD_RESOLVER |
| 6 | -#define A2A_CARD_RESOLVER | 6 | +#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 destructor | 19 | + */ |
| 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 path | 24 | + |
| 25 | - * | 25 | + /** |
| 26 | - * @param[in] relativeCardPath relative card path | 26 | + * @brief Fetch an agent card from a relative path. |
| 27 | - * @return future to valid AgentCard if read successful | 27 | + * @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 path | 33 | + const std::optional<std::string>& relativeCardPath = std::nullopt) const = 0; |
| 34 | - * | 34 | + |
| 35 | - * @return future to vector of AgentCards | 35 | + /** |
| 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::Client | 39 | + */ |
| 40 | - | 40 | + virtual std::future<std::vector<AgentCard>> GetAllAgentCards() const = 0; |
| 41 | -#endif // A2A_CARD_RESOLVER | 41 | +}; |
| 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_CLIENT | 5 | +#ifndef A2A_CLIENT |
| 6 | -#define A2A_CLIENT | 6 | +#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 streaming | 19 | +/** |
| 20 | - bool polling = false; // Prefer polling for message/send | 20 | + * @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 preferences | 22 | +struct ClientConfig { |
| 23 | - std::vector<std::string> acceptedOutputModes; // accepted output modes | 23 | + /** @brief Whether the client supports streaming (message/stream). */ |
| 24 | - std::vector<PushNotificationConfig> pushNotificationConfigs; // default push configs | 24 | + 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 Message | 27 | + /** @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 AgentCard | 31 | + /** @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 destructor | 38 | +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 consumers | 43 | +/** @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/stream | 45 | + |
| 46 | - * | 46 | +/** @brief Per-request response handler (alias of Consumer). */ |
| 47 | - * @param[in] msg message to be sent | 47 | +using ResponseHandler = std::function<void(const ClientEvent&, const A2A::AgentCard&)>; |
| 48 | - * @param[in] context client call context | 48 | + |
| 49 | - * @param[in] handler response handler | 49 | +/** |
| 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 params | 55 | + /** @brief Virtual destructor. */ |
| 56 | - * tasks/get | 56 | + virtual ~Client() = default; |
| 57 | - * | 57 | + |
| 58 | - * @param[in] params params of the task to fetch | 58 | + /** |
| 59 | - * @param[in] context client call context, defaults to nullptr | 59 | + * @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 task | 60 | + * @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 id | 65 | + * @throws A2AClientException via future on transport or protocol errors. |
| 66 | - * tasks/cancel | 66 | + * @note 流式模式下 handler 会被同步多次调用。 |
| 67 | - * | 67 | + */ |
| 68 | - * @param[in] params task id param | 68 | + virtual std::future<void> SendMessage(const Message& msg, const ClientCallContext* context, |
| 69 | - * @param[in] context client call context, defaults to nullptr | 69 | + ResponseHandler handler, int timeout = 0) = 0; |
| 70 | - * @return future to a Task object representing the canceled task state | 70 | + |
| 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 tasks | 75 | + * @param[in] timeout Request timeout in seconds (0 = default). |
| 76 | - * tasks/pushNotificationConfig/set | 76 | + * @return Future that completes with the Task object. |
| 77 | - * | 77 | + * @throws A2AClientException via future on error. |
| 78 | - * @param[in] config configuration object specifying callback details | 78 | + */ |
| 79 | - * @param[in] context client call context, defaults to nullptr | 79 | + virtual std::future<Task> GetTask(const TaskQueryParams& params, const ClientCallContext* context = nullptr, |
| 80 | - * @return future to TaskPushNotificationConfig | 80 | + 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 task | 86 | + * @param[in] timeout Request timeout in seconds (0 = default). |
| 87 | - * tasks/pushNotificationConfig/get | 87 | + * @return Future that completes with the canceled Task. |
| 88 | - * | 88 | + * @throws A2AClientException via future on error. |
| 89 | - * @param[in] params task param | 89 | + */ |
| 90 | - * @param[in] context client call context, defaults to nullptr | 90 | + virtual std::future<Task> CancelTask(const TaskIdParams& params, const ClientCallContext* context = nullptr, |
| 91 | - * @return future to the push notification callback configuration for a specific task | 91 | + 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 task | 97 | + * @param[in] timeout Request timeout in seconds (0 = default). |
| 98 | - * tasks/pushNotificationConfig/list | 98 | + * @return Future that completes with the saved config. |
| 99 | - * | 99 | + * @throws A2AClientException via future on error. |
| 100 | - * @param[in] params task param specifying task information | 100 | + */ |
| 101 | - * @param[in] context client call context, defaults to nullptr | 101 | + virtual std::future<TaskPushNotificationConfig> SetTaskPushNotificationConfig(const TaskPushNotificationConfig& cfg, |
| 102 | - * @return future to the list of push notification callback configuration for a specific task | 102 | + 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 task | 108 | + * @param[in] timeout Request timeout in seconds (0 = default). |
| 109 | - * tasks/pushNotificationConfig/delete | 109 | + * @return Future that completes with the config. |
| 110 | - * | 110 | + * @throws A2AClientException via future on error. |
| 111 | - * @param[in] params task param specifying task information | 111 | + */ |
| 112 | - * @param[in] context client call context, defaults to nullptr | 112 | + virtual std::future<TaskPushNotificationConfig> GetTaskPushNotificationConfig( |
| 113 | - * @return future to void | 113 | + 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 id | 119 | + * @param[in] context Per-request client context. |
| 120 | - * | 120 | + * @param[in] timeout Request timeout in seconds (0 = default). |
| 121 | - * @param[in] params task id params | 121 | + * @return Future that completes with the config list. |
| 122 | - * @param[in] context client call context | 122 | + * @throws A2AClientException via future on error. |
| 123 | - * @param[in] handler response handler | 123 | + */ |
| 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 agent | 129 | + * @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 nullptr | 131 | + * @param[in] context Per-request client context. |
| 132 | - * @return future to AgentCard information | 132 | + * @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 events | 137 | + const ClientCallContext* context = nullptr, int timeout = 0) = 0; |
| 138 | - * | 138 | + |
| 139 | - * @param[in] c consumer object | 139 | + /** |
| 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 middleware | 144 | + * @param[in] timeout Request timeout in seconds (0 = default). |
| 145 | - * | 145 | + * @throws A2AClientException on transport or protocol errors. |
| 146 | - * @param[in] middleware interceptor object | 146 | + */ |
| 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 resources | 151 | + * @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 performed | 153 | + * @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::Client | 158 | + |
| 159 | - | 159 | + /** |
| 160 | -#endif | 160 | + * @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_INTERCEPTOR | 5 | #ifndef A2A_CLIENT_CALL_INTERCEPTOR |
| 6 | #define A2A_CLIENT_CALL_INTERCEPTOR | 6 | #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 | ||
| 14 | namespace A2A::Client { | 13 | namespace 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 | + */ | ||
| 17 | class ClientCallInterceptor { | 19 | class ClientCallInterceptor { |
| 18 | public: | 20 | public: |
| 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 headers | 25 | + * @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 intercept | 27 | + * @param[in,out] payload Serialized request body. |
| 30 | - * @param[in/out] payload data payload | 28 | + * @param[out] headers HTTP / transport headers to send. |
| 31 | - * @param[out] headers headers | 29 | + * @param[in] agentCard Agent card for this call; may be nullptr. |
| 32 | - * @param[in] agentCard agent card related to this intercept. may be null | 30 | + * @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_FACTORY | 5 | +#ifndef A2A_CLIENT_FACTORY |
| 6 | -#define A2A_CLIENT_FACTORY | 6 | +#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 destructor | 20 | +class ClientFactory { |
| 21 | - */ | 21 | +public: |
| 22 | - ~ClientFactory(); | 22 | + /** @brief Destructor. */ |
| 23 | - | 23 | + ~ClientFactory(); |
| 24 | - /** | 24 | + |
| 25 | - * @brief create client | 25 | + /** |
| 26 | - * | 26 | + * @brief Create a client with the default JSON-RPC transport. |
| 27 | - * @param[in] card agent card | 27 | + * @param[in] card Resolved agent card. |
| 28 | - * @param[in] config client config | 28 | + * @param[in] config Client behaviour configuration. |
| 29 | - * @param[in] consumers consumers of client being created | 29 | + * @param[in] consumers Optional event consumers. |
| 30 | - * @param[in] interceptors interceptors of client being created | 30 | + * @param[in] interceptors Optional request interceptors. |
| 31 | - * @return unique pointer of client been created | 31 | + * @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::Client | 41 | + * @param[in] transport Custom transport layer. |
| 42 | - | 42 | + * @param[in] consumers Optional event consumers. |
| 43 | -#endif | 43 | + * @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 | ||
| @@ -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 | ||
| 17 | namespace A2A::Client { | 15 | namespace A2A::Client { |
| 18 | 16 | ||
| 17 | +/** | ||
| 18 | + * @brief Transport-layer error delivered via TransportEventCallback. | ||
| 19 | + */ | ||
| 19 | struct TransportError { | 20 | struct 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 | + */ | ||
| 24 | using TransportEvent = std::variant<TransportError, Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, | 30 | using 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 | + */ | ||
| 26 | using TransportEventCallback = std::function<void(const std::string&, const TransportEvent&)>; | 38 | using 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 | + */ | ||
| 28 | class ClientTransport { | 44 | class ClientTransport { |
| 29 | public: | 45 | public: |
| 30 | - ~ClientTransport() = default; | 46 | + /** @brief Virtual destructor. */ |
| 47 | + virtual ~ClientTransport() = default; | ||
| 31 | 48 | ||
| 32 | /** | 49 | /** |
| 33 | - * @brief send message to server and get response | 50 | + * @brief Send a non-streaming message/send request. |
| 34 | - * | 51 | + * @param[in] requestId Correlation ID for the callback. |
| 35 | - * @param[in] requestId requestId | 52 | + * @param[in] request Message send parameters. |
| 36 | - * @param[in] request request data info | 53 | + * @param[in] context Per-request client context. |
| 37 | - * @param[in] context client call context | 54 | + * @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 callback | 60 | + * @brief Send a streaming message/stream request. |
| 44 | - * | 61 | + * @param[in] requestId Correlation ID for the callback. |
| 45 | - * @param[in] requestId requestId | 62 | + * @param[in] request Message send parameters. |
| 46 | - * @param[in] request request data info | 63 | + * @param[in] context Per-request client context. |
| 47 | - * @param[in] context client call context | 64 | + * @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 server | 70 | + * @brief Send a tasks/get request. |
| 54 | - * | 71 | + * @param[in] requestId Correlation ID. |
| 55 | - * @param[in] requestId requestId | 72 | + * @param[in] params Task query parameters. |
| 56 | - * @param[in] params query params | 73 | + * @param[in] context Per-request client context. |
| 57 | - * @param[in] context client call context | 74 | + * @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 task | 80 | + * @brief Send a tasks/cancel request. |
| 64 | - * | 81 | + * @param[in] requestId Correlation ID. |
| 65 | - * @param[in] requestId requestId | 82 | + * @param[in] params Task ID parameters. |
| 66 | - * @param[in] params task id params | 83 | + * @param[in] context Per-request client context. |
| 67 | - * @param[in] context client call context | 84 | + * @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 task | 90 | + * @brief Send a push-notification config set request. |
| 74 | - * | 91 | + * @param[in] requestId Correlation ID. |
| 75 | - * @param[in] requestId requestId | 92 | + * @param[in] config Push-notification configuration. |
| 76 | - * @param[in] config push notification config | 93 | + * @param[in] context Per-request client context. |
| 77 | - * @param[in] context client call context | 94 | + * @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 task | 100 | + * @brief Send a push-notification config get request. |
| 84 | - * | 101 | + * @param[in] requestId Correlation ID. |
| 85 | - * @param[in] requestId requestId | 102 | + * @param[in] params Query parameters. |
| 86 | - * @param[in] params task id and metadata information | 103 | + * @param[in] context Per-request client context. |
| 87 | - * @param[in] context client call context | 104 | + * @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 task | 110 | + * @brief Send a push-notification config list request. |
| 94 | - * | 111 | + * @param[in] requestId Correlation ID. |
| 95 | - * @param[in] requestId requestId | 112 | + * @param[in] params Query parameters. |
| 96 | - * @param[in] params task id and metadata information | 113 | + * @param[in] context Per-request client context. |
| 97 | - * @param[in] context client call context | 114 | + * @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 task | 120 | + * @brief Send a push-notification config delete request. |
| 104 | - * | 121 | + * @param[in] requestId Correlation ID. |
| 105 | - * @param[in] requestId requestId | 122 | + * @param[in] params Delete parameters. |
| 106 | - * @param[in] params task id and metadata information | 123 | + * @param[in] context Per-request client context. |
| 107 | - * @param[in] context client call context | 124 | + * @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 server | 130 | + * @brief Resubscribe to task streaming events. |
| 114 | - * | 131 | + * @param[in] requestId Correlation ID. |
| 115 | - * @param[in] requestId requestId | 132 | + * @param[in] params Task ID parameters. |
| 116 | - * @param[in] params task id params | 133 | + * @param[in] context Per-request client context. |
| 117 | - * @param[in] context client call context | 134 | + * @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 server | 140 | + * @brief Send an agent/getCard request. |
| 124 | - * | 141 | + * @param[in] requestId Correlation ID. |
| 125 | - * @param[in] requestId requestId | 142 | + * @param[in] context Per-request client context. |
| 126 | - * @param[in] context client call context | 143 | + * @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 callback | 148 | + * @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 fuction | 154 | + * @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::Client | 166 | } // 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_BUILDER | 5 | +#ifndef HTTP_CARD_RESOLVER_BUILDER |
| 6 | -#define HTTP_CARD_RESOLVER_BUILDER | 6 | +#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 destructor | 20 | +class HttpCardResolverBuilder final { |
| 21 | - */ | 21 | +public: |
| 22 | - ~HttpCardResolverBuilder(); | 22 | + /** @brief Destructor. */ |
| 23 | - | 23 | + ~HttpCardResolverBuilder(); |
| 24 | - /** | 24 | + |
| 25 | - * @brief build card resolver | 25 | + /** |
| 26 | - * | 26 | + * @brief Build an HTTP card resolver. |
| 27 | - * @param[in] baseUrl base url | 27 | + * @param[in] baseUrl Server base URL (e.g. "http://host:port"). |
| 28 | - * @param[in] agentCardPath agent card path | 28 | + * @param[in] agentCardPath Path to the agent card (default: /.well-known/agent-card.json). |
| 29 | - * @param[in] httpKwargs http args | 29 | + * @param[in] httpKwargs Extra HTTP headers or options. |
| 30 | - * @return A shared pointer to the created card resolver instance | 30 | + * @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::Client | 36 | +} // namespace A2A::Client |
| 37 | - | 37 | + |
| 38 | -#endif | 38 | +#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_ERROR | 5 | #ifndef A2A_ERROR |
| 6 | #define A2A_ERROR | 6 | #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 | + | ||
| 12 | namespace A2A { | 14 | namespace A2A { |
| 13 | -// Generic unsupported operation | 15 | + |
| 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 | + */ | ||
| 19 | struct A2AServerError : public std::runtime_error { | 54 | struct 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 error | 79 | +/** |
| 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 error | 95 | +/** |
| 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 wrapper | 110 | +/** |
| 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 A2A | 133 | } // namespace A2A |
| 63 | 134 | ||
| 64 | -#endif | 135 | +#endif |
| @@ -12,30 +12,45 @@ | |||
| 12 | 12 | ||
| 13 | namespace A2A::Server { | 13 | namespace A2A::Server { |
| 14 | 14 | ||
| 15 | +/** | ||
| 16 | + * @brief User-implemented agent logic for task execution and cancellation. | ||
| 17 | + * @note 实现此接口以处理 message/send 与 tasks/cancel 请求。 | ||
| 18 | + */ | ||
| 15 | class AgentExecutor { | 19 | class AgentExecutor { |
| 16 | public: | 20 | public: |
| 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 context | 25 | + * @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 information | 27 | + * @param[in] taskUpdater Updater for publishing status / artifact events. |
| 26 | - * @param[in] taskUpdater updater used to update events | 28 | + * @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 context | 33 | + * @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 information | 35 | + * @param[in] taskUpdater Updater for publishing events. |
| 34 | - * @param[in] taskUpdater updater used to update events | 36 | + * @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::Server | 54 | } // namespace A2A::Server |
| 40 | 55 | ||
| 41 | -#endif | 56 | +#endif |
| @@ -14,35 +14,43 @@ | |||
| 14 | 14 | ||
| 15 | namespace A2A::Server { | 15 | namespace A2A::Server { |
| 16 | 16 | ||
| 17 | +/** | ||
| 18 | + * @brief HTTP server binding and threading configuration. | ||
| 19 | + */ | ||
| 17 | struct HttpConfig { | 20 | struct 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 | + */ | ||
| 24 | class HttpServerBuilder { | 34 | class HttpServerBuilder { |
| 25 | public: | 35 | public: |
| 26 | - /** | 36 | + /** @brief Destructor. */ |
| 27 | - * @brief destructor | ||
| 28 | - */ | ||
| 29 | ~HttpServerBuilder(); | 37 | ~HttpServerBuilder(); |
| 30 | 38 | ||
| 31 | /** | 39 | /** |
| 32 | - * @brief create http server | 40 | + * @brief Build and return a configured HTTP server. |
| 33 | - * | 41 | + * @param[in] config HTTP listen configuration. |
| 34 | - * @param[in] config http config | 42 | + * @param[in] agentCard Public agent card. |
| 35 | - * @param[in] agentCard agent card object | 43 | + * @param[in] extendedAgentCard Authenticated extended card (may be empty). |
| 36 | - * @param[in] extendedAgentCard extended agent card object | 44 | + * @param[in] agentExecutor User agent logic implementation. |
| 37 | - * @param[in] agentExecutor agent executor object | 45 | + * @param[in] taskStore Task persistence backend (nullptr = in-memory). |
| 38 | - * @param[in] taskStore store object to store task object | 46 | + * @return Shared pointer to the started-ready Server instance. |
| 39 | - * @return A shared pointer to the created server instance | 47 | + * @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 | -#endif | 56 | +#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 | ||
| 17 | namespace A2A::Server { | 17 | namespace A2A::Server { |
| 18 | 18 | ||
| 19 | +/** @brief Opaque implementation of RequestContext (PIMPL). */ | ||
| 19 | class RequestContextImpl; | 20 | class 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 | - | ||
| 30 | class RequestContext { | 26 | class RequestContext { |
| 31 | public: | 27 | public: |
| 32 | /** | 28 | /** |
| 33 | - * @brief constructor | 29 | + * @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 parts | 38 | + * @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 parts | 40 | + * @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 context | 45 | + * @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 available | 51 | + * @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 request | 57 | + * @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 processed | 63 | + * @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 task | 75 | + * @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 available | 81 | + * @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 available | 87 | + * @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 available | 93 | + * @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 request | 99 | + * @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 activate | 105 | + * @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 | ||
| 8 | namespace A2A::Server { | 8 | namespace A2A::Server { |
| 9 | 9 | ||
| 10 | +/** | ||
| 11 | + * @brief Top-level A2A server interface. | ||
| 12 | + * @note 服务端生命周期:Start() → Stop()。 | ||
| 13 | + */ | ||
| 10 | class Server { | 14 | class Server { |
| 11 | public: | 15 | public: |
| 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 listen | 20 | + * @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 server | 27 | + * @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::Server | 32 | } // namespace A2A::Server |
| 29 | 33 | ||
| 30 | -#endif | 34 | +#endif |
| @@ -6,22 +6,48 @@ | |||
| 6 | #define A2A_SERVER_CALL_CONTEXT | 6 | #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 | + | ||
| 14 | namespace A2A::Server { | 15 | namespace A2A::Server { |
| 15 | 16 | ||
| 16 | -// Server-side call context analogous to Python's ServerCallContext | 17 | +/** @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 | + */ | ||
| 17 | struct ServerCallContext { | 24 | struct 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 extensions | 27 | + /** @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::Server | 51 | } // namespace A2A::Server |
| 26 | 52 | ||
| 27 | #endif | 53 | #endif |
| @@ -5,7 +5,6 @@ | |||
| 5 | #ifndef A2A_TASK_STORE | 5 | #ifndef A2A_TASK_STORE |
| 6 | #define A2A_TASK_STORE | 6 | #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 | ||
| 15 | namespace A2A::Server { | 14 | namespace A2A::Server { |
| 16 | 15 | ||
| 16 | +/** | ||
| 17 | + * @brief Persistence interface for A2A tasks. | ||
| 18 | + * @note 任务存储抽象;默认实现为内存存储。 | ||
| 19 | + */ | ||
| 17 | struct TaskStore { | 20 | struct 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 store | 25 | + * @brief Save or update a task. |
| 25 | - * | 26 | + * @param[in] task Task to persist. |
| 26 | - * @param[in] task transport type | 27 | + * @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 ID | 32 | + * @brief Retrieve a task by ID. |
| 33 | - * | 33 | + * @param[in] taskId Task identifier. |
| 34 | - * @param[in] taskId task id | 34 | + * @param[in] context Server call context. |
| 35 | - * @param[in] context server call context | 35 | + * @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 ID | 40 | + * @brief Delete a task by ID. |
| 41 | - * | 41 | + * @param[in] taskId Task identifier. |
| 42 | - * @param[in] taskId task id | 42 | + * @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/include/client/protocol_version_interceptor.h→A2A/cpp-sdk/src/client/protocol_version_interceptor.h+14-14
【openlibing.ci】检测到当前PR中存在代码检查告警抑制 31 处,详情见下表,请Committer检视合理性。 / Detected 31 code check alert suppression(s) in this PR, see table below. Committers please review.
# shellcheck disable=SC1091a2x/search/models.py
from a2x_registry.common.models import SearchResult # noqa: F401 — re-exporteda2x/utils/llm_client.py
from a2x_registry.common.llm_client import ( # noqa: F401backend/app.py
except Exception: # noqa: BLE001 — shutdown must not raisebackend/app.py
except Exception: # noqa: BLE001 — shutdown must not raisecluster/auth_handshake.py
except Exception: # noqa: BLE001 — any auth failure → unauthenticatedcluster/membership.py
except Exception: # noqa: BLE001 — skip a malformed recordcluster/membership.py
except Exception: # noqa: BLE001 — skip a malformed recordcluster/membership.py
except Exception as exc: # noqa: BLE001 — never kill the loopcluster/membership.py
except Exception: # noqa: BLE001 — any auth failure → unauthorizedcluster/store.py
except Exception as exc: # noqa: BLE001 — corrupt file must not crash bootcluster/store.py
except Exception as exc: # noqa: BLE001 — best-effort; don't propagatecluster/store.py
except Exception: # noqa: BLE001 — skip a malformed replicacluster/sweepers.py
except Exception as exc: # noqa: BLE001 — never kill the loopcluster/sweepers.py
except Exception as exc: # noqa: BLE001 — never kill the loopcluster/sweepers.py
except Exception as exc: # noqa: BLE001 — defensivecluster/sweepers.py
except Exception as exc: # noqa: BLE001 — defensiveheartbeat/router.py
except Exception as exc: # noqa: BLE001heartbeat/sweeper.py
from .errors import HeartbeatError # noqa: F401 — re-exported via __init__heartbeat/sweeper.py
except Exception as exc: # noqa: BLE001 — sweeper must survive any errorheartbeat/sweeper.py
except Exception as exc: # noqa: BLE001 — defensivetraditional/search/traditional_search.py
from a2x_registry.common.models import SearchResult # noqa: F401vector/search/vector_search.py
from a2x_registry.common.models import SearchResult # noqa: F401a2x_registry_client/async_client.py
except Exception as exc: # noqa: BLE001a2x_registry_client/client.py
except Exception as exc: # noqa: BLE001 — best-efforta2x_registry_client/heartbeat.py
except Exception as exc: # noqa: BLE001 — daemon must survivea2x_registry_client/heartbeat.py
import asyncio as _asyncio # noqa: E402 — keep below sync types to avoida2x_registry_client/heartbeat.py
from typing import Awaitable # noqa: E402a2x_registry_client/heartbeat.py
except Exception as exc: # noqa: BLE001a2x_registry_client/models.py
allowed = {f.name for f in fields(cls)} # type: ignore[arg-type]a2x_registry_client/models.py
return cls(**kwargs) # type: ignore[call-arg]