AI Agent人工智能认证鉴权服务注册发现工具调用【免费下载链接】agent-protocolopenJiuwen agent-protocol提供agent通信协议实现包括MCP、A2A协议的C SDK项目地址https://gitcode.com/openJiuwen/agent-protocol点击查看免费下载本篇技术指南围绕 openJiuwen agent-protocol 仓库中A2A/cpp-sdk展开系统讲解其环境准备、编译构建、双终端联调、单元测试与日志诊断的完整链路并深入到examples/示例、src/源码与tests/ut/测试实现帮助读者快速上手基于 HTTP JSON-RPC 的智能体间通信开发。一、SDK 定位与能力概述A2A/cpp-sdk是 Agent-to-AgentA2A协议 v1.0 的 C 实现提供 A2A 客户端与服务器两大能力全部基于HTTP JSON-RPC完成智能体间通信。作为 openJiuwen agent-protocol 仓库中与 MCP C SDK 并列的协议实现其核心能力包括构建 A2A 客户端发现 Agent Card、发送消息、查询/取消任务、接收流式事件构建 A2A 服务器注册AgentExecutor、管理任务生命周期、暴露 JSON-RPC 端点扩展能力多模态Part、推送通知配置、请求拦截器、自定义TaskStore等详见A2A/cpp-sdk/examples/与 API 文档。SDK 的模块划分可从A2A/cpp-sdk/src/目录结构确认包含client/连接与传输、server/HTTP 服务、任务管理、请求处理、transport/HTTP Server Transport 与流式发射器、shared/JSON-RPC、HTTP 公共件、错误、定时器等组件。二、文档地图A2A/cpp-sdk/README.md将配套文档组织为下表阅读本文时可配合查阅文档说明依赖说明运行/编译依赖、版本、各发行版安装命令测试说明单元测试、覆盖率、ASANAPI 文档索引Client / Server API、协议对照错误处理说明错误码、异常类型与处理建议日志说明SDK 诊断日志、A2A_LOG/SetLogCallback用法三、环境要求操作系统Linuxglibc 或 musl为主要验证平台编译器C17 及以上GCC 9 / Clang 10CMake≥ 3.15见A2A/cpp-sdk/CMakeLists.txt依赖详见 依赖说明。3.1 依赖清单与版本依赖最低版本用途OpenSSL1.1.1TLS、加密libcurl7.xHTTP Client 传输nlohmann_json3.11.2JSON 序列化libevent2.1.12事件循环Server I/Ohttp_parser2.9.4HTTP 解析其中 OpenSSL、libcurl、libevent、nlohmann_json 属于系统依赖需手动或通过scripts/install_deps.sh安装http_parser、Google Test 等则由 CMake 在构建时自动拉取A2A/cpp-sdk/third_party/third_party.cmake系统包优先否则使用 FetchContent。3.2 一键安装系统依赖cd A2A/cpp-sdk bash scripts/install_deps.sh脚本会检测 Ubuntu/Debian、RHEL/CentOS/Fedora/EulerOS、Arch 等发行版并安装对应开发包。手动安装命令如下Ubuntu / Debiansudo apt-get update sudo apt-get install -y \ build-essential cmake \ libssl-dev \ libcurl4-openssl-dev \ libevent-dev \ nlohmann-json3-devCentOS / RHEL / Fedora / EulerOSsudo yum install -y \ gcc-c cmake \ openssl-devel \ libcurl-devel \ libevent-develArch Linuxsudo pacman -S --needed base-devel cmake openssl curl libevent nlohmann-json安装后可验证依赖openssl version # OpenSSL curl-config --version # libcurl cmake --version # CMake脚本解释器提醒A2A/cpp-sdk/scripts/下所有脚本均为 Bash含set -o pipefail等语法请一律使用bash scripts/xxx调用勿用sh在 dash 等环境下sh scripts/build.sh会报错如set: Illegal option -o pipefail。离线构建提示若需离线构建可预先安装上述系统包并配置 CMake 使用系统提供的 json/libevent 等见A2A_USE_SYSTEM_*选项从其他机器同步工程时建议清理third_party/*-subbuild后再配置避免 CMakeCache 路径不一致。四、快速入门在A2A/cpp-sdk目录下按以下顺序执行约 5–15 分钟视网络与编译环境而定# 1. 安装系统依赖curl、openssl、libevent 等部分发行版需 sudo sudo bash scripts/install_deps.sh # 2. 编译 SDK 与示例产物output/lib/liba2a.so、output/bin/* bash scripts/build.sh -e # 3. 一键冒烟测试全部示例脚本内会先后台起 Server再跑 Client bash scripts/run_example.sh默认示例端口为8888JSON-RPC 端点地址为http://127.0.0.1:8888/jsonrpc。如需指定端口A2A_EXAMPLE_PORT9000 bash scripts/run_example.sh4.1 方式一单终端一键推荐首次验证bash scripts/run_example.sh # 依次跑 helloworld / streaming后台起 Server → Client 检查 → 停止 Server4.2 方式二双终端Server 常驻便于反复调试 Clientexport LD_LIBRARY_PATH$(pwd)/output/lib:${LD_LIBRARY_PATH:-} # 终端 1前台运行 ServerCtrlC 停止 ./output/bin/helloworld_server -i 127.0.0.1 -p 8888 # 终端 2Server 已监听后再跑 Client ./output/bin/helloworld_client -i 127.0.0.1 -p 8888streaming_server/streaming_client同理须先 Server 后 Client且两端端口一致。注意事项必须先有 Server 再跑 Client同一终端内直接连跑两条命令时Client 会因 Server 未就绪而失败run_example.sh无参数时在同一脚本内后台起 Server、跑 Client 后自动清理进程手动启动前须先bash scripts/build.sh -e并设置LD_LIBRARY_PATH。五、构建与安装统一构建入口为A2A/cpp-sdk/scripts/build.sh注意不是仓库根目录下的build.sh。其脚本源码从set -euo pipefail开始默认BUILD_TYPERelease、BUILD_DIRbuildA2A_BUILD_CLIENT1、A2A_BUILD_SERVER1通过命令行参数控制裁剪。# Release 构建默认仅核心库 bash scripts/build.sh # Release 构建 示例 bash scripts/build.sh -e # Debug 构建含调试符号 bash scripts/build.sh -t Debug # 编译并启用单元测试 bash scripts/build.sh -u -t Debug # 覆盖率构建 运行测试报告见 docs/testing.md bash scripts/build.sh -c # AddressSanitizer 调试构建 bash scripts/build.sh -u -t Debug --asan5.1 常用 CMake 裁剪选项选项含义-h, --help显示帮助信息并退出-e, --with-examples编译examples/下示例程序-u, --with-tests编译单元测试-c, --coverage启用覆盖率隐含-uDebug--no-client不编译 Client 组件--no-server不编译 Server 组件--asan启用 AddressSanitizer自动使用 Debug-t, --type typeCMake 构建类型Debug、Release、RelWithDebInfo、MinSizeRel默认Release日常开发/测试常用Debug发布用Release-b, --build-dir dir构建目录默认build-g, --generator nameCMake 生成器如Ninja、NMake Makefiles5.2 构建产物路径说明output/lib/liba2a.so共享库output/include/公共头文件types.h、client/、server/等output/bin/示例二进制需-e集成到自己工程时链接liba2a.so并添加头文件路径output/include或源码树include/运行时需要将output/lib加入LD_LIBRARY_PATH具体集成方式可参考A2A/cpp-sdk/examples/CMakeLists.txt。六、运行示例示例位于A2A/cpp-sdk/examples/目录共四个可执行程序示例源文件说明Hello World Serverexamples/helloworld_server.cppHTTP Server非流式消息处理Hello World Clientexamples/helloworld_client.cpp获取 Agent Card、发送消息Streaming Serverexamples/streaming_server.cpp流式任务状态与产物推送Streaming Clientexamples/streaming_client.cppmessage/stream流式接收6.1 方式一单终端run_example.shbash scripts/build.sh -e bash scripts/run_example.sh脚本会对helloworld、streaming各执行一轮后台起 Server → HTTP/JSON-RPC 检查 → 跑 Client → 停止 Server。6.2 方式二双终端手动Server 常驻export LD_LIBRARY_PATH$(pwd)/output/lib:${LD_LIBRARY_PATH:-} # 终端 1 ./output/bin/helloworld_server -i 127.0.0.1 -p 8080 # 终端 2须等 Server 监听后再执行 ./output/bin/helloworld_client -i 127.0.0.1 -p 8080注意事项必须先有 Server 再跑 ClientServer 前台运行会占用终端Client 应在另一终端连接同一-i/-p运行示例二进制前须bash scripts/build.sh -e并将output/lib加入LD_LIBRARY_PATH。6.3 从示例看 SDK 调用链路以helloworld_server.cpp为例服务端启动的完整流程在源码中清晰可见A2A/cpp-sdk/examples/helloworld_server.cpp#L150-L211阻塞SIGINT/SIGTERM信号pthread_sigmask(SIG_BLOCK, ...)后通过sigwait同步等待退出信号std::make_sharedMyAgentExecutor()创建业务执行器构造A2A::AgentCard填写name、description、version、defaultInputModes、defaultOutputModes、capabilities.streaming并设置supportedInterfacesurl http:// ip : port /jsonrpc、protocolBinding JSONRPC、protocolVersion 1.0填充A2A::Server::HttpConfigip、portA2A::Server::HttpServerBuilder::Build(httpConfig, agentCard, {}, executor, nullptr)构建 ServertaskStore传nullptr表示使用内存存储server-Start()返回值非 0 即启动失败阻塞等待信号后server-Stop()。helloworld_client.cppA2A/cpp-sdk/examples/helloworld_client.cpp#L94-L180则演示了客户端侧流程构造 Agent Card → 通过HttpCardResolverBuilder从/.well-known/agent-card.json拉取 Card →ClientFactory::Create(card, cfg)创建客户端 → 构造带 text 与 data 两种Part的Message→SendMessage(msg, nullptr, handler)异步发送通过std::variantMessage, A2AError, std::pairTask, UpdateEvent类型的ClientEvent用std::visit分发处理响应。cfg.supportedTransports {JSONRPC}指定了客户端支持的传输标签。七、运行测试SDK 测试基于Google Test通过CTest发现与运行测试源码位于A2A/cpp-sdk/tests/ut/默认不编译需显式开启A2A_ENABLE_TESTS。# 构建 运行 ctest含覆盖率与 ASAN默认 bash scripts/run_ut.sh # 跳过覆盖率更快 bash scripts/run_ut.sh --no-coverage # 跳过 ASAN bash scripts/run_ut.sh --no-coverage --no-asan # 或 A2A_SKIP_ASAN1 bash scripts/run_ut.sh --no-coverage也可手动构建后运行bash scripts/build.sh -u -t Debug cd build export LD_LIBRARY_PATH../output/lib:${LD_LIBRARY_PATH:-} ctest --output-on-failure7.1 测试构建选项与 CMake 变量映射选项CMake 变量说明-t, --type typeCMAKE_BUILD_TYPE构建类型Debug、Release、RelWithDebInfo、MinSizeRel默认Release-u, --with-testsA2A_ENABLE_TESTSON编译单元测试-c, --coverageA2A_ENABLE_COVERAGEON启用覆盖率隐含--with-tests--no-clientA2A_BUILD_CLIENTOFF跳过 Client 模块--no-serverA2A_BUILD_SERVEROFF跳过 Server 模块--asanASANenable启用 AddressSanitizerDebugrun_ut.sh默认启用AddressSanitizer与覆盖率gcovr可通过--no-coverage、--no-asan或A2A_SKIP_ASAN1关闭。覆盖率报告默认输出到build/coverage_report.htmlHTML 格式需 gcovrrun_ut.sh在缺少 gcovr 时会跳过 HTML 报告并提示pip install gcovr。7.2 测试模块结构tests/ut/ ├── client/ # 客户端、Card Resolver、Transport ├── server/ # 服务端、HTTP Server、Request Handler ├── shared/ # 错误、HTTP、UUID、定时器等 ├── transport/ # HTTP Server Transport、流式发射器 ├── event/ # 事件系统 ├── log/ # 日志模块 ├── utils/ # 消息工具、ID 生成 └── fixtures/ # 共享 mock 与辅助工具编写约定详见 测试说明测试源文件命名test_module.cpp尽量与src/module/对应a2a_ut_test二进制链接liba2a.so不重复编译全部 SDK 源码需要 bind/listen 的测试优先使用A2A::Test::GetFreeTcpPort()A2A/cpp-sdk/tests/ut/fixtures/test_network.h避免硬编码端口复用fixtures/中的 mockmock_agent_executor.h、mock_task_store.h、test_agent_card.h等禁止占位测试如EXPECT_TRUE(true)每个用例须断言真实行为。7.3 常见问题排查问题处理Error: Build directory not found先执行bash scripts/build.sh -u -t Debug无测试用例确认构建时使用了--with-tests且未用--no-client/--no-server裁剪被测模块运行时找不到 liba2a.soexport LD_LIBRARY_PATH$(pwd)/output/lib:$(pwd)/build:${LD_LIBRARY_PATH:-}CMake 配置失败stale FetchContent 缓存清理third_party/*-subbuild、third_party/*-build、build、_deps后重编端口冲突部分测试使用动态端口仍失败可单独运行模块测试如cd build ctest -R LoggerTest --output-on-failure单元测试与示例冒烟的关系单元测试验证 SDK 内部模块与协议逻辑scripts/run_example.sh验证可执行示例链路不属于 CTest。两者互补发布前建议均跑通。八、日志与可观测性SDK 存在两套互不自动联动的体系详见 日志说明体系API输出目标用途SDK 诊断日志A2A_LOG、SetLogLevel、SetLogCallback默认stdout可自定义SDK 与应用程序内部调试协议运行时数据ClientEvent、TaskStatusUpdateEvent、A2AError等JSON-RPC 响应 / SSE 流任务状态、业务消息、对外错误A2A 协议当前未定义独立的协议级日志推送通道任务进度与错误应通过协议事件传递对照见 protocol-mapping.md。8.1 基本用法#include a2a_log.h A2A::Log::SetLogLevel(A2A::Log::A2A_LOG_LEVEL::INFO); // 默认 INFO A2A_LOG(A2A::Log::A2A_LOG_LEVEL::INFO, std::string(server started on port ) std::to_string(port));A2A_LOG第一个参数为级别第二个参数为已拼接好的std::string不支持printf风格占位符。8.2 日志级别常量数值说明A2A_LOG_LEVEL::DEBUG3调试A2A_LOG_LEVEL::INFO4信息默认阈值A2A_LOG_LEVEL::WARN5警告A2A_LOG_LEVEL::ERROR6错误A2A_LOG_LEVEL::FATAL7致命SetLogLevel设置全局阈值低于阈值的日志在A2A_LOG入口即被过滤自定义 callback 收到的也是过滤后的消息。无效级别小于DEBUG或大于FATAL调用SetLogLevel会返回-1级别保持不变。8.3 输出格式与默认 sink通过A2A_LOG输出的每行前缀格式为[YYYY-MM-DD HH:MM:SS.mmm] [tid] [LEVEL] file.cpp::Function:[line] message其中LEVEL为DEBUG/INFO/WARN/ERROR/FATAL之一tid为 Linux 线程 IDsyscall(SYS_gettid)。默认回调A2aPrintfImpl通过printf写入stdout末尾自动换行。注意若应用将stdout用于其他用途如管道输出、与协议数据混写建议在进程启动早期通过SetLogCallback将日志重定向到stderr或文件void StderrLogCallback(A2A::Log::A2A_LOG_LEVEL /*level*/, std::string message) { fprintf(stderr, %s\n, message.c_str()); } A2A::Log::SetLogCallback(StderrLogCallback);8.4 自定义回调的行为约束SetLogCallback进程内仅可成功调用一次重复调用返回-1并向 stdout 打印提示log callback can only be set once设置自定义回调后无法通过 API 恢复默认A2aPrintfImpl如需切换 sink应在自定义回调内部分发若logCallback为nullptrA2A_LOG不会输出。与 spdlog、glog 等常见日志库集成时在SetLogCallback注册的函数内转发message即可级别映射需自行对照上表。相关测试可参考A2A/cpp-sdk/tests/ut/log/如test_logger.cpp、test_a2a_log_internal.cpp。九、错误处理要点SDK 同时使用多种机制表达失败且彼此不自动转换详见 错误处理说明表达方式典型场景如何感知A2AClientException及子类Client 传输层、JSON-RPC、A2A 协议错误RPCfuture.get()抛异常A2AServerError及子类Server handler 内不可恢复错误映射为 JSON-RPC error 响应A2AError结构体流式ClientEvent中的协议错误ResponseHandler/Consumer回调intServer::Start()Server 启动失败返回非 0详情见日志SendMessage、GetTask、CancelTask、GetCard等返回std::future在future.get()时可能抛出A2AClientJSONError对端 JSON-RPC / A2A error、A2AClientHTTPError非 2xx、A2AClientTimeoutError请求超时等。推荐捕获顺序为先子类后基类try { auto task client-GetTask(params).get(); } catch (const A2A::A2AClientJSONError e) { // 协议错误读 e.errorCode、e.message } catch (const A2A::A2AClientHTTPError e) { // HTTP 错误读 e.statusCode } catch (const A2A::A2AClientException e) { // 其他 Client 错误 } catch (const std::runtime_error e) { // SDK 本地错误 }服务端Start()一般不抛异常失败原因端口占用、bind 失败等需通过A2A_LOG日志排查AgentExecutor::Execute抛出的A2AServerError会被 SDK 映射为 JSON-RPC error。常见错误码包括 JSON-RPC 标准码JSONRPC_PARSE_ERROR -32700、JSONRPC_INVALID_REQUEST -32600、JSONRPC_METHOD_NOT_FOUND -32601、JSONRPC_INVALID_PARAMS -32602、JSONRPC_INTERNAL_ERROR -32603以及 A2A 扩展码如TASK_NOT_FOUND -32001。十、客户端与服务端 API 速览10.1 架构概览A2A/cpp-sdk/docs/api/README.md给出了清晰的分层调用关系HttpCardResolverBuilder / ClientFactory ↓ Client ClientTransportJSON-RPC ↓ HTTP → Agent Server/jsonrpc HttpServerBuilder ↓ Server AgentExecutor TaskStore ↓ HTTP JSON-RPC /.well-known/agent-card.json10.2 客户端核心 API发现 Agent CardHttpCardResolverBuilder::Build(baseUrl)→resolver-GetAgentCard()默认路径/.well-known/agent-card.json创建客户端ClientFactory::Create(card, config)ClientConfig关键字段包括streaming是否使用SendStreamingMessage、polling非流式时是否轮询任务状态、supportedTransports、acceptedOutputModes、pushNotificationConfigs常用 RPCGetCard()、SendMessage(msg, ctx, handler, timeout)、GetTask(params)、CancelTask(params)、Resubscribe(params, ctx, handler)、SetTaskPushNotificationConfig等推送通知配置 CRUD、AddEventConsumer(c)、AddRequestMiddleware(m)、Close()流式消息config.streaming true时SendMessage的回调可能多次收到std::pairTask, UpdateEvent状态/产物更新。完整示例见 client.md 与 helloworld_client.cpp。10.3 服务端核心 API创建服务端HttpServerBuilder::Build(httpConfig, agentCard, extendedAgentCard, executor, taskStore)taskStore传nullptr时使用内存InMemoryTaskStoreHttpConfig关键字段ip监听 IP、port监听端口、endpointJSON-RPC 路径默认/jsonrpc、ioThreadNumI/O 事件循环线程数实现AgentExecutor重写Execute(context, taskUpdater)与Cancel(context, taskUpdater)。同步处理时在Execute内直接通过TaskUpdater推送状态与消息流式处理时多次调用taskUpdater发布TaskStatusUpdateEvent/TaskArtifactUpdateEventTaskUpdater常用方法StartWork()任务进入 WORKING 状态、SendResponseMessage(msg)发送 Agent 回复消息、Cancel()标记任务已取消。AgentCard.supportedInterfaces应包含指向http://host:port/jsonrpc的 JSON-RPC 接口描述。详细用法见 server.md 与 helloworld_server.cpp。10.4 协议方法与 API 对照SDK 内部 JSON-RPC 方法名定义在A2A/cpp-sdk/src/shared/common_types.h与 A2A 协议及公开 Client API 的对应关系完整对照见 protocol-mapping.mdJSON-RPC methodSDKA2A 协议能力C APISendMessagemessage/sendSendMessagestreamingfalseSendStreamingMessagemessage/streamSendMessagestreamingtrueGetTasktasks/getGetTask(params)CancelTasktasks/cancelCancelTask(params)SubscribeToTasktasks/resubscribeResubscribe(params, ctx, handler)CreateTaskPushNotificationConfigtasks/pushNotificationConfig/setSetTaskPushNotificationConfigGetAgentCardagent/getCardSDK 扩展标识GetCard()Agent Card 的 HTTP 获取路径GET /.well-known/agent-card.json为推荐方式无需走 JSON-RPC。流式响应时 SDK 将 SSE / 流式 JSON 解析为ClientEvent流类型常量包括task完整 Task 对象、status-updateTaskStatusUpdateEvent、artifact-updateTaskArtifactUpdateEvent。应用侧主要实现AgentExecutor及可选TaskStore无需直接注册每个 JSON-RPC 方法。十一、参与贡献与 License欢迎提交 Issue、文档改进与代码贡献。提交 PR 前请运行bash scripts/run_ut.sh --no-coverage确保单元测试通过。本项目依据Apache-2.0许可证授权Copyright (c) 2025-2026 Huawei Technologies Co., Ltd.并包含或依赖第三方开源软件版权和许可证信息归原作者所有详见A2A/../Third_Party_Open_Source_Software_Notice.txt及相应文件。总结本文以A2A/cpp-sdk为主线完整覆盖了从依赖安装、构建编译、示例联调到单元测试与日志诊断的整条实战链路。配合 API 文档索引、错误处理说明 与四个示例程序开发者可以在 Linux C17 环境下快速搭建起一个可运行、可调试、可扩展的 A2A 智能体通信应用。赞分享AI Agent人工智能认证鉴权服务注册发现工具调用【免费下载链接】agent-protocolopenJiuwen agent-protocol提供agent通信协议实现包括MCP、A2A协议的C SDK项目地址https://gitcode.com/openJiuwen/agent-protocol点击查看免费下载相关推荐openJiuwen agent-protocol A2A C SDK 客户端开发指南Agent Card 发现、RPC 调用与流式消息openJiuwen agent protocol A2A C SDK 客户端开发指南Agent Card 发现、RPC 调用与流式消息 本篇技术指南以AI Agent人工智能认证鉴权服务注册发现工具调用A2A C SDK 公共 API 完全指南Agent Card 发现、客户端/服务端开发与协议方法映射A2A C SDK 公共 API 完全指南Agent Card 发现、客户端/服务端开发与协议方法映射 本文是 openJiuwen agent protAI Agent人工智能认证鉴权服务注册发现工具调用AG-UI C SDK 实战指南基于 libcurl 与 SSE 流式协议构建 Agent-UI 交互的 C 客户端AG UI C SDK 实战指南基于 libcurl 与 SSE 流式协议构建 Agent UI 交互的 C 客户端 AG UIAgent User人工智能AI Agent上一篇Keyboard Chatter Blocker终极指南专业解决机械键盘连击问题的完整方案下一篇QuickLook Office预览插件终极指南3秒极速查看Word、Excel、PPT文件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考