人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载VoltAgent 是一个开源的 TypeScript AI Agent 工程化框架而voltagent/a2a-server是它提供的Agent-to-AgentA2A协议服务端实现。本篇文章以仓库中的 with-a2a-server 示例 为主体完整讲解如何把一个普通的 VoltAgent Agent 通过 A2A 的 JSON-RPC 端点暴露给外部让其他 Agent、IDE 或编排框架可以通过.well-known发现它、通过/a2a/:serverId向它发送消息并管理任务。读完本文你将掌握 A2A 服务的装配方式、Agent Card 发现机制、四大 JSON-RPC 方法message/send、message/stream、tasks/get、tasks/cancel的调用与内部实现以及如何用冒烟测试端到端验证整个链路。什么是 A2A 协议为什么 VoltAgent 要支持它A2AAgent-to-Agent是一套让 AI Agent 之间相互发现、通信与协作的开放协议。与 MCPModel Context Protocol面向 Agent 与工具/数据源不同A2A 解决的是Agent 与 Agent之间的互操作问题一个 Agent 需要调用另一个 Agent 的能力而双方不需要共享同一套运行时。VoltAgent 在voltagent/a2a-server包中提供了这套协议的服务端实现。根据 packages/a2a-server/README.md 的说明该包把 VoltAgent 的 Agent 暴露到 A2A JSON-RPC 协议之上使其他 Agent、IDE 或编排框架可以通过定义良好的端点与之交互目前该包仍标记为ExperimentalAPI 在首个稳定版发布前可能发生变化。with-a2a-server示例展示的正是这一能力的落地形态一个极简 VoltAgent 项目包含一个SupportAgent和一个status工具通过voltagent/a2a-server与voltagent/server-hono的集成对外提供一个Agent Card发现文档说明该 Agent 的能力与端点地址一个JSON-RPC 消息端点接收符合 A2A 规范的请求并驱动内部 Agent 执行完整的任务生命周期提交、执行中、完成、失败、取消与内存任务存储。示例结构总览examples/with-a2a-server ├── src/ │ ├── agents/assistant.ts # 示例 Agent 定义含 status 工具 │ └── index.ts # VoltAgent 启动引导 A2A 服务器注册 ├── scripts/ │ └── smoke-test.mjs # 端到端冒烟测试脚本 ├── package.json ├── tsconfig.json └── README.md与仓库中其他示例一样package.json中定义了devtsx watch --env-file.env ./src、buildtsc、start、test:smoke等脚本并声明了对voltagent/a2a-server、voltagent/core、voltagent/internal、voltagent/logger、voltagent/server-hono、ai、zod的依赖具体可见 examples/with-a2a-server/package.json。环境准备与本地运行示例 README 明确给出了前置条件与运行方式完整继承如下前置条件Node.js 20pnpm环境变量OPENAI_API_KEY示例 Agent 使用 OpenAI 模型创建项目若尚未创建npm create voltagent-applatest -- --example with-a2a-server安装依赖并启动pnpm install pnpm --filter voltagent-example-with-a2a-server devdev脚本实际执行的是tsx watch --env-file.env ./src即监听模式启动并会加载项目根目录的.env文件OPENAI_API_KEY可放在其中。Hono 服务器监听在http://localhost:3141。从 Agent 定义到 A2A 暴露两个关键源码文件1. Agent 与工具定义examples/with-a2a-server/src/agents/assistant.ts 中定义了一个带status工具的SupportAgentimport { Agent, createTool } from voltagent/core; import { z } from zod; const statusTool createTool({ name: status, description: Return the current time in ISO format, parameters: z.object({}), async execute() { return { timestamp: new Date().toISOString(), }; }, }); export const assistant new Agent({ id: supportagent, name: SupportAgent, instructions: Reply with helpful answers and include the current time when relevant., model: openai/gpt-4o-mini, tools: [statusTool], }); export const tools { status: statusTool };要点Agent 的id为supportagent这个 id 会出现在后续的发现路径/.well-known/supportagent/agent-card.json和 JSON-RPC 路径/a2a/supportagent中工具参数使用zod的z.object({})描述说明该工具不需要额外参数execute()返回 ISO 格式时间戳用于演示 Agent 在回复中引用工具结果。2. A2A 服务器创建与 VoltAgent 装配examples/with-a2a-server/src/index.ts 是核心装配入口import { A2AServer } from voltagent/a2a-server; import { VoltAgent } from voltagent/core; import { createPinoLogger } from voltagent/logger; import { honoServer } from voltagent/server-hono; import { assistant } from ./agents/assistant; const logger createPinoLogger({ name: with-a2a-server, level: debug, }); const a2aServer new A2AServer({ name: SupportAgent, version: 0.1.0, description: Expose VoltAgent over the Agent-to-Agent protocol, }); new VoltAgent({ agents: { assistant, }, a2aServers: { supportAgent: a2aServer, }, server: honoServer({ port: 3141 }), logger, }); logger.info(VoltAgent A2A example is running on http://localhost:3141);装配逻辑分三步创建A2AServer通过构造参数声明服务器元信息name、version、description。A2AServerConfig还支持id、provider组织与官网 URL、agents直接在服务器上挂 Agent以及filterAgents按请求上下文过滤可暴露的 Agent详见 packages/a2a-server/src/types.ts在VoltAgent中登记通过a2aServers字段以serverId - A2AServer的形式注册键supportAgent就是路径中的 serverId挂载 Hono 服务器honoServer({ port: 3141 })提供 HTTP 传输层端口为 3141。从源码看VoltAgent在初始化时会对a2aServers逐项调用initializeA2AServerpackages/core/src/voltagent.ts其内部把实例注册进 A2A 注册表并注入依赖private initializeA2AServer(server: A2AServerLike | A2AServerFactory): A2AServerLike { const instance: A2AServerLike typeof server function ? server() : server; this.a2aServerRegistry.register(instance, this.getA2ADependencies()); this.a2aServers.add(instance); return instance; }这里A2AServerLike | A2AServerFactory意味着除了直接传实例还可以传一个返回实例的工厂函数便于懒加载。注入的依赖来自getA2ADependencies()packages/core/src/voltagent.ts即 VoltAgent 全局的agentRegistry——这让 A2A 服务器可以访问框架中注册的所有 Agent而不只是构造时传入的那几个。A2A 服务器的依赖契约定义在 packages/internal/src/a2a/types.tsagentRegistry.getAgent(id)与agentRegistry.getAllAgents()加上可选的taskStore。发现机制Agent Card 与.well-knownA2A 协议要求 Agent 通过标准位置暴露其能力描述文档Agent Card。示例中Hono 服务器启动后即可直接抓取发现文档curl http://localhost:3141/.well-known/supportagent/agent-card.json | jq返回的卡片通过url字段公布 JSON-RPC 端点{ url: http://localhost:3141/a2a/supportagent }这个路由的规范定义在 packages/server-core/src/routes/definitions.tsGET /.well-known/:serverId/agent-card.jsonOpenAPI 摘要为 Get A2A agent card。Hono 适配层在 packages/server-hono/src/routes/a2a.routes.ts 中实现先按serverId从注册表解析出 Agent再调用resolveAgentCard生成卡片找不到时返回 404参数非法时返回 400。卡片本身由buildAgentCard生成packages/a2a-server/src/adapters/agent.ts其结构对应 types.ts 中的 AgentCard包括字段说明示例值来源nameAgent 名称agent.id ?? agent.name即supportagentdescription描述默认取agent.purposeurlJSON-RPC 端点绝对地址基于请求 URL 解析/a2a/:serverIdprovider/version服务器元信息A2AServer配置capabilities能力声明默认streaming: true、pushNotifications: false、stateTransitionHistory: falsedefaultInputModes/defaultOutputModes输入输出模式均为[text]skills技能列表由agent.getTools()映射tags: [tool]一个值得注意的实现细节Agent 的每个工具会被自动映射为卡片中的一项skill外部 Agent 据此即可感知该 Agent 具备哪些能力。消息端点向 Agent 发送 JSON-RPC 请求拿到卡片中的url后即可向 JSON-RPC 端点发消息。示例 README 给出的请求体curl -X POST http://localhost:3141/a2a/supportagent \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: message/send, params: { message: { kind: message, role: user, messageId: msg-1, parts: [{ kind: text, text: What time is it? }] } } }协议层对请求的约束jsonrpc必须为2.0且method必须是字符串校验见 protocol.ts 的 isJsonRpcRequestparams.message必须存在、parts必须为非空数组当前实现只支持kind: text的纯文本消息部件其他类型会被拒绝校验见 server.ts 的 validateMessageSendParams消息可选携带taskId、contextId若缺失则由服务端生成randomUUID。服务端入口handleRequestpackages/a2a-server/src/server.ts是一个按method分发的 JSON-RPC 处理器支持四种方法方法作用返回message/send同步发送一条消息并等待执行完成TaskRecordmessage/stream以 SSE 流式发送消息逐段推送任务状态异步流逐帧TaskRecordtasks/get按任务 id 查询历史与状态TaskRecordtasks/cancel取消正在执行的任务TaskRecord状态为canceled请求的上下文userId、sessionId、metadata可通过context查询参数JSON 编码或请求体中的context字段传入由 Hono 路由解析合并见 packages/server-hono/src/routes/a2a.routes.ts最终在调用 Agent 时转换为conversationId、abortSignal、context等执行选项见 server.ts 的 buildAgentCallOptions。任务生命周期与消息映射A2A 的核心抽象是Task任务每次对话都对应一个任务任务有明确的状态机。TaskState定义在 packages/a2a-server/src/types.tssubmitted → working → completed ↘ failed ↘ canceled任务记录TaskRecordtypes.ts包含id、contextId、status状态 时间戳 关联消息、history完整消息历史、可选的artifacts与metadata。状态迁移由 packages/a2a-server/src/tasks.ts 中的纯函数完成createTaskRecord初始为submitted、appendMessage追加消息、updateLastMessage更新最后一条用于流式增量、transitionStatus迁移状态并打时间戳、ensureCancelable终态任务不可再取消、upsertArtifact按名字写入或合并产物。A2A 消息与 VoltAgent 内部消息的转换发生在适配层 packages/a2a-server/src/adapters/message.tstoVoltAgentMessage取第一条 text 部件作为内容把role: agent映射为assistantfromVoltAgentMessage反向映射回 A2A 消息并生成新的messageId。任务存储默认使用InMemoryTaskStorepackages/a2a-server/src/store.ts它以agentId::taskId为键在内存Map中保存任务快照读写时做structuredClone并维护一个activeCancellations集合用于取消传播。这意味着重启进程后任务即丢失——示例 README 的 Next steps 也明确指出生产场景应提供自定义TaskStore实现以持久化任务。流式场景的实现细节message/stream返回的流会先产出初始记录submitted/working随后在for await消费streamResult.textStream的每个 chunk 时把累积文本写入responseMessage.parts[0].text并产出working状态的更新帧最后产出completed终帧若中途被取消或出错则分别产出canceled或failed终帧见 server.ts 的 createMessageStreamGenerator。Hono 路由把该异步流包装为 SSEtext/event-stream响应帧格式为data: RSpayload\n\n见 packages/server-hono/src/routes/a2a.routes.ts。错误处理与 JSON-RPC 错误码协议错误统一由VoltA2AError表达packages/a2a-server/src/types.ts错误码对应A2AErrorCode常量types.ts错误码值含义PARSE_ERROR-32700JSON 解析失败INVALID_REQUEST-32600请求结构非法如未知 AgentMETHOD_NOT_FOUND-32601未知方法INVALID_PARAMS-32602参数非法如消息缺少 partsINTERNAL_ERROR-32603内部错误TASK_NOT_FOUND-32001任务不存在TASK_NOT_CANCELABLE-32002任务已处于终态不可取消UNSUPPORTED_OPERATION-32004不支持的操作任何处理器抛出的错误都会在handleRequest的 catch 中被normalizeErrorpackages/a2a-server/src/protocol.ts统一转换为符合 JSON-RPC 2.0 的错误响应error.code、error.message、error.data。Hono 层据此映射 HTTP 状态码错误响应返回 400未知 serverId 返回 404见 a2a.routes.ts。端到端验证冒烟测试脚本做了什么仓库为示例提供了完整的端到端冒烟测试脚本 examples/with-a2a-server/scripts/smoke-test.mjs。先在一个终端启动 dev server再在另一个终端运行pnpm --filter voltagent-example-with-a2a-server test:smoke脚本默认目标http://localhost:3141可用环境变量BASE_URL覆盖依次断言以下环节Agent Card 发现抓取/.well-known/supportagent/agent-card.json断言name supportagent、url是/a2a/supportagent的绝对地址、skills是数组message/send发送一条纯文本消息断言响应为 JSON-RPC 2.0、无error且任务状态为completedtasks/get用返回的task.id查询历史断言history.length 2用户消息 Agent 回复message/stream以Accept: text/event-stream发起流式请求逐帧解析data: RS...负载断言至少收到一个working状态更新帧且最终帧completed、最后一条历史消息role agent且文本非空tasks/cancel先发起一个长任务流在流打开onOpen时立即调用tasks/cancel断言取消传播到流最终状态为canceled或completed取消传播的单元级验证用内置的 stub Agent 与 stub 注册表直接驱动A2AServer.handleRequest在消费第一个流事件后调用tasks/cancel断言最终帧为canceled——这验证了AbortController注册/注销机制registerActiveOperation/abortActiveOperation见 server.ts确实能把取消信号传递给正在流式生成的 Agent。全部通过后脚本输出 All smoke tests passed。这说明该示例不仅是能跑而且覆盖了发现、同步、流式、查询、取消五大核心能力。进一步扩展多 Agent、流式与持久化示例 README 的 Next steps 给出了三条明确的扩展路径接入多个 Agent在a2aServers映射中继续添加条目即可。每个条目以 serverId 为键VoltAgent会为每个服务器注册独立的发现与 JSON-RPC 路由由于agentRegistry是全局共享的所有已注册的 Agent 都可被 A2A 服务器解析到。流式支持A2AServer已内置message/stream卡片中capabilities.streaming默认为true当 Agent 通过streamText产生增量输出时任务帧会逐段更新外部可以实时渲染。持久化任务默认的InMemoryTaskStore仅适合开发与演示。实现TaskStore接口load({ agentId, taskId })与save({ agentId, data })见 types.ts并作为taskStore注入依赖后即可把任务状态持久化到数据库实现跨重启的任务恢复。小结with-a2a-server示例用极少的代码展示了 VoltAgent 的完整 A2A 集成路径Agent createTool定义能力A2AServer暴露协议端点VoltAgent.a2aServers完成装配honoServer提供 HTTP 传输。配合.well-known发现文档、四种 JSON-RPC 方法与规范错误码外部任何遵循 A2A 的 Agent、IDE 或编排框架都能与 VoltAgent 生态互操作。如果你想深入底层可以从 packages/a2a-server/src/server.ts 的handleRequest开始沿着message/send→handleMessageSend→toVoltAgentMessage→agent.generateText的调用链逐行阅读想验证协议行为packages/a2a-server/src/server.spec.ts 与 packages/server-hono/src/routes/a2a.routes.spec.ts 是更系统的测试参考。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Thorium 浏览器指南Chromium 优化分支的选版、安装与进阶配置Thorium 浏览器指南Chromium 优化分支的选版、安装与进阶配置 Thorium 是一个以元素周期表 90 号元素命名的 Chromium 分支浏览桌面应用跨平台VoltAgent A2A Server 实战指南用 JSON-RPC 把 VoltAgent Agent 暴露给外部 AgentVoltAgent A2A Server 实战指南用 JSON RPC 把 VoltAgent Agent 暴露给外部 Agent 本篇技术指南围绕 vol人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音OmniRoute A2A Server 技术解析以 JSON-RPC 2.0 将 AI 网关暴露为 Agent-to-Agent 协议端点OmniRoute A2A Server 技术解析以 JSON RPC 2.0 将 AI 网关暴露为 Agent to Agent 协议端点 OmniRout后端API网关LLM 网关人工智能大模型MCP 服务桌面应用上一篇插件自动化测试框架markdown-preview.nvim的单元测试与集成测试实现下一篇phar-io/manifest云存储集成从S3读取PHAR文件元数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 VoltAgent 将 AI Agent 暴露为 A2A 服务：with-a2a-server 示例全解析
人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载VoltAgent 是一个开源的 TypeScript AI Agent 工程化框架而voltagent/a2a-server是它提供的Agent-to-AgentA2A协议服务端实现。本篇文章以仓库中的 with-a2a-server 示例 为主体完整讲解如何把一个普通的 VoltAgent Agent 通过 A2A 的 JSON-RPC 端点暴露给外部让其他 Agent、IDE 或编排框架可以通过.well-known发现它、通过/a2a/:serverId向它发送消息并管理任务。读完本文你将掌握 A2A 服务的装配方式、Agent Card 发现机制、四大 JSON-RPC 方法message/send、message/stream、tasks/get、tasks/cancel的调用与内部实现以及如何用冒烟测试端到端验证整个链路。什么是 A2A 协议为什么 VoltAgent 要支持它A2AAgent-to-Agent是一套让 AI Agent 之间相互发现、通信与协作的开放协议。与 MCPModel Context Protocol面向 Agent 与工具/数据源不同A2A 解决的是Agent 与 Agent之间的互操作问题一个 Agent 需要调用另一个 Agent 的能力而双方不需要共享同一套运行时。VoltAgent 在voltagent/a2a-server包中提供了这套协议的服务端实现。根据 packages/a2a-server/README.md 的说明该包把 VoltAgent 的 Agent 暴露到 A2A JSON-RPC 协议之上使其他 Agent、IDE 或编排框架可以通过定义良好的端点与之交互目前该包仍标记为ExperimentalAPI 在首个稳定版发布前可能发生变化。with-a2a-server示例展示的正是这一能力的落地形态一个极简 VoltAgent 项目包含一个SupportAgent和一个status工具通过voltagent/a2a-server与voltagent/server-hono的集成对外提供一个Agent Card发现文档说明该 Agent 的能力与端点地址一个JSON-RPC 消息端点接收符合 A2A 规范的请求并驱动内部 Agent 执行完整的任务生命周期提交、执行中、完成、失败、取消与内存任务存储。示例结构总览examples/with-a2a-server ├── src/ │ ├── agents/assistant.ts # 示例 Agent 定义含 status 工具 │ └── index.ts # VoltAgent 启动引导 A2A 服务器注册 ├── scripts/ │ └── smoke-test.mjs # 端到端冒烟测试脚本 ├── package.json ├── tsconfig.json └── README.md与仓库中其他示例一样package.json中定义了devtsx watch --env-file.env ./src、buildtsc、start、test:smoke等脚本并声明了对voltagent/a2a-server、voltagent/core、voltagent/internal、voltagent/logger、voltagent/server-hono、ai、zod的依赖具体可见 examples/with-a2a-server/package.json。环境准备与本地运行示例 README 明确给出了前置条件与运行方式完整继承如下前置条件Node.js 20pnpm环境变量OPENAI_API_KEY示例 Agent 使用 OpenAI 模型创建项目若尚未创建npm create voltagent-applatest -- --example with-a2a-server安装依赖并启动pnpm install pnpm --filter voltagent-example-with-a2a-server devdev脚本实际执行的是tsx watch --env-file.env ./src即监听模式启动并会加载项目根目录的.env文件OPENAI_API_KEY可放在其中。Hono 服务器监听在http://localhost:3141。从 Agent 定义到 A2A 暴露两个关键源码文件1. Agent 与工具定义examples/with-a2a-server/src/agents/assistant.ts 中定义了一个带status工具的SupportAgentimport { Agent, createTool } from voltagent/core; import { z } from zod; const statusTool createTool({ name: status, description: Return the current time in ISO format, parameters: z.object({}), async execute() { return { timestamp: new Date().toISOString(), }; }, }); export const assistant new Agent({ id: supportagent, name: SupportAgent, instructions: Reply with helpful answers and include the current time when relevant., model: openai/gpt-4o-mini, tools: [statusTool], }); export const tools { status: statusTool };要点Agent 的id为supportagent这个 id 会出现在后续的发现路径/.well-known/supportagent/agent-card.json和 JSON-RPC 路径/a2a/supportagent中工具参数使用zod的z.object({})描述说明该工具不需要额外参数execute()返回 ISO 格式时间戳用于演示 Agent 在回复中引用工具结果。2. A2A 服务器创建与 VoltAgent 装配examples/with-a2a-server/src/index.ts 是核心装配入口import { A2AServer } from voltagent/a2a-server; import { VoltAgent } from voltagent/core; import { createPinoLogger } from voltagent/logger; import { honoServer } from voltagent/server-hono; import { assistant } from ./agents/assistant; const logger createPinoLogger({ name: with-a2a-server, level: debug, }); const a2aServer new A2AServer({ name: SupportAgent, version: 0.1.0, description: Expose VoltAgent over the Agent-to-Agent protocol, }); new VoltAgent({ agents: { assistant, }, a2aServers: { supportAgent: a2aServer, }, server: honoServer({ port: 3141 }), logger, }); logger.info(VoltAgent A2A example is running on http://localhost:3141);装配逻辑分三步创建A2AServer通过构造参数声明服务器元信息name、version、description。A2AServerConfig还支持id、provider组织与官网 URL、agents直接在服务器上挂 Agent以及filterAgents按请求上下文过滤可暴露的 Agent详见 packages/a2a-server/src/types.ts在VoltAgent中登记通过a2aServers字段以serverId - A2AServer的形式注册键supportAgent就是路径中的 serverId挂载 Hono 服务器honoServer({ port: 3141 })提供 HTTP 传输层端口为 3141。从源码看VoltAgent在初始化时会对a2aServers逐项调用initializeA2AServerpackages/core/src/voltagent.ts其内部把实例注册进 A2A 注册表并注入依赖private initializeA2AServer(server: A2AServerLike | A2AServerFactory): A2AServerLike { const instance: A2AServerLike typeof server function ? server() : server; this.a2aServerRegistry.register(instance, this.getA2ADependencies()); this.a2aServers.add(instance); return instance; }这里A2AServerLike | A2AServerFactory意味着除了直接传实例还可以传一个返回实例的工厂函数便于懒加载。注入的依赖来自getA2ADependencies()packages/core/src/voltagent.ts即 VoltAgent 全局的agentRegistry——这让 A2A 服务器可以访问框架中注册的所有 Agent而不只是构造时传入的那几个。A2A 服务器的依赖契约定义在 packages/internal/src/a2a/types.tsagentRegistry.getAgent(id)与agentRegistry.getAllAgents()加上可选的taskStore。发现机制Agent Card 与.well-knownA2A 协议要求 Agent 通过标准位置暴露其能力描述文档Agent Card。示例中Hono 服务器启动后即可直接抓取发现文档curl http://localhost:3141/.well-known/supportagent/agent-card.json | jq返回的卡片通过url字段公布 JSON-RPC 端点{ url: http://localhost:3141/a2a/supportagent }这个路由的规范定义在 packages/server-core/src/routes/definitions.tsGET /.well-known/:serverId/agent-card.jsonOpenAPI 摘要为 Get A2A agent card。Hono 适配层在 packages/server-hono/src/routes/a2a.routes.ts 中实现先按serverId从注册表解析出 Agent再调用resolveAgentCard生成卡片找不到时返回 404参数非法时返回 400。卡片本身由buildAgentCard生成packages/a2a-server/src/adapters/agent.ts其结构对应 types.ts 中的 AgentCard包括字段说明示例值来源nameAgent 名称agent.id ?? agent.name即supportagentdescription描述默认取agent.purposeurlJSON-RPC 端点绝对地址基于请求 URL 解析/a2a/:serverIdprovider/version服务器元信息A2AServer配置capabilities能力声明默认streaming: true、pushNotifications: false、stateTransitionHistory: falsedefaultInputModes/defaultOutputModes输入输出模式均为[text]skills技能列表由agent.getTools()映射tags: [tool]一个值得注意的实现细节Agent 的每个工具会被自动映射为卡片中的一项skill外部 Agent 据此即可感知该 Agent 具备哪些能力。消息端点向 Agent 发送 JSON-RPC 请求拿到卡片中的url后即可向 JSON-RPC 端点发消息。示例 README 给出的请求体curl -X POST http://localhost:3141/a2a/supportagent \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: message/send, params: { message: { kind: message, role: user, messageId: msg-1, parts: [{ kind: text, text: What time is it? }] } } }协议层对请求的约束jsonrpc必须为2.0且method必须是字符串校验见 protocol.ts 的 isJsonRpcRequestparams.message必须存在、parts必须为非空数组当前实现只支持kind: text的纯文本消息部件其他类型会被拒绝校验见 server.ts 的 validateMessageSendParams消息可选携带taskId、contextId若缺失则由服务端生成randomUUID。服务端入口handleRequestpackages/a2a-server/src/server.ts是一个按method分发的 JSON-RPC 处理器支持四种方法方法作用返回message/send同步发送一条消息并等待执行完成TaskRecordmessage/stream以 SSE 流式发送消息逐段推送任务状态异步流逐帧TaskRecordtasks/get按任务 id 查询历史与状态TaskRecordtasks/cancel取消正在执行的任务TaskRecord状态为canceled请求的上下文userId、sessionId、metadata可通过context查询参数JSON 编码或请求体中的context字段传入由 Hono 路由解析合并见 packages/server-hono/src/routes/a2a.routes.ts最终在调用 Agent 时转换为conversationId、abortSignal、context等执行选项见 server.ts 的 buildAgentCallOptions。任务生命周期与消息映射A2A 的核心抽象是Task任务每次对话都对应一个任务任务有明确的状态机。TaskState定义在 packages/a2a-server/src/types.tssubmitted → working → completed ↘ failed ↘ canceled任务记录TaskRecordtypes.ts包含id、contextId、status状态 时间戳 关联消息、history完整消息历史、可选的artifacts与metadata。状态迁移由 packages/a2a-server/src/tasks.ts 中的纯函数完成createTaskRecord初始为submitted、appendMessage追加消息、updateLastMessage更新最后一条用于流式增量、transitionStatus迁移状态并打时间戳、ensureCancelable终态任务不可再取消、upsertArtifact按名字写入或合并产物。A2A 消息与 VoltAgent 内部消息的转换发生在适配层 packages/a2a-server/src/adapters/message.tstoVoltAgentMessage取第一条 text 部件作为内容把role: agent映射为assistantfromVoltAgentMessage反向映射回 A2A 消息并生成新的messageId。任务存储默认使用InMemoryTaskStorepackages/a2a-server/src/store.ts它以agentId::taskId为键在内存Map中保存任务快照读写时做structuredClone并维护一个activeCancellations集合用于取消传播。这意味着重启进程后任务即丢失——示例 README 的 Next steps 也明确指出生产场景应提供自定义TaskStore实现以持久化任务。流式场景的实现细节message/stream返回的流会先产出初始记录submitted/working随后在for await消费streamResult.textStream的每个 chunk 时把累积文本写入responseMessage.parts[0].text并产出working状态的更新帧最后产出completed终帧若中途被取消或出错则分别产出canceled或failed终帧见 server.ts 的 createMessageStreamGenerator。Hono 路由把该异步流包装为 SSEtext/event-stream响应帧格式为data: RSpayload\n\n见 packages/server-hono/src/routes/a2a.routes.ts。错误处理与 JSON-RPC 错误码协议错误统一由VoltA2AError表达packages/a2a-server/src/types.ts错误码对应A2AErrorCode常量types.ts错误码值含义PARSE_ERROR-32700JSON 解析失败INVALID_REQUEST-32600请求结构非法如未知 AgentMETHOD_NOT_FOUND-32601未知方法INVALID_PARAMS-32602参数非法如消息缺少 partsINTERNAL_ERROR-32603内部错误TASK_NOT_FOUND-32001任务不存在TASK_NOT_CANCELABLE-32002任务已处于终态不可取消UNSUPPORTED_OPERATION-32004不支持的操作任何处理器抛出的错误都会在handleRequest的 catch 中被normalizeErrorpackages/a2a-server/src/protocol.ts统一转换为符合 JSON-RPC 2.0 的错误响应error.code、error.message、error.data。Hono 层据此映射 HTTP 状态码错误响应返回 400未知 serverId 返回 404见 a2a.routes.ts。端到端验证冒烟测试脚本做了什么仓库为示例提供了完整的端到端冒烟测试脚本 examples/with-a2a-server/scripts/smoke-test.mjs。先在一个终端启动 dev server再在另一个终端运行pnpm --filter voltagent-example-with-a2a-server test:smoke脚本默认目标http://localhost:3141可用环境变量BASE_URL覆盖依次断言以下环节Agent Card 发现抓取/.well-known/supportagent/agent-card.json断言name supportagent、url是/a2a/supportagent的绝对地址、skills是数组message/send发送一条纯文本消息断言响应为 JSON-RPC 2.0、无error且任务状态为completedtasks/get用返回的task.id查询历史断言history.length 2用户消息 Agent 回复message/stream以Accept: text/event-stream发起流式请求逐帧解析data: RS...负载断言至少收到一个working状态更新帧且最终帧completed、最后一条历史消息role agent且文本非空tasks/cancel先发起一个长任务流在流打开onOpen时立即调用tasks/cancel断言取消传播到流最终状态为canceled或completed取消传播的单元级验证用内置的 stub Agent 与 stub 注册表直接驱动A2AServer.handleRequest在消费第一个流事件后调用tasks/cancel断言最终帧为canceled——这验证了AbortController注册/注销机制registerActiveOperation/abortActiveOperation见 server.ts确实能把取消信号传递给正在流式生成的 Agent。全部通过后脚本输出 All smoke tests passed。这说明该示例不仅是能跑而且覆盖了发现、同步、流式、查询、取消五大核心能力。进一步扩展多 Agent、流式与持久化示例 README 的 Next steps 给出了三条明确的扩展路径接入多个 Agent在a2aServers映射中继续添加条目即可。每个条目以 serverId 为键VoltAgent会为每个服务器注册独立的发现与 JSON-RPC 路由由于agentRegistry是全局共享的所有已注册的 Agent 都可被 A2A 服务器解析到。流式支持A2AServer已内置message/stream卡片中capabilities.streaming默认为true当 Agent 通过streamText产生增量输出时任务帧会逐段更新外部可以实时渲染。持久化任务默认的InMemoryTaskStore仅适合开发与演示。实现TaskStore接口load({ agentId, taskId })与save({ agentId, data })见 types.ts并作为taskStore注入依赖后即可把任务状态持久化到数据库实现跨重启的任务恢复。小结with-a2a-server示例用极少的代码展示了 VoltAgent 的完整 A2A 集成路径Agent createTool定义能力A2AServer暴露协议端点VoltAgent.a2aServers完成装配honoServer提供 HTTP 传输。配合.well-known发现文档、四种 JSON-RPC 方法与规范错误码外部任何遵循 A2A 的 Agent、IDE 或编排框架都能与 VoltAgent 生态互操作。如果你想深入底层可以从 packages/a2a-server/src/server.ts 的handleRequest开始沿着message/send→handleMessageSend→toVoltAgentMessage→agent.generateText的调用链逐行阅读想验证协议行为packages/a2a-server/src/server.spec.ts 与 packages/server-hono/src/routes/a2a.routes.spec.ts 是更系统的测试参考。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Thorium 浏览器指南Chromium 优化分支的选版、安装与进阶配置Thorium 浏览器指南Chromium 优化分支的选版、安装与进阶配置 Thorium 是一个以元素周期表 90 号元素命名的 Chromium 分支浏览桌面应用跨平台VoltAgent A2A Server 实战指南用 JSON-RPC 把 VoltAgent Agent 暴露给外部 AgentVoltAgent A2A Server 实战指南用 JSON RPC 把 VoltAgent Agent 暴露给外部 Agent 本篇技术指南围绕 vol人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音OmniRoute A2A Server 技术解析以 JSON-RPC 2.0 将 AI 网关暴露为 Agent-to-Agent 协议端点OmniRoute A2A Server 技术解析以 JSON RPC 2.0 将 AI 网关暴露为 Agent to Agent 协议端点 OmniRout后端API网关LLM 网关人工智能大模型MCP 服务桌面应用上一篇插件自动化测试框架markdown-preview.nvim的单元测试与集成测试实现下一篇phar-io/manifest云存储集成从S3读取PHAR文件元数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考