OmniRoute A2A Server 接入指南用 Agent-to-Agent 协议把 OmniRoute 变成智能路由 Agent【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文依据 docs/frameworks/A2A-SERVER.md 编写结合仓库源码与测试佐证。OmniRoute 以 Agent-to-Agent ProtocolA2Av0.3 暴露自身能力让任何支持 A2A 的 AgentClaude Code、Codex、Hermes 等通过 JSON-RPC 2.0 把任务委托给它由它根据配额、成本、延迟与可靠性智能路由到 352 个提供者、1200 模型之一并返回带路由解释、成本信封与韧性追踪的结构化结果。读完本文你将掌握 OmniRoute A2A 的完整接入姿势——从发现 Agent Card、鉴权、四个 JSON-RPC 方法到六个内置 Skill再到自定义 Skill、TTL 调优与 Python/TypeScript 客户端集成。A2A 表面总览一个入口两种协议面OmniRoute 的 A2A 服务有两张面孔均用于让外部 Agent 与网关互操作JSON-RPC 2.0POST /a2a规范入口处理message/send、message/stream、tasks/get、tasks/cancel四个方法实现在 src/app/a2a/route.ts。REST 辅助面/api/a2a/*面向仪表盘与工具链提供状态查询、任务列表、取消等能力。任务的完整生命周期由A2ATaskManager管理src/lib/a2a/taskManager.ts默认 TTL 5 分钟Skill 的调度则通过A2A_SKILL_HANDLERS注册表完成src/lib/a2a/taskExecution.ts。在深入协议细节前先看协议版本兼容性路由层内置了A2A 1.0 ↔ v0.3 兼容层src/app/a2a/route.ts将 1.0 的方法名SendMessage、SendStreamingMessage分别映射到message/send、message/stream并把 v0.3 的顶层artifacts/metadata重塑为 1.0 客户端期望的task.status.message.parts[].text。这意味着 a2a-sdk 1.x、Hermes 等 1.0 客户端无需改动即可直连本端点v0.3 客户端也完全不受影响。Agent Discovery获取 Agent Card任何 A2A 客户端的第一步都是发现对端能力。OmniRoute 在标准路径提供 Agent Cardcurl http://localhost:20128/.well-known/agent.json返回的 JSON 描述 OmniRoute 的能力、Skill 清单与认证要求字段包括name、description、url、version、capabilities、skills、authentication。该端点在 src/app/.well-known/agent.json/route.ts 实现version字段直接取自process.env.npm_package_versionroute.ts:17每次发版随package.json自动同步Agent Card 动态拼装除 6 个内置 Skill 外还通过getFleetSkills()注入 OmniConductor 编排集群的 fleet skillsConductor PRD RF2集群未配置/离线时为空数组卡片依然有效响应带Cache-Control: public, max-age3600客户端可放心缓存 1 小时。从源码结构可以推断authentication.schemes为[api-key]且apiKeyHeader为Authorization与下文的 Bearer 鉴权方式完全一致。认证与启用开关认证所有/a2a请求都需要在Authorization头中携带 API KeyAuthorization: Bearer YOUR_OMNIROUTE_API_KEY鉴权逻辑集中在 src/lib/a2a/authenticate.tsJSON-RPC 路由与 REST 任务路由共享同一实现避免两处漂移。其判定顺序为若启用了REQUIRE_API_KEY特性开关则校验传入 Key 是否有效无 Key 时回退到仪表盘会话认证与/api/v1/*的会话回退保持一致否则若配置了OMNIROUTE_API_KEY环境变量则用timingSafeEqual做常量时间比较两者皆无——即服务器未配置任何 Key 时鉴权直接放行本地优先的 keyless 默认姿态。也就是说未配置 API Key 时认证会被绕过。此外每个任务都会记录调用者身份ownerAPI Key 的 SHA-256 哈希前 32 位会话登录者为dashboardkeyless 为undefined用于任务可见性与取消操作的归属隔离GHSA-jcm5-6wpp-wjj8 修复见 resolveA2AOwner。启用开关A2A 由Endpoints → A2A开关控制默认关闭。关闭状态下GET /api/a2a/status返回status: disabled、online: false对POST /a2a的 JSON-RPC 调用返回 HTTP 503 与错误码-32000错误信息提示从 Endpoints 页面启用。路由层通过rejectIfA2ADisabledsrc/app/a2a/route.ts读取settings.a2aEnabled判断因此这是一个可持久化、可随时切换的运行期开关。JSON-RPC 2.0 方法所有方法统一走POST /a2a正文为 JSON-RPC 2.0 格式。下面逐一给出可直接运行的 curl 示例与响应形态。message/send— 同步执行向指定 Skill 发送消息并等待完整响应curl -X POST http://localhost:20128/a2a \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_KEY \ -d { jsonrpc: 2.0, id: 1, method: message/send, params: { skill: smart-routing, messages: [{role: user, content: Write a hello world in Python}], metadata: {model: auto, combo: fast-coding} } }响应示例{ jsonrpc: 2.0, id: 1, result: { task: { id: uuid, state: completed }, artifacts: [{ type: text, content: ... }], metadata: { routing_explanation: Selected claude-sonnet via provider \anthropic\ (latency: 1200ms, cost: $0.003), cost_envelope: { estimated: 0.005, actual: 0.003, currency: USD }, resilience_trace: [ { event: primary_selected, provider: anthropic, timestamp: ... } ], policy_verdict: { allowed: true, reason: within budget and quota limits } } } }从实现看message/send的流程为解析skill缺省smart-routing→ 归一化messages支持messages[]、{message: {content}}及遗留的{message: {parts: [...]}}三种形态见toMessageArray→ 查A2A_SKILL_HANDLERS→ 创建任务submitted→ 置working→ 执行 Skill → 置completed。若 Skill 为smart-routing还会调用logRoutingDecision把路由决策写入日志src/app/a2a/route.ts。message/stream— SSE 流式输出与message/send相同但返回 Server-Sent Events 实时流curl -N -X POST http://localhost:20128/a2a \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_KEY \ -d { jsonrpc: 2.0, id: 1, method: message/stream, params: { skill: smart-routing, messages: [{role: user, content: Explain quantum computing}] } }SSE 事件流形态data: {jsonrpc:2.0,method:message/stream,params:{task:{id:...,state:working},chunk:{type:text,content:...}}} : heartbeat 2026-03-03T17:00:00Z data: {jsonrpc:2.0,method:message/stream,params:{task:{id:...,state:completed},metadata:{...}}}流式实现位于 src/lib/a2a/streaming.ts每15 秒发送一次: heartbeat注释行保活连接createHeartbeatSkill 结果以chunk事件逐段下发非流式 Skill 走模拟分块完成时以metadata事件收尾支持AbortSignal取消客户端断开或取消时下发failed事件并关闭流响应头为SSE_HEADERStext/event-stream、no-cache、X-Accel-Buffering: no确保代理服务器不缓冲。tasks/get— 查询任务状态curl -X POST http://localhost:20128/a2a \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_KEY \ -d {jsonrpc:2.0,id:2,method:tasks/get,params:{taskId:TASK_UUID}}参数既支持taskId也兼容id。查询时会先检查过期若任务处于submitted/working且已过 TTL则自动置为failedTask expired再返回。tasks/cancel— 取消任务curl -X POST http://localhost:20128/a2a \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_KEY \ -d {jsonrpc:2.0,id:3,method:tasks/cancel,params:{taskId:TASK_UUID}}取消遵循归属校验只能取消自己owner的任务且任务不存在与无权操作返回同一错误信息防止 IDOR 探测taskManager.ts:268-L278。可用 Skill6 个内置处理器所有 Skill 注册在 src/lib/a2a/taskExecution.ts 的A2A_SKILL_HANDLERS中每个模块位于 src/lib/a2a/skills/均采用懒加载await import(...)首次调用才载入模块SkillID说明Tags示例Smart Routingsmart-routing用组合引擎 评分把提示路由到最优提供者/组合routing, providersRoute this prompt via the best modelQuota Managementquota-management报告各提供者配额状态帮助调用方决定何时限流/切换quota, providersCheck quota for anthropicProvider Discoveryprovider-discovery列出已安装提供者及其能力、免费额度标志、OAuth 状态providers, discoveryWhat providers are available?Cost Analysiscost-analysis依据目录与近期用量估算请求/会话成本cost, usageEstimate cost for this conversationHealth Reporthealth-report汇总各提供者的断路器、冷却、锁定状态health, resilienceShow health status of all providersList Capabilitieslist-capabilities返回完整 Agent Skills 目录45 项23 API 21 CLI 1 配置附带 SKILL.md 原始 URLcatalog, discovery, skillsList all OmniRoute capabilities以smart-routing为例src/lib/a2a/skills/smartRouting.ts它接收model默认auto、combo、budget等元数据调用网关自身的POST /v1/chat/completions30 秒超时随后把真实延迟、实际成本、路由解释、韧性追踪与预算策略裁决withinBudget判定组装进metadata返回。这解释了示例响应中routing_explanation等字段的来源——它们不是凭空生成的文案而是本次请求的真实度量。list-capabilitiesSkill 细节对外部 Agent 而言list-capabilities是在发请求前了解 OmniRoute 能做什么的入口。它返回结构化 markdown 表格制品| ID | Name | Category | Area | Endpoints/Commands | Raw URL | | --- | --- | --- | --- | --- | --- | | omni-auth | Auth Sessions | api | auth | POST /api/auth/login, ... | https://raw.githubusercontent.com/... | ...每行包含rawUrl列Agent 可据此立即拉取完整 SKILL.mdmetadata.totalSkills字段镜像目录规模当前 45 项。实现见 src/lib/a2a/skills/listCapabilities.ts。更完整的 Skill 说明可参考 docs/frameworks/AGENT-SKILLS.md。提示Agent Card 的提供者数据与运行时注册表保持同步——文档明确要求 Agent Card 与实时 352 提供者目录对齐提供者数量与免费/免认证元数据均来自运行时注册表而非硬编码。REST 辅助 APIJSON-RPC 的/a2a是规范入口以下 REST 端点向仪表盘与外部工具提供辅助访问端点方法说明认证/api/a2a/statusGET服务器状态、已注册 Skill公开/api/a2a/tasksGET带筛选的任务列表management/api/a2a/tasks/[id]GET按 ID 获取任务management/api/a2a/tasks/[id]/cancelPOST取消运行中的任务management/.well-known/agent.jsonGETAgent CardA2A 发现缓存 3600s公开/api/a2a/tasksPOST入站委派到 OmniConductor 集群Conductor PRD RF5Bearer OMNIROUTE_API_KEYa2aEnabled入站 Conductor 委派其中POST /api/a2a/tasks是 OmniRoute 与 OmniConductor 编排集群协作的关键通道外部 A2A Agent 把编码任务委托给 Conductor 集群执行。请求体形如{ skill: conductor | conductor-cli-profile, messages: [{role, content}], metadata: { conductor: { repo: { url: ..., base_ref? }, mode?, cli?, model? } } }规则要点只有 Agent Card 上公布过的 Conductor 集群 Skill 才可委派metadata.conductor.repo.url为必填集群在 git 仓库上工作路由会翻译为 hub 的POST /v1/tasks使用服务端CONDUCTOR_ORCHESTRATOR_TOKEN回退CONDUCTOR_HUB_TOKEN返回201 { conductor_task_id, state: submitted }任务状态通过 SSE→A2A 镜像回流可通过GET /api/a2a/tasks?skillconductor查询。任务生命周期与 TTL状态机submitted → working → completed → failed → cancelled默认 5 分钟过期可配置见下终态completed、failed、cancelled事件日志记录每一次状态迁移。从源码看状态机有明确的合法迁移表taskManager.ts:121-L127submitted → working/failed/cancelledworking → completed/failed/cancelled终态不可再迁移非法迁移直接抛错。每次迁移都会追加events日志、通过事件总线发布agent.task.updated供编排画布消费监听器异常不会打断写路径、并尽力持久化到 SQLite 历史表persist全程 best-effort失败仅记日志。任务 TTL 定制A2ATaskManager构造器接受ttlMinutes参数默认 5 分钟taskManager.ts:139。如需调整fork 单例实例化并传入新值例如new A2ATaskManager(15)得到 15 分钟 TTL。后台每60 秒清扫一次过期任务非终态任务到期 → 置为failedTTL expired终态任务超过 2 倍 TTL → 从内存移除历史表清理受OMNIROUTE_A2A_HISTORY_RETENTION_DAYS环境变量控制默认保留 30 天每天至多 purge 一次见 historyRetentionDays。此外流式任务通过beginStream/endStream维护活跃流计数可在GET /api/a2a/status中体现listTasks支持state/skill筛选与offset/limit分页默认 limit 50。错误码代码含义-32700解析错误无效 JSON-32600无效请求 / 未授权-32601方法或 Skill 不存在-32602参数无效-32603内部错误-32000A2A 端点已禁用对应的 HTTP 状态映射见 src/app/a2a/route.ts-32600→ 400-32601→ 404-32603→ 500其余含-32700、-32000与非法方法→ 200其中-32000场景为 HTTP 503route.ts:147-L161。实际调用时建议同时检查 HTTP 状态码与 JSON-RPCerror字段。新增一个 Skill 的完整流程A2A 的 Skill 扩展遵循文件 → 注册 → 暴露 → 测试 → 文档五步创建 Skill 文件src/lib/a2a/skills/your-skill.ts导出异步函数(task: A2ATask) Promise{ artifacts, metadata }参照smartRouting.ts的既有形状。注册处理器在 src/lib/a2a/taskExecution.ts 的A2A_SKILL_HANDLERS中加入条目export const A2A_SKILL_HANDLERS { // ...existing skills your-skill: async (task) { const skillModule await import(./skills/yourSkill); return skillModule.executeYourSkill(task); }, };暴露到 Agent Card在src/app/.well-known/agent.json/route.ts的skills数组追加{ id: your-skill, name: Your Skill, description: Brief, intent-focused description, tags: [routing, quota], examples: [Sample natural-language invocation] }编写测试tests/unit/a2a-your-skill.test.ts覆盖 happy path 与错误路径。仓库的 a2a 单元测试同时覆盖了任务管理器、认证、流式输出与各 Skill 模块。文档同步在本文件Available Skills表中登记新 Skill。说明本文为技术指南仅介绍如何阅读、运行与配置仓库仓库为只读文中不涉及修改仓库内容的操作建议。集成示例Pythonrequestsimport requests resp requests.post(http://localhost:20128/a2a, json{ jsonrpc: 2.0, id: 1, method: message/send, params: { skill: smart-routing, messages: [{role: user, content: Hello}] } }, headers{Authorization: Bearer YOUR_KEY}) result resp.json()[result] print(result[artifacts][0][content]) print(result[metadata][routing_explanation])TypeScriptfetchconst resp await fetch(http://localhost:20128/a2a, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer YOUR_KEY, }, body: JSON.stringify({ jsonrpc: 2.0, id: 1, method: message/send, params: { skill: smart-routing, messages: [{ role: user, content: Hello }], }, }), }); const { result } await resp.json(); console.log(result.metadata.routing_explanation);扩展阅读与源码索引规范文档docs/frameworks/A2A-SERVER.md本指南原始依据Agent Skills 目录docs/frameworks/AGENT-SKILLS.mdJSON-RPC 路由src/app/a2a/route.tsAgent Card 端点src/app/.well-known/agent.json/route.ts任务管理器src/lib/a2a/taskManager.tsSkill 调度与执行src/lib/a2a/taskExecution.ts认证与归属解析src/lib/a2a/authenticate.tsSSE 流式封装src/lib/a2a/streaming.tsSkill 实现目录src/lib/a2a/skills/【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考