A2A协议集成实战：用sprix-sage-router从Agent Card到传输中立ExecutionPlan
【免费下载链接】sprix-sage-routerSprix AI at 屿智同行 — state-aware SELF/COLLABORATE/HANDOFF routing for A2A agent networks.项目地址: https://gitcode.com/gh_mirrors/sp/sprix-sage-router
sprix-sage-router是 Sprix AI 开源的状态感知智能体路由器，专为A2A（Agent2Agent）协议网络设计。它能在任务执行中途，替你在SELF（自己干）/ COLLABORATE（协作）/ HANDOFF（交接）三种模式间做出可审计的决策，再把 A2A 的Agent Card一步步转换成一份传输中立的 ExecutionPlan（执行计划）。
👉 本文是一份「从 0 到 1」的实战指南：不堆砌代码，只讲清楚每一步为什么这么做、产出什么，帮你快速把 sprix-sage-router 接入自己的 A2A 系统。
🧭 1. 先搞清楚：sprix-sage-router 到底解决什么问题？
Agent 发现（discovery）只能告诉你「有哪些智能体存在」，却回答不了执行阶段最棘手的问题：
任务已经开始跑了，接下来该让谁和谁一起干活？
sprix-sage-router 就是插在A2A 发现与任务执行之间的决策层。它评估三条路由，并在同一个可审计目标下选出最优：
| 路由模式 | 所有权归属 | 最适合的场景 |
|---|---|---|
| SELF | 当前智能体（incumbent） | 现有能力和上下文已足够 |
| COLLABORATE | 当前智能体保留所有权 | 一支互补团队补齐缺失能力 |
| HANDOFF | 某个同行完全接管 | 专家优势 > 上下文迁移损失 |
💡 A2A 负责「发现 + 传输 + 任务生命周期」，sprix-sage-router 负责「选谁、用哪种模式、为什么」。两者互补，不重叠。
🎯 2. 核心链路：Agent Card → Profile → 路由 → ExecutionPlan
sprix-sage-router 的 A2A 集成把整条链路拆成 5 个清晰阶段（这也是官方集成指南的推荐做法）：
认证过的 Agent Card │ ▼ 本地证据 + 策略（技能分 / 成本 / 延迟 / 权限） │ ▼ SAGE route_with_trace（可审计路由） │ ▼ 传输中立 ExecutionPlan │ ▼ A2A 客户端 + 任务生命周期- 认证并发现 Agent Card（身份、签名、安全校验都在 SAGE 之外完成）
- 结合本地证据：把卡片声明的技能，与本地校准的能力、成本、延迟、权限证据合并
- 调用
route_with_trace：拿到选中路由、可行备选、以及被排除智能体的原因 - 转换为
ExecutionPlan：一份不含凭据、不发起网络请求的传输中立计划 - 交给 A2A 客户端分发：保留依赖与取消语义，执行后把最强证据回喂给
record_outcome
📖 完整说明见 docs/INTEGRATION.md。
🛡️ 3. Agent Card 安全规范化：为什么不能直接信「营销文案」？
这是新手最容易踩的坑。Agent Card 里的技能描述常常是营销语言，并不等于真实能力。
sprix-sage-router 在 sprix_a2a.py 里的profile_from_agent_card采用安全设计：
- ✅ 只接受卡片真实声明过的技能 ID对应的分数
- ✅ 强制由调用方提供数值型的能力、成本、延迟证据
- ✅刻意不从技能描述或营销文案推断信任度
- ✅ 未知技能、空技能列表等异常会直接报错，而不是静默忽略
返回的AgentCardProfile保留卡片元数据用于审计日志，并通过.agent暴露一个经过校验的 SAGEAgent。
💬 一句话：声明的技能是「广告」，本地证据才是「验货报告」，两者必须对得上。
🔀 4. 路由决策：route_with_trace给出可审计的三条路
调用route_with_trace后，你会拿到：
- 选中的路由（模式 + 智能体 + 角色分配 + 通信拓扑）
- 可行的备选方案（按效用排序）
- 被排除智能体的明确原因（权限不足、超预算、无法满足截止时间等）
这种「审计痕迹」设计意味着：你不仅知道选了谁，还知道为什么没选别人——这正是生产环境做合规和排障时最需要的。
📦 5. 生成传输中立 ExecutionPlan：一份「只决策、不发请求」的计划
execution_plan函数把路由结果转成ExecutionPlan，包含：
| 字段 | 含义 |
|---|---|
owner_agent_id | 谁拥有所有权 |
executor_agent_ids | 实际执行者 |
steps | 每个需求的分配 + 依赖 + 权重 + 最低门槛 |
communication_edges | 智能体间通信拓扑 |
estimated_cost/estimated_latency_ms | 成本与关键路径延迟估算 |
rationale | 人类可读的路由理由 |
⚠️关键边界：ExecutionPlan不含任何凭据、不发起任何网络请求。真正的传输职责（认证、流式、轮询、取消、超时、幂等重试、人工审批、产物评估）仍由你的A2A 客户端负责。
💡不要把「路由成功」当成「任务执行成功」——这是集成时最容易被误解的一点。
🚀 6. 最快上手：3 步跑通 A2A 执行计划
参考实现只需Python 3.10+，且零运行时依赖。
① 克隆仓库
git clone https://gitcode.com/gh_mirrors/sp/sprix-sage-router.git cd sprix-sage-router② 跑官方端到端示例
python -m examples.a2a_execution_plan它会把「路由审计痕迹 + 执行计划」一起打印成 JSON，你能直接看到从 Agent Card 到 ExecutionPlan 的完整形态。
③（可选）跑演示与验证套件
python demo.py python -m unittest -v📖 示例说明见 examples/README.md；A2A 规划与失败恢复两个可运行示例分别在 examples/a2a_execution_plan.py 和 examples/replan_and_persist.py。
🔁 7. 进阶：失败重规划与学习状态持久化
真实世界里任务会失败。sprix-sage-router 内置了进度感知重规划：
- 当前执行者失败时，路由器会把「已完成节点 / 进度 / 失败智能体 / 可迁移上下文」纳入考量
- 重复失败会让重规划更容易，而有价值的不可迁移工作会让重规划更难——这正是「进度感知」的精髓
- 通过
export_state/restore_state把学习状态（上下文信任、协同、报价保真度、在线模型）序列化为带版本的 JSON 快照，跨重启不丢失
💡 这意味着 sprix-sage-router会学习：用每次真实执行证据，持续校准「谁在哪个领域更靠谱」。
🧠 8. 它和「普通 LLM 路由」有什么不一样？
很多路由方案只是「挑一个最强的智能体」。sprix-sage-router 的差异点：
- 执行中三模式竞争：SELF / COLLABORATE / HANDOFF 在同一个效用函数里比，而非各自独立的启发式
- 互补性优先于名气：奖励「边际需求覆盖」，而非收集一堆高分但冗余的智能体
- 上下文信任而非单一口碑分：按「智能体 × 需求」维度学习，编程强 ≠ 研究强
- 权限优先：不合格的智能体根本进不了排序
- 任务 DAG 角色分配：每个剩余需求都有明确执行者，依赖边变成可检查的通信拓扑
📖 完整算法与限制见 ALGORITHM.md，上线门槛与指标见 docs/OPERATIONS.md。
📁 9. 文件路径速查：从代码到文档
| 你想找什么 | 去哪里 |
|---|---|
| 上下文路由器 / DAG 调度 / 束搜索 / 审计痕迹 | sprix_sage.py |
| Agent Card 规范化 + 传输中立执行计划 | sprix_a2a.py |
| A2A 集成指南 | docs/INTEGRATION.md |
| 算法形式化目标与搜索 | ALGORITHM.md |
| A2A 规划可运行示例 | examples/a2a_execution_plan.py |
| 失败恢复 + 持久化示例 | examples/replan_and_persist.py |
| 端到端路由演示 | demo.py |
| 运维 / 上线门槛 | docs/OPERATIONS.md |
| 基准测试说明 | docs/BENCHMARKING.md |
✅ 10. 集成最佳实践清单
- 🔒先认证，再路由：身份、签名、安全方案都在 SAGE 之外校验
- 📏技能分必须对得上卡片：本地证据与声明技能一一映射
- 🧾保留审计痕迹：
trace.to_dict()落到日志，便于排障与合规 - 🚦传输职责归 A2A 客户端：别把路由层当传输层
- 🧪产物评估后再记成功：
record_outcome之前先验证产物 - 💾定期持久化：
export_state保存带版本快照，重启可恢复
⚠️当前定位：sprix-sage-router 是早期研究预览，不是生产 SLA。生产部署需要校准评估器、认证身份、签名能力元数据、隐私安全评审等——详见 docs/OPERATIONS.md。
写在最后：sprix-sage-router 把「A2A 发现 → 路由决策 → 执行计划」这条链路拆得非常干净。只要抓住「Agent Card 只给广告，本地证据才验货，ExecutionPlan 只决策不发请求」这三句话，你就能快速把它接入自己的智能体网络。
【免费下载链接】sprix-sage-routerSprix AI at 屿智同行 — state-aware SELF/COLLABORATE/HANDOFF routing for A2A agent networks.项目地址: https://gitcode.com/gh_mirrors/sp/sprix-sage-router
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
