快速上手进程内 A2A 协议:Agent Card 与 JSON-RPC 端点实战指南

原创2026-11-02 12:41:451,689 阅读
文章标签:人工智能AI Agent后端

快速上手进程内 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 分布式运行时架构,Agent Card 与 JSON-RPC 位于 Agent Server 层

上图展示了 openJiuwen Agent 分布式运行时的整体分层:A2A 的 Agent Card 与 JSON-RPC 能力就位于 Agent Server → Agent-App 层,与 Init / Shutdown / Query / Interrupt 等生命周期操作并列,向下依托 Agent-Core,向上对接 Agent Gateway 🧩

A2A 协议是什么?为什么需要"进程内"形态

A2A 是 Agent 之间互相"发现 + 调用"的标准协议,核心只有两个动作:

  1. 发现:调用方 GET 你的 Agent Card(能力名片),知道你的端点和技能;
  2. 调用:调用方 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 委派、流式透传、中断恢复全链路即刻可验证。

登录后查看全文
agent-runtime-java