简体中文

English

简体中文

English

A2A —— Agent-to-Agent 协作 ​

商业版本： A2A 协作需要商业授权。单实例 Baize 及其网页控制台仍然包含在 Baize Core 中。

A2A 让多个 Baize 实例经 HTTPS P2P 直接协作——没有中心消息服务器，消息与任务委托直达对端 Agent，每个实例保持完全独立。

独立模式（standalone）是默认且完整的运行方式；A2A 是显式启用的可选能力。

架构 ​

A2A Agent 直接协作网络
Agent 之间直接建立 HTTPS P2P 通道；Admin Workspace 只负责目录、准入、在线与审计，不进入业务消息路径。

组件 ​

组件职责
@baize-ai/baize-a2anpm 渠道包，装在每个启用实例：HTTPS server、注册/心跳客户端、任务 worker、baize a2a CLI
@baize-ai/baize-admin-workspace独立控制面（npm 包 + Docker 镜像 + Ant Design Pro 控制台）：准入审批、在线状态、审计、基于 Card 的发现——不进消息路径

硬性边界：

  • admin-workspace 不创建 Agent、不转发消息、不保存任务正文、不维护业务描述——业务事实存于 Agent Card，由每个 Agent 自报。
  • baize-a2a 是唯一需要装在每个参与实例上的组件。不装 = standalone 模式。

配置 A2A 集群 ​

A2A 与 Admin Workspace 都属于商业版本能力，需要先取得商业授权和对应组件包。单实例模式无需执行以下步骤。

第一步：获取并安装 A2A 组件 ​

取得商业授权后，获取 @baize-ai/baize-a2a 渠道包，并在每个需要参与协作的 Baize 实例中安装：

bash
baize add @baize-ai/baize-a2a

A2A 模块安装与集群模式

第二步：部署 Admin Workspace ​

获取商业版 @baize-ai/baize-admin-workspace 组件及部署产物，在独立服务中启动 Admin Workspace。Docker 部署示例：

bash
docker run -d --name baize-admin -p 8080:8080 \
  -v baize-admin-data:/data \
  -e BAIZE_ADMIN_TOKEN='<初始口令>' \
  baize-admin-workspace

确保 Admin Workspace 已启动并可访问。本文示例使用 http://a2a-admin:8080 作为 Admin Workspace 部署地址；实际环境请替换为 Agent 能访问的地址。

第三步：切换集群模式并保存连接配置 ​

打开 Web Console → A2A 互联，在运行模式中切换为“集群”：

  1. 在模块安装区域确认 baize-a2a 已安装。
  2. 确认 Admin Workspace 已部署并正常运行。
  3. 在“连接配置”中填写 Admin Workspace 地址，例如 http://a2a-admin:8080。
  4. 填写本 Agent 对外可访问的地址，例如 https://agent-a:8443。
  5. https://agent-a:8443 通常按当前环境默认值即可，不要填写仅本机可访问的 localhost 或容器内部地址。
  6. 点击“保存配置”，等待身份注册、心跳和健康状态变为正常。
text
Admin Workspace：http://a2a-admin:8080
Agent advertise URL： https://agent-a:8443

保存成功后，状态应显示为“集群 · 在线”，并能看到 daemon 健康、注册状态和最近心跳。

第四步：编辑 Agent Card ​

状态正常后，在 A2A 页面打开“编辑名片”。Agent Card 是其他 Agent 认识本 Agent 的唯一业务入口，决定它能被如何发现和调用：

  1. 填写清晰的名称，例如“客户成功 Agent”。
  2. 用一两句话说明它负责什么、适合处理什么任务。
  3. 在 Skills 列表中，从已安装的 Skills 中勾选允许对外开放的能力。
  4. 只暴露确实可以被远程调用的 Skills，不要把内部管理、凭据处理或实验性 Skill 发布出去。
  5. 保存后等待 Card 热更新和 Admin Workspace 同步。

编辑 Agent Card 与选择对外 Skills

其他 Agent 会通过 Card 的名称、描述和 Skills 发现本 Agent；因此 Card 不是展示文案，而是协作网络中的能力声明。

核心概念 ​

  • Agent Card 是唯一业务事实源 —— 每个 agent 在 GET /.well-known/baize-agent.json 自报 name / description / skills；admin 不维护业务描述，只管准入、在线、审计与发现。
  • 接收方授权自治 —— 每个 agent 自己决定接受谁的调用（config.json 的 authz：默认 open，或 allowlist）。被拒调用返回 403 并记审计。
  • 基于 Card 的发现 —— 经 admin 目录按 Card 的 name/description/skills 文本匹配，或按 skill id 精确匹配发现 peer。

注册生命周期 ​

A2A Agent 注册生命周期
从身份生成到发现与直接调用，控制面只在注册生命周期中提供治理信号。
  1. 注册 —— 首启生成身份与密钥对，启动 HTTPS 服务并发布 Agent Card，向 admin 发注册请求（nonce + 时间戳 + 公钥 + 签名）。
  2. 验证 —— admin 验证签名并回连 challenge（SSRF 防护：网段限制、禁回环/云元数据、一次性 nonce）。
  3. 审批 —— pending → 管理员审批（仅批准/拒绝 + 备注）→ 签发每 Agent 独立 JWT（RS256，12h 有效）→ approved。
  4. 心跳 —— 每 30s 上报（agent/instance/boot id、Card 版本/hash、三维在线状态、通信总线待处理数、task_runs 队列数、Runtime 健康摘要）；admin 每 60s 主动探测（SSRF 防护，连续 2 败 → offline）并同步 Card 快照。
  5. 发现与调用 —— 审批通过的 agent 可被发现，并经 HTTPS P2P 直接调用。

快速上手 ​

bash
baize add @baize-ai/baize-a2a              # 安装渠道
baize a2a enable --admin <url> --advertise <https://your-agent.example.com>
# → 自注册 → 管理员审批 → 签发 JWT → 心跳（30s）→ 可发现
baize a2a search <query>                   # 经 admin 目录发现 agent
baize a2a task <peer> <skill> "<instruction>"  # 委托任务（默认同步等待）

CLI ​

命令用途
status本实例状态：enabled / agent_id / 注册状态 / advertise_url
enable --admin <url> --advertise <url>启用 A2A 并向 admin 注册
disable关闭（已接受任务继续执行）
peer list本地缓存 peer
search <query>经 admin 目录发现 agent
card <id>Agent Card 详情
session-summary当前可用 peer 摘要
send <peer> <text>普通消息（不等待回复）
task <peer> <skill> "<instruction>"委托任务；默认同步等待终态（--async 只拿 task_id）
task status <id> / task cancel <id>查询 / 取消委托任务

协议 ​

  • 传输：HTTPS 强制（内网也 TLS），UTF-8 JSON，Content-Type: application/json。不接受 multipart/二进制/文件上传——A2A 只传文本与 URL。
  • 普通消息（baize 扩展，对话式语义）：POST /a2a/v1/messages → 202 { request_id, status: "accepted" }。不等待回复；接收方经通信总线异步回复。幂等键 (caller_agent_id, request_id)。
  • 任务委托（标准 A2A 语义）：POST /a2a/v1/tasks（tasks/send）→ 202 { task_id, status: "queued" }；GET /a2a/v1/tasks/{id}（tasks/get）；POST /a2a/v1/tasks/{id}/cancel（tasks/cancel）。同 request_id 重试返回同一 task_id。
  • 状态机：queued → running → completed | failed | canceled，含 input_required（补充输入恢复任务，不新建 task_runs）、cancel_requested 与安全点取消。
A2A 任务状态流
任务由接收方自治推进，补充输入、取消和终态都沿同一条可追踪链路流转。
  • 限额：最大委托 hop 4（超限 409 HOP_LIMIT）；消息体 256KB（JSON 深度 ≤ 32，字段 ≤ 128）；接收方默认并发 8 queued/running（超限 503 NOT_ACCEPTING，管理台可调）。

名片编辑与调用授权 ​

网页控制台 A2A 页可编辑本实例 Agent Card——名称、描述，以及从已安装 SKILL.md 列表勾选 Skills（frontmatter 自动提取）。保存后 Card 秒级热更新，admin 探测同步快照；A2A 未启用也可先编辑预填名片。

同页配置「调用授权」：默认 open + 黑名单，或 allowlist——被拒调用返回 403 并记审计。

凭证轮换 ​

每个 agent 持有 admin 签发的独立 JWT（RS256，12h 有效，凭证独立）。agent 在过期前自动刷新；admin 轮换后 agent 60s 内自动重取凭证（吊销检测 + 强制恢复）。轮换只吊销目标 agent 的凭证并以当前 key 重签——全局签名 key 不变，单 agent 轮换不影响其他 agent。

安全模型 ​

  • 同企业内网请求也不默认可信；每个 Agent 独立执行主体。
  • 无共享万能 token：每 Agent 独立 JWT、接收方离线验签、HTTPS 强制；接收方授权是默认姿态。
  • 凭证不传播：B 用自己的飞书/GitHub 身份执行，不继承 A 的 token；无权限 → input_required，不传文件绕过 ACL。
  • 重放/幂等/循环防护：JWT 时效 + created_at/expires_at 校验 + 持久幂等 + trace（root/parent/hop，上限 4）。
  • 不可信输入：远端 instruction 不覆盖本地系统规则、不自动批准工具权限；限流限长；日志不记录 token/文档正文/完整 prompt。
  • admin 侧：登录限流（5 次/分 + 指数退避 + Retry-After）、周期 SSRF 防护探测、agent 视角凭证元数据裁剪、JSON 深度/字段校验、元数据级审计。

可靠性 ​

  • at-least-once 传输 + 接收方幂等（不宣称 exactly-once）。
  • accepted / delivered / task_runs completed 三个不同阶段。
  • 重启恢复：inbox/outbox/task_runs 本地持久化；非终态 task_runs 由 worker 重启后恢复。
  • 完成通知为可选优化；调用方始终可轮询权威状态。