OmniRoute A2A Server 接入指南Agent-to-Agent Protocol v0.3 智能路由代理服务详解【免费下载链接】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/i18n/ar/docs/frameworks/A2A-SERVER.md阿拉伯语版与 docs/frameworks/A2A-SERVER.md英文原版整理编写并以仓库源码 src/app/a2a/route.ts、src/lib/a2a/taskManager.ts 等实现细节交叉验证。OmniRoute 作为统一 AI 网关除了标准的 OpenAI 兼容 API 之外还提供了一面完整的Agent-to-AgentA2A协议服务让其他 Agent 框架可以把 OmniRoute 当作一个智能路由代理来调用——把提示词交给它由它完成模型选型、配额检查、成本预估与回退容错。本文面向希望在 Claude Code、自研 Agent 或任意支持 JSON-RPC/SSE 的程序中接入 OmniRoute A2A Server 的开发者读完你将掌握如何发现 Agent Card、如何完成认证与开关启用、四个核心 JSON-RPC 方法的完整调用格式与响应结构、六个内置技能的能力边界、任务生命周期与 TTL 机制以及如何用 Python / TypeScript 在 10 行代码内完成首个调用。A2A 服务的双面形态JSON-RPC 主入口与 REST 辅助接口从源码结构看A2A 表面surface分为两个层面职责各有分工JSON-RPC 2.0入口为POST /a2a是规范的canonical入口点定义在 src/app/a2a/route.ts。message/send、message/stream、tasks/get、tasks/cancel四个方法都在这里分发。REST 辅助接口位于/api/a2a/*之下面向仪表盘与外部工具提供状态查询、任务列表、任务取消等操作。任务由A2ATaskManager统一管理src/lib/a2a/taskManager.ts默认 5 分钟 TTL技能Skill通过 src/lib/a2a/taskExecution.ts 中的A2A_SKILL_HANDLERS注册表分发执行。端口说明文档中的示例统一使用http://localhost:20128作为 A2A Server 监听地址实际端口以你启动 OmniRoute 时的配置为准。Agent Discovery通过 Agent Card 发现能力任何 A2A 客户端的第一步都是发现对端能力。OmniRoute 按照 A2A 规范暴露了一个标准的发现端点curl http://localhost:20128/.well-known/agent.json该端点返回Agent Card其中描述 OmniRoute 的能力capabilities、可用技能skills以及认证要求authentication requirements。外部 Agent 可以先读取这份卡片再决定调用哪个技能。据官方文档说明Agent Card 中的version字段取自process.env.npm_package_version因此每次发版时都会与package.json自动同步不会出现版本号漂移。Agent Card 也应与实时更新的 352 供应商目录保持对齐其中的供应商数量与 free/no-auth 元数据均来自运行时注册表。认证机制与启用开关Bearer Token 认证所有/a2a请求都需要通过Authorization头携带 API KeyAuthorization: Bearer YOUR_OMNIROUTE_API_KEY从 src/lib/a2a/authenticate.ts 的authenticateA2ARequest实现可以看出认证的完整判定逻辑分为三层若全局启用了REQUIRE_API_KEY策略isRequireApiKeyEnabled()为真则请求必须携带有效的 OmniRoute API Key通过isValidApiKey校验。若未启用强制策略、但配置了环境变量OMNIROUTE_API_KEY则用timingSafeEqual做常数时间比对防止时序侧信道攻击。若服务器上既未启用强制 Key、也未配置任何 Key则认证直接放行——这是与/v1一致的本地优先、免钥keyless默认姿态。此外resolveA2AOwner会对调用方的 API Key 做 SHA-256 哈希并取前 32 位十六进制字符作为任务的所有者 ID用于任务可见性隔离对应安全公告 GHSA-jcm5-6wpp-wjj8带所有者的任务仅对该所有者可见而免钥调用产生的任务对所有调用者可见。Endpoints 开关A2A 默认关闭A2A 功能由Endpoints 页面中的 A2A 开关控制默认处于关闭状态。未启用时的行为对应 src/app/a2a/route.ts 的rejectIfA2ADisabledGET /api/a2a/status返回status: disabled与online: false对POST /a2a的 JSON-RPC 调用返回HTTP 503错误码为 JSON-RPC 标准扩展码-32000消息为A2A endpoint is disabled. Enable it from the Endpoints page.对应的单元测试见 tests/unit/a2a-enabled-route.test.ts。JSON-RPC 2.0 核心方法所有方法都遵循 JSON-RPC 2.0 规范请求体包含jsonrpc: 2.0、id、method、params四个字段。下面逐一说明。message/send同步执行向某个技能发送消息并等待完整响应。这是最常用的方法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} } }params的三个字段说明字段说明skill要调用的技能 ID缺省时路由到smart-routing源码中params?.skill || smart-routingmessages消息数组每项为{ role, content }兼容 A2A v1.0 的message.content与message.parts[]形态metadata可选透传给技能的附加参数例如model、combo、role等成功响应示例{ 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 } } } }响应中的metadata是 OmniRoute A2A 最具价值的输出routing_explanation人类可读的路由决策说明例如选择了哪个模型、经由哪个供应商、延迟与成本cost_envelope成本信封给出预估成本estimated与实际成本actual及币种resilience_trace韧性追踪逐条记录primary_selected、fallback等事件完整还原回退链路policy_verdict策略裁定说明该请求是否在预算与配额限制之内。在message/send的执行路径上源码还会对smart-routing技能调用 src/lib/a2a/routingLogger.ts 的logRoutingDecision记录路由决策供后续分析与审计。message/streamSSE 流式输出message/stream与message/send参数完全一致但响应改为Server-Sent EventsSSE适合需要实时展示生成内容的场景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 源码可以看到三个关键实现细节chunk 事件state: working状态下逐块推送chunk文本片段heartbeat 心跳每 15 秒发送一条: heartbeat ISO 时间注释行保活防止代理或负载均衡器断开空闲连接完成事件任务结束时推送state: completed并携带完整metadata。流式路径通过executeA2ATaskWithState见 src/lib/a2a/taskExecution.ts包装任务执行期间还会尝试收集记忆命中memory hits可通过OMNIROUTE_A2A_MEMORY_HITS0关闭写入task.metadata.memoryHits纯为可观测性用途不会注入技能提示词。tasks/get查询任务状态异步任务可以随时通过任务 ID 回查状态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}}tasks/get在返回前会检查任务是否已过期若任务处于submitted或working状态且已超过expiresAt会先将其标记为failed消息为Task expired。同时执行所有者可见性校验——带所有者的任务对其他调用方返回Task not found避免 IDOR 探测对应 tests/unit/a2a-task-owner-idor.test.ts。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}}tasks/cancel先将任务从submitted/working迁移到cancelled随后技能执行线程会在executeA2ATaskWithState捕获状态迁移异常并保留原始错误确保取消不会破坏正在进行的写路径。版本兼容性提示源码中还实现了一层A2A v1.0 与 v0.3 的兼容层src/app/a2a/route.ts 顶部的V1_METHOD_ALIASESv1.0 客户端使用SendMessage/SendStreamingMessage方法名同样可以调用且同步响应会被重塑为 v1.0 的task.status.message.parts[].text形态。因此 a2a-sdk 1.x、Hermes 等 v1.0 客户端可以直接接入v0.3 客户端不受影响。可用技能Skills清单OmniRoute 通过 src/lib/a2a/taskExecution.ts 的A2A_SKILL_HANDLERS注册了 6 个 A2A 技能每个技能模块位于 src/lib/a2a/skills/ 目录下技能ID说明标签示例问法Smart Routingsmart-routing使用 OmniRoute 的组合引擎与评分机制将提示词路由到最优供应商/组合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返回完整的 45 项 Agent 技能目录23 项 API 21 项 CLI 1 项 config为 Markdown 表格附带原始 SKILL.md URL 供上下文注入catalog, discovery, skillsList all OmniRoute capabilities每个技能的实现都对应一个独立模块例如src/lib/a2a/skills/smartRouting.tsexecuteSmartRoutingsrc/lib/a2a/skills/quotaManagement.tssrc/lib/a2a/skills/providerDiscovery.tssrc/lib/a2a/skills/costAnalysis.tssrc/lib/a2a/skills/healthReport.tssrc/lib/a2a/skills/listCapabilities.tslist-capabilities 技能详解对于需要在发送 API 调用前先了解 OmniRoute 暴露了哪些能力的外部 Agent 而言list-capabilities尤其有用。它返回一个结构化的 Markdown 表格 artifact| ID | Name | Category | Area | Endpoints/Commands | Raw URL | | --- | --- | --- | --- | --- | --- | | omni-auth | Auth Sessions | api | auth | POST /api/auth/login, ... | https://raw.githubusercontent.com/... | ...从 src/lib/a2a/skills/listCapabilities.ts 源码可见数据来自getCatalog()与computeCoverage()定义于 src/lib/agentSkills/catalog.ts每行包含rawUrl列Agent 可以立即抓取完整的 SKILL.md 注入上下文响应的metadata.totalSkills反映目录规模当前为 45 项metadata.coverage分别给出 API23/CLI21/config1的覆盖统计。REST 辅助 API面向仪表盘与工具链/a2a是规范的 JSON-RPC 入口而下列 REST 端点提供辅助访问供仪表盘与外部工具使用端点方法说明认证/api/a2a/statusGET服务器状态、已注册技能公开/api/a2a/tasksGET带过滤条件列出任务management/api/a2a/tasks/[id]GET按 ID 获取任务management/api/a2a/tasks/[id]/cancelPOST取消运行中的任务management/.well-known/agent.jsonGETAgent CardA2A 发现公开缓存 3600 秒/api/a2a/tasksPOST入站委派inbound delegation到 OmniConductor 舰队Bearer 与OMNIROUTE_API_KEYa2aEnabled其中最后一个端点值得单独说明入站 Conductor 委派允许外部 A2A Agent 通过 OmniRoute 把编码工作委派给 OmniConductor 舰队。请求体格式为{ skill: conductor | conductor-cli-profile, messages: [{ role: ..., content: ... }], metadata: { conductor: { repo: { url: ..., base_ref: ... }, mode: ..., cli: ..., model: ... } } }约束与流程要点只有 Conductor 舰队技能即 Agent Card 上公布的技能可被委派metadata.conductor.repo.url为必填舰队在 git 仓库上工作该路由使用服务端CONDUCTOR_ORCHESTRATOR_TOKEN回退CONDUCTOR_HUB_TOKEN转换为 hub 的POST /v1/tasks返回201 { conductor_task_id, state: submitted }任务状态通过 SSE→A2A 镜像回流可通过GET /api/a2a/tasks?skillconductor查看。任务生命周期与 TTLA2A 任务的状态机如下submitted → working → completed → failed → cancelled任务默认在5 分钟后过期可配置终态为completed、failed、cancelled事件日志记录每一次状态迁移。上述状态机在 src/lib/a2a/taskManager.ts 中有完整实现VALID_TRANSITIONS表严格约束合法迁移例如completed之后不能再次迁移createTask生成 UUID v4 任务 ID并将input.metadata做浅拷贝写入任务自身的metadata运行时袋避免运行时写入污染调用方原始输入每次状态迁移都会追加TaskEvent时间戳 状态 可选消息通过事件总线发出agent.task.updated事件供编排画布监听且监听器异常绝不会拖垮写路径尽力持久化到 SQLite 历史表src/lib/db/a2aTasks.ts 的upsertA2ATask/appendA2ATaskEvent失败仅告警不阻断。TTL 配置TTL 在A2ATaskManager构造函数中配置src/lib/a2a/taskManager.tsconstructor(ttlMinutes: number 5)默认 5 分钟。要自定义只需 forkA2ATaskManager实例化并传入不同值例如new A2ATaskManager(15)即为 15 分钟 TTL。后台定时器每60 秒清理一次过期任务非终态且超过expiresAt的任务被标记为failed消息TTL expired终态且超过 2 倍 TTL 的任务从内存 Map 中删除历史表按OMNIROUTE_A2A_HISTORY_RETENTION_DAYS默认 30 天清理每天最多触发一次。错误码对照表遵循 JSON-RPC 2.0 标准错误码约定并扩展了两个 A2A 专用错误码代码含义-32700解析错误无效 JSON-32600无效请求 / 未授权-32601方法或技能不存在-32602参数无效-32603内部错误-32000A2A 端点未启用HTTP 状态码与 JSON-RPC 错误码的映射见 src/app/a2a/route.ts 的jsonRpcError-32600→ 400-32601→ 404-32603→ 500其余返回 200-32000端点禁用返回 503。集成示例Python 与 TypeScriptPythonrequestsimport 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);两个示例都只依赖标准 HTTP 客户端无需额外 SDK。注意流式场景请改用message/stream并监听 SSE 事件。扩展新技能从零注册一个 A2A Skill如果你需要让 OmniRoute 的 A2A 面暴露自有能力可以按以下五步扩展创建技能文件src/lib/a2a/skills/your-skill.ts导出一个异步函数(task: A2ATask) Promise{ artifacts, metadata }参考现有技能如 src/lib/a2a/skills/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覆盖成功路径与错误路径仓库现有测试可参考 tests/unit/a2a-cost-analysis-numeric-fallback.test.ts、tests/unit/a2a-routing-logger.test.ts 等。更新文档在本文档的 Available Skills 表中补充新技能条目。延伸阅读与源码索引协议总览官方文档 A2A-SERVER.md、AGENT_PROTOCOLS_GUIDE.md技能目录体系AGENT-SKILLS.md、SKILLS.md关键源码src/app/a2a/route.ts路由分发与 v1.0 兼容层、src/lib/a2a/taskManager.ts任务状态机与 TTL、src/lib/a2a/taskExecution.ts技能注册表、src/lib/a2a/authenticate.ts认证、src/lib/a2a/streaming.tsSSE 流式单元测试仓库tests/unit/a2a-*.test.ts系列覆盖启用开关、认证、任务所有权隔离、历史持久化、v1.0 兼容等场景OmniRoute 的 A2A Server 把路由决策、配额管理、成本估算、健康报告与韧性追踪这些网关核心能力封装成了标准 JSON-RPC 方法与可发现的技能目录。无论是把 OmniRoute 接入自研 Agent 编排、交给 Conductor 舰队做代码委派还是让外部 Agent 在调用前先完成能力发现这面 A2A 表面都提供了开箱即用的协议级入口——你只需要一个 API Key 和一次POST /a2a。【免费下载链接】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），仅供参考