ChainlessChain 文档

主题

A2A 协议 (a2a) ​

Headless 命令 — 不依赖桌面 GUI，直接使用核心包运行。适用于服务器、CI/CD、容器化等无桌面环境。

核心特性 ​

  • 🤖 Agent Card 注册: 声明式智能体能力描述卡片
  • 🔎 能力发现: 基于关键词和能力标签的智能体搜索
  • 📨 任务生命周期: submitted → working → completed / failed / input-required 完整状态机
  • 🤝 能力协商: 任务分配前的能力匹配与协商机制
  • 📡 订阅系统: 实时监听任务状态变更通知
  • 🌐 去中心化: 基于本地注册表的 P2P 式智能体发现

概述 ​

ChainlessChain CLI 实现了 A2A（Agent-to-Agent）协议，为智能体间通信提供标准化接口。每个智能体通过注册 Agent Card 声明自己的名称、能力、技能和端点 URL。其他智能体可通过 discover 命令发现具有特定能力的伙伴，并通过 submit 发送任务。

任务遵循标准状态机：提交后进入 submitted 状态，执行中转为 working，最终进入 completed（成功）、failed（失败）或 input-required（需要额外输入）。智能体可通过 negotiate 命令在任务分配前验证目标智能体是否具备所需能力。

命令参考 ​

a2a register — 注册 Agent Card ​

bash
chainlesschain a2a register <name>
chainlesschain a2a register "code-reviewer" --description "Code review agent" --capabilities "review,lint,test"
chainlesschain a2a register "translator" --url "http://localhost:8080" --skills "translate,summarize"
chainlesschain a2a register "analyzer" --json

注册一个新的 Agent Card，声明智能体的名称、描述、能力列表、技能列表和端点 URL。

a2a discover — 发现智能体 ​

bash
chainlesschain a2a discover
chainlesschain a2a discover --capability "review"         # 按能力搜索
chainlesschain a2a discover --name "translator" --json    # 按名称搜索

搜索已注册的智能体。支持按能力、名称、技能等条件过滤。

a2a submit — 提交任务 ​

bash
chainlesschain a2a submit <agent-id> <message>
chainlesschain a2a submit agent-001 "Review this code" --json

向指定智能体提交一个任务，任务进入 submitted 状态等待处理。

a2a status — 查看任务状态 ​

bash
chainlesschain a2a status <task-id>
chainlesschain a2a status <id> --json

查看任务的当前状态及详细信息（提交时间、处理智能体、结果等）。

a2a complete — 完成任务 ​

bash
chainlesschain a2a complete <task-id> --result "Review passed, 2 suggestions"
chainlesschain a2a complete <id> --result "Done" --json

将任务标记为已完成，附带结果信息。

a2a fail — 标记任务失败 ​

bash
chainlesschain a2a fail <task-id> --reason "Unsupported language"
chainlesschain a2a fail <id> --reason "Timeout" --json

将任务标记为失败，附带失败原因。

a2a peers — 列出对等节点 ​

bash
chainlesschain a2a peers
chainlesschain a2a peers --json

列出所有已注册的 A2A 对等节点及其状态。

a2a cards — 列出所有 Agent Card ​

bash
chainlesschain a2a cards
chainlesschain a2a cards --json

显示所有已注册 Agent Card 的完整信息。

a2a negotiate — 能力协商 ​

bash
chainlesschain a2a negotiate <agent-id> --capability "code-review"
chainlesschain a2a negotiate <id> --capability "translate" --json

与指定智能体进行能力协商，确认其是否具备所需能力并获取协商结果。

任务状态机 ​

  submitted ──→ working ──→ completed
                  │
                  ├──→ failed
                  │
                  └──→ input-required ──→ working

数据库表 ​

表名说明
a2a_agent_cardsAgent Card 注册表（名称、描述、能力、技能、URL、状态）
a2a_tasks任务记录（状态、提交者、处理者、消息、结果、时间戳）

系统架构 ​

用户命令 → a2a.js (Commander) → a2a-protocol.js
                                      │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
             Card 注册表        任务调度器        能力协商器
          (agent_cards)       (状态机驱动)     (匹配+验证)
                    │                │                │
                    ▼                ▼                ▼
           a2a_agent_cards     a2a_tasks 表     协商结果缓存

配置参考 ​

bash
chainlesschain a2a <subcommand> [options]

子命令:
  register <name>         注册 Agent Card
  discover                发现已注册智能体
  submit <agent-id> <msg> 向 Agent 提交任务
  status <task-id>        查看任务状态
  complete <task-id>      将任务标记为完成
  fail <task-id>          将任务标记为失败
  peers                   列出 A2A 对等节点
  cards                   列出所有 Agent Card
  negotiate <agent-id>    能力协商

常用选项:
  --description <text>    Agent 描述
  --capabilities <list>   能力列表（JSON 数组或逗号分隔）
  --skills <list>         技能列表
  --url <endpoint>        Agent 端点 URL
  --capability <name>     按能力过滤/协商的能力名
  --result <data>         complete 任务的结果
  --reason <text>         fail 任务的失败原因
  --json                  以 JSON 格式输出

存储位置: SQLite a2a_agent_cards / a2a_tasks 表，位于系统统一数据库。

性能指标 ​

操作目标实际状态
Agent 注册< 50ms~25ms✅
能力发现（100 Agent）< 200ms~80ms✅
任务提交< 50ms~30ms✅
任务状态查询< 30ms~15ms✅
能力协商（双向）< 100ms~45ms✅
Agent Card 列表（100 条）< 150ms~60ms✅

测试覆盖率 ​

✅ a2a.test.js  - 覆盖 a2a CLI 的主要路径
  ├── 参数解析 / 选项验证（register/submit/discover 等）
  ├── 正常路径（Agent 注册→发现→任务生命周期）
  ├── 错误处理 / 边界情况（Agent 不存在、状态机非法跳转）
  └── JSON 输出格式

关键文件 ​

  • packages/cli/src/commands/a2a.js — 命令实现
  • packages/cli/src/lib/a2a-protocol.js — A2A 协议库

使用示例 ​

场景 1：注册 Agent 并发现协作者 ​

bash
# 注册一个代码审查 Agent
chainlesschain a2a register \
  --name "code-reviewer" \
  --description "专注代码质量和安全审查" \
  --capabilities '["code-review","security-audit"]' \
  --skills '["javascript","python","go"]'

# 发现有代码审查能力的 Agent
chainlesschain a2a discover --capability code-review

# 查看所有已注册的 Agent Card
chainlesschain a2a cards --json

场景 2：任务分发与跟踪 ​

bash
# 向指定 Agent 提交任务
chainlesschain a2a submit <agent-id> \
  "审查 src/lib/auth.js 的安全漏洞"

# 查看任务状态和历史
chainlesschain a2a status <task-id> --json

# Agent 完成任务后标记完成
chainlesschain a2a complete <task-id> \
  --output '{"issues":3,"severity":"medium"}'

# 任务失败时标记失败
chainlesschain a2a fail <task-id> --error "Agent 超时"

场景 3：能力协商 ​

bash
# 协商两个 Agent 之间的共同能力
chainlesschain a2a negotiate <agent-a-id> <agent-b-id>

# 查看所有活跃的 peer Agent
chainlesschain a2a peers

故障排查 ​

任务状态异常 ​

症状可能原因解决方案
任务一直停在 "submitted"目标 Agent 未消费任务检查 Agent 是否在线：a2a peers
"Agent not found" 错误Agent Card 未注册或已删除使用 a2a cards 查看可用 Agent
任务提交后无响应能力不匹配先 a2a negotiate 确认能力兼容性
任务状态查询返回空task-id 格式错误使用 a2a status --json 确认正确的任务 ID

常见错误 ​

bash
# 错误: "Agent not found"
# 原因: 指定的 agent-id 不存在
# 修复: 先注册或搜索 Agent
chainlesschain a2a discover --capability code-review

# 错误: "Task cannot transition from completed to working"
# 原因: 已完成的任务不能重新进入 working 状态
# 修复: 提交新任务
chainlesschain a2a submit <agent-id> "new task"

# 错误: "No compatible capabilities"
# 原因: 两个 Agent 没有共同能力
# 修复: 检查双方能力注册
chainlesschain a2a cards --json

安全考虑 ​

  • Agent 身份验证: Agent Card 支持 auth_type 字段（none/api-key/oauth），生产环境建议配置认证
  • 任务隔离: 每个任务有独立的输入/输出/历史记录，Agent 之间的任务数据相互隔离
  • 能力声明验证: 注册时的 capabilities 和 skills 会被存储和索引，其他 Agent 可据此验证能力真实性
  • 状态机约束: 任务状态严格按照 submitted→working→completed/failed 的状态机流转，防止非法状态跳转
  • 数据最小化: 任务输出仅包含必要信息，避免在 Agent 间传递敏感数据

相关文档 ​

基于 MIT 许可发布

Copyright © 2024-2026 ChainlessChain Team