A2A 协议
A2A（Agent-to-Agent）是平台与外部 Agent 之间的标准通信方式。平台是 Client，外部 Agent 是 Server。
职责
| 负责 | 不负责 |
|---|---|
| 调用外部 Agent 的 HTTP 端点 | 管理长连接（agent-gateway） |
| 任务提交与状态轮询 | 匹配 Agent（agent-matching） |
| 对话消息传递 | Agent 内部执行 |
| 对外暴露平台自身的 AgentCard 与 Skill | 工作流编排（workflow） |
平台端点
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/a2a/agent-card | 平台自身的 AgentCard |
| GET | /api/a2a/agent-card/:agentId | 指定 Agent 的 AgentCard |
| GET | /api/a2a/skills | 所有 Skill 的 A2A 格式 |
| GET | /api/a2a/adapter.js | 接入适配脚本 |
/api/a2a/skills 是外部 Agent 初始化能力的入口：Agent 下载 Skill 定义后，据此实现本地服务。
外部 Agent 需要实现的端点
| 方法 | 路径 | 必需 | 说明 |
|---|---|---|---|
| POST | /message:send | ✅ | 接收任务或对话消息 |
| GET | /tasks/:id | 推荐 | 查询任务状态 |
| GET | /health | 可选 | 健康检查 |
交互流程
1. 注册前获取能力
Agent 平台
│ GET /api/a2a/skills │
│────────────────────────────▶│
│ ← [{ skill_id, input_schema, output_schema, ... }]
│ │
│ 本地初始化能力 │2. 注册
Agent 平台
│ POST /api/agent-profiles/register
│ { agentId, skillIds, a2aEndpoint, ... }
│────────────────────────────▶│
│ ← { profile, apiKey } │3. 任务执行
平台 Agent
│ POST /message:send │
│ { message: { parts: [...] },
│ configuration: {
│ returnImmediately: true } }
│────────────────────────────▶│
│ ← { task: { id, status: SUBMITTED } }
│ │
│ GET /tasks/{id} │
│────────────────────────────▶│
│ ← { task: { status: WORKING } }
│ │
│ GET /tasks/{id} │
│────────────────────────────▶│
│ ← { task: { status: COMPLETED,
│ artifacts: [...] } } │4. 对话（INPUT_REQUIRED）
平台 → Agent: message:send
Agent → 平台: { status: INPUT_REQUIRED, message: { text: "目标市场？" } }
平台 → 用户: 展示问题
用户 → 平台: "德国"
平台 → Agent: message:send（同一 task 上下文）
Agent → 平台: { status: COMPLETED }任务状态
| 状态 | 平台行为 |
|---|---|
SUBMITTED | 开始轮询 |
WORKING | 继续等待 |
INPUT_REQUIRED | 转交用户 |
COMPLETED | 读取 artifacts，校验 Schema |
FAILED | 节点失败，可重试 |
CANCELED | 终止 |
降级策略
A2AClientService.executeTask()
├─ 成功 → 使用结果
└─ 失败（超时 / 连接错误 / 非 2xx）
└─ AgentGatewayService.pushTask()
├─ 在线 → WebSocket
└─ 离线 → offline_tasks降级会记录在节点元数据中，便于排查。
参考实现
bash
npx ts-node scripts/a2a-server-reference.ts环境变量：
bash
A2A_PORT=3001
AGENT_ID=my-agent
AGENT_NAME="My Compliance Agent"
SKILL_ID=ce-certification-review-v1
DOMAIN=compliance
SUBDOMAIN=ce_certification
PLATFORM_URL=http://localhost:3000启动后自动注册并等待任务。
边界与限制
| 限制 | 说明 |
|---|---|
| 协议兼容 | 按 A2A 风格实现，未做完整规范兼容 |
| 认证 | 依赖端点自身校验；平台侧使用 API Key / 注册信息 |
| 幂等 | 平台可能重试，Agent 需按 taskId 幂等 |
| 流式 | message:send 以轮询为主，未强制 SSE |
| 多实例 | 同一 Skill 可注册多个 Agent，由匹配分数选择 |
源码位置
libs/modules/src/a2a/
├── a2a-client.service.ts
└── a2a.controller.ts
scripts/a2a-server-reference.ts # 参考 Agent