快速上手进程内 A2A 协议:Agent Card 与 JSON-RPC 端点实战指南
快速上手进程内 A2A 协议:Agent Card 与 JSON-RPC 端点实战指南
openJiuwen Agent Runtime Java 是 Agent 分布式运行时的 Java 实现,内置进程内 A2A(Agent-to-Agent)协议支持:无需独立网关,你的 Agent Service 既能通过标准 Agent Card 向外部声明"我是谁、会什么",也能通过 JSON-RPC(POST /a2a)接收来自其它 Agent 的调用,还可以委派远端 Agent 协作完成复杂任务。本文带你用最少配置跑通 A2A 全链路 🚀
上图展示了 openJiuwen Agent 分布式运行时的整体分层:A2A 的 Agent Card 与 JSON-RPC 能力就位于 Agent Server → Agent-App 层,与 Init / Shutdown / Query / Interrupt 等生命周期操作并列,向下依托 Agent-Core,向上对接 Agent Gateway 🧩
A2A 协议是什么?为什么需要"进程内"形态
A2A 是 Agent 之间互相"发现 + 调用"的标准协议,核心只有两个动作:
- 发现:调用方
GET你的 Agent Card(能力名片),知道你的端点和技能; - 调用:调用方
POST你的 JSON-RPC 端点,发送消息、查询任务、取消任务。
传统上 A2A 需要一个独立的平台级网关服务来做多 Agent 路由。而 openJiuwen 提供的是进程内 A2A:A2A Server 与你的 Agent 同进程运行,适合单 Agent 或单进程多实例直连场景,零平台依赖。两种形态的能力对照见 A2A 与平台边界。
Agent Card:一张名片告诉别人"我能做什么"
Agent Card 是一个 JSON 文档,描述你的 Agent 的名称、版本、能力与技能清单。openJiuwen 的 Card 完全由配置驱动(name 取自 spring.application.name,version 取自 openjiuwen.service.version,默认 0.1.4)。
标准路径为 GET /.well-known/agent-card.json,另外两个兼容路径 GET /.well-known/agent.json 与 GET /a2a/.well-known/agent-card.json 返回内容完全相同,方便不同 SDK 接入。Card 的端点实现位于 AgentCardController.java,端点常量定义在 A2AServicePaths.java。
Card 中包含的关键信息:
| 字段 | 来源 | 作用 |
|---|---|---|
name / version |
spring.application.name / openjiuwen.service.version |
标识你的 Agent |
capabilities |
a2a.is-streaming 等 |
声明是否支持 SSE 流式、推送通知等 |
skills[] |
a2a.skills 列表 |
每项含 id、description、tags、examples,供调用方选路 |
url(JSON-RPC 端点) |
a2a.public-url + a2a.json-rpc-path |
调用方的请求目标 |
💡
public-url未配置时,Card 中的 URL 会自动从当前请求推断,本地开发开箱即用。
JSON-RPC 端点:四个方法跑通全部交互
所有 A2A 业务请求都发到同一个入口:POST /a2a(带或不带尾部斜杠均可)。按 JSON-RPC 2.0 方法名分发,共四个方法:
| 方法 | 模式 | 说明 |
|---|---|---|
SendMessage |
非流式 | JSON 单次响应 |
SendStreamingMessage |
流式 | SSE(text/event-stream)实时推送过程 |
GetTask |
非流式 | 按 taskId 查询任务状态 |
| Cancel | — | 取消进行中的 Task |
流式响应的每条 SSE 事件长这样:
event:jsonrpc
data:{"jsonrpc":"2.0","id":1.0,"result":{...}}
请求字段会按下表映射到内部对话请求,其中 metadata 会一路透传到被委派的远端 Agent,适合跨 Agent 传上下文:
| A2A 字段 | 对话请求 |
|---|---|
message.contextId |
conversationId |
message.taskId / messageId |
透传(taskId 非空表示续接已有 Task) |
message.role / parts[].text |
消息内容 |
params.metadata |
metadata |
控制器入口与分发逻辑见 A2aJsonRpcController.java,A2A 自动装配(基于 org.a2aproject.sdk:1.0.0.Final)见 A2AAutoConfiguration.java。
最小配置:YAML 里写几行,A2A Server 就起来了
引入 agent-service-app 后 A2A SDK 由传递依赖提供,业务 POM 一般无需重复声明。只需这样配置:
spring:
application:
name: "My Agent"
openjiuwen:
service:
version: "1.0.0"
a2a:
agent-description: "A helpful assistant"
is-streaming: true
json-rpc-path: "/a2a"
task-completion-timeout-seconds: 300
skills:
- id: search
name: Search
description: Search for information
配置完成后:
GET /.well-known/agent-card.json返回你的能力名片;POST /a2a即可接收SendMessage等请求并执行你的 Agent。
完整配置项(含 TaskStore Redis 持久化、Callback 白名单等)参见官方文档 A2A 开发指导。
四 Agent 委派实战:A2A 示例与烟测脚本
仓库自带一个非常直观的 A2A 多 Agent 示例:四个独立进程协作,所有请求只发给 Agent A。
| Agent | 端口 | 职责 |
|---|---|---|
| Agent A | 18090 | 入口 ReAct Agent,把用户请求转交给 Agent B |
| Agent B | 18091 | 本地计算工具,或继续转交餐饮/费用请求给 C / D |
| Agent C | 18092 | DeepAgent,返回餐饮推荐前请求用户确认 |
| Agent D | 18093 | WorkflowAgent,费用政策检查 + 自动/人工审批 + LLM 报告 |
A 委派 B 的配置示例(来自 application-a2a-agent-a.yml):
openjiuwen:
service:
a2a:
is-streaming: true
remote-agents:
- name: agentb
url: http://localhost:18091/
timeout-seconds: 300
streaming: true
启动时 Runtime 会探测远端 Agent 的 Card(失败约 30s 自动重试),当 Agent 在工具中触发 a2a_delegate 中断时,运行时按 remote-agents 目录找到目标发起调用,并把远端结果回喂给模型继续对话。
想一键验证?运行 smoke 脚本即可自动拉起四个 Agent、检查健康与 Card,并跑完全部端到端场景:
bash service/agent-service-demo/example/a2a/smoke-a2a.sh
脚本覆盖的计算确认、流式确认、非流式审批等 5 个场景说明见 A2A Multi-Agent 示例 README。
流式透传:两个条件同时满足才"透传"
委派时远端过程事件是否实时投影给最终客户端,规则简单但容易踩坑:路由配置 streaming: true 与 上游请求本身是流式(SendStreamingMessage 或 REST stream=true),两者缺一不可,且该规则逐跳传递(A 流式调 B,不代表 B 一定流式调 C)。细节见 出站委派与流式规则。
中断与恢复:INPUT_REQUIRED 不用手动维护状态
当远端 Agent 需要用户补充输入时会返回 INPUT_REQUIRED 状态。运行时会自动保存待恢复状态并向客户端抛出统一中断;下一轮同一 contextId(即 conversationId)的请求会自动续接,无需你自己维护任何恢复状态 ✅
Task 状态机:你的任务走到哪一步了
A2A 中的任务遵循固定状态流转,客户端可用 GetTask 随时轮询:
SUBMITTED → WORKING → COMPLETED / FAILED / INPUT_REQUIRED
- TaskStore 默认使用内存(InMemory);配置
openjiuwen.service.middleware.checkpointer.type: redis后复用同一 Redis 连接持久化 Task,进程重启不丢任务。 - 注意区分 A2A Cancel(JSON-RPC 方法,停止当前 A2A 流)与 Lifecycle interrupt(运行时生命周期中断,无 REST 入口),二者语义不同,详见 生命周期与探针。
进阶与延伸阅读
- 进程内 A2A 与 HTTP
/v1/query共用同一 Orchestrator,两个入口可以并存,按需选择对接方式; - 一个 Runtime 进程注册多个 AgentHandler(多实例 Card、实例级
remote-agents覆盖)见 多 Agent 实例托管; - 配置、端点、字段映射的完整权威文档:A2A 开发指导;
- 平台级 A2A 服务的边界与规划:A2A 与平台边界。
一句话总结:写几行 YAML 声明技能,openJiuwen 就帮你把 Agent Card 和 JSON-RPC 端点全部就位;配合 remote-agents 目录与 smoke 脚本,多 Agent 委派、流式透传、中断恢复全链路即刻可验证。
