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-routersprix-sage-router是 Sprix AI 开源的状态感知智能体路由器专为A2AAgent2Agent协议网络设计。它能在任务执行中途替你在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 → 路由 → ExecutionPlansprix-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.mdA2A 规划与失败恢复两个可运行示例分别在 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.pyAgent Card 规范化 传输中立执行计划sprix_a2a.pyA2A 集成指南docs/INTEGRATION.md算法形式化目标与搜索ALGORITHM.mdA2A 规划可运行示例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），仅供参考
