OmniRoute A2A Server 实战指南把 OmniRoute 打造成可被任意 Agent 调用的智能路由 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/OmniRouteOmniRoute 内置了符合 Agent-to-Agent ProtocolA2Av0.3 规范的 A2A Server它把 OmniRoute 暴露为一个智能路由 Agent外部 Agent 通过标准的 JSON-RPC 2.0 协议调用smart-routing、quota-management等技能即可复用 OmniRoute 的模型路由、成本核算、配额管理与弹性回退能力。读完本文你将掌握 A2A 端点的发现、鉴权、四大核心 RPC 方法、六大内置技能、任务生命周期与错误码并能在 Python/TypeScript 中完成真实调用还能按规范扩展自己的 A2A 技能。本文以 docs/i18n/fr/docs/frameworks/A2A-SERVER.md法文版与 docs/frameworks/A2A-SERVER.md英文原版为主体结合仓库源码src/lib/a2a/、src/app/a2a/进行原理级佐证。一、A2A Server 概览双面接口OmniRoute 的 A2A 面由两个互补的入口构成JSON-RPC 2.0 规范入口POST /a2a规范入口实现在src/app/a2a/route.ts承载message/send、message/stream、tasks/get、tasks/cancel四个方法REST 辅助入口/api/a2a/*为仪表盘和外部工具提供状态查询、任务列表、取消等辅助能力。所有任务的追踪由A2ATaskManager负责src/lib/a2a/taskManager.ts默认 5 分钟 TTL技能的调度则通过A2A_SKILL_HANDLERS注册表完成src/lib/a2a/taskExecution.ts。二、Agent Discovery发现 Agent Card与其他 A2A Agent 一样外部调用方首先通过 well-known 端点发现 OmniRoute 的能力声明curl http://localhost:20128/.well-known/agent.json该端点返回描述 OmniRoute 能力、技能清单与鉴权要求的Agent Card。Agent Card 中的version字段取自process.env.npm_package_version因此每次发布都会自动与package.json保持同步无需手工维护版本号。Agent Card 应始终与运行时 352 提供方目录保持一致提供方数量与 free/no-auth 元数据均来自运行时注册表。三、启用 A2A默认关闭需显式开启A2A 由Endpoints → A2A开关控制默认处于关闭状态。关闭时GET /api/a2a/status返回status: disabled与online: false对POST /a2a的 JSON-RPC 调用返回 HTTP 503并携带 JSON-RPC 错误码-32000A2A endpoint is disabled。四、AuthenticationBearer API Key所有/a2a请求都需要通过Authorization头携带 API KeyAuthorization: Bearer YOUR_OMNIROUTE_API_KEY如果服务器上未配置任何 API Key则鉴权被跳过keyless 本地优先模式。鉴权逻辑集中实现在 src/lib/a2a/authenticate.ts若REQUIRE_API_KEY特性开启则校验请求携带的 key 是否为合法 OmniRoute keyisValidApiKey否则若配置了OMNIROUTE_API_KEY环境变量则用timingSafeEqual做常量时间比较否则既无要求也无配置放行所有请求。同时resolveA2AOwner会对调用方的 API Key 做 SHA-256 哈希并截取前 32 位作为任务的 owner 标识GHSA-jcm5-6wpp-wjj8用于任务可见性隔离带 owner 的任务只对同一 owner 可见keyless 下产生的无主任务对所有调用方可见。tasks/get、tasks/cancel、listTasks均执行该 owner 作用域检查。五、JSON-RPC 2.0 方法所有方法统一走POST http://localhost:20128/a2a请求体遵循 JSON-RPC 2.0 规范jsonrpc、id、method、params。5.1message/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} } }响应示例{ 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是smart-routing技能的精华所在routing_explanation解释选中了哪个模型与提供方cost_envelope给出预估/实际成本resilience_trace记录弹性回退事件policy_verdict给出预算与配额策略裁决。5.2message/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:{...}}}流式过程中会周期性发送: heartbeat ...注释行保活A2ATaskManager内部通过beginStream()/endStream()跟踪活跃流数量activeStreams统计信息可通过getStats()获取。5.3tasks/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}}底层由 src/lib/a2a/taskManager.ts 的getTask实现读取时若发现任务已超过expiresAt且仍处于非终态会先将其标记为failedTask expired再按 owner 可见性过滤返回。5.4tasks/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}}cancelTask在变更状态之前执行 owner 检查且对任务不存在与任务存在但不属于你返回相同的 not-found 错误防止 IDOR 探测。六、Available Skills六大内置技能OmniRoute 通过 src/lib/a2a/taskExecution.ts 中的A2A_SKILL_HANDLERS注册了 6 个 A2A 技能每个技能模块位于src/lib/a2a/skills/目录下技能ID描述标签示例调用Smart Routingsmart-routing使用 OmniRoute 的 combo 引擎 评分将提示词路由到最优提供方/comborouting, 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 配置的 markdown 表格附带原始 SKILL.md URLcatalog, discovery, skillsList all OmniRoute capabilities以smart-routing为例其实现位于 src/lib/a2a/skills/smartRouting.ts它从任务输入中读取metadata.model默认auto、metadata.combo与metadata.budget随后调用 OmniRoute 自身的/v1/chat/completions完成路由请求超时 30 秒最后组装routing_explanation、cost_envelope、resilience_trace包含可选的fallback_needed事件与policy_verdict当实际成本超出budget时裁决allowed: false。list-capabilities技能对外部 Agent 尤其有用它返回结构化的 markdown 表格 artifact每行包含 ID、名称、类别、区域、端点和rawUrl列Agent 拿到rawUrl后即可立即抓取完整 SKILL.md 注入上下文metadata.totalSkills字段镜像目录大小当前为 45。实现见src/lib/a2a/skills/listCapabilities.ts可配合 docs/frameworks/AGENT-SKILLS.md 阅读。七、Task 生命周期与 TTL任务遵循如下状态机submitted → working → completed → failed → cancelled任务默认在 5 分钟后过期ttlMinutes可在A2ATaskManager构造时传入其他值如new A2ATaskManager(15)表示 15 分钟 TTL终态为completed、failed、cancelled事件日志记录每一次状态迁移。源码层面src/lib/a2a/taskManager.ts有更多细节值得关注合法迁移表VALID_TRANSITIONS明确定义了每个状态允许的后续状态如submitted只能转working/failed/cancelled非法迁移直接抛错后台清理构造函数启动一个每 60 秒执行一次的cleanupExpired定时器将过期且未处于终态的任务标记为failed消息 TTL expired并清理超过 2×TTL 的终态任务历史持久化任务通过upsertA2ATask、appendA2ATaskEvent写入 SQLite 历史表尽力而为失败仅告警不影响内存主路径并通过purgeA2AHistory按保留天数清理历史保留天数由环境变量OMNIROUTE_A2A_HISTORY_RETENTION_DAYS控制默认 30 天可观测性每次状态迁移会通过事件总线发布agent.task.updated事件监听器异常不会破坏任务写入路径任务执行时还会以最后一条用户消息为查询词做记忆检索OMNIROUTE_A2A_MEMORY_HITS0可关闭命中结果仅作为可观测数据写入metadata.memoryHits不会注入技能提示词。八、Error Codes错误码表代码含义-32700解析错误非法 JSON-32600无效请求 / 未授权-32601方法或技能未找到-32602无效参数-32603内部错误-32000A2A 端点未启用九、REST 辅助 API/a2a是规范的 JSON-RPC 入口以下 REST 端点为仪表盘与外部工具提供辅助访问详见 docs/frameworks/A2A-SERVER.md端点方法描述鉴权/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 发现公开缓存 3600s公开/api/a2a/tasksPOST向 OmniConductor 编队入站委派Conductor PRD RF5Bearer 与OMNIROUTE_API_KEYa2aEnabled入站 Conductor 委派外部 A2A Agent 可通过POST /api/a2a/tasks将编码工作委派给 OmniConductor 编队。请求体为{ skill: conductor | conductor-cli-profile, messages: [{role, content}], metadata: { conductor: { repo: { url, base_ref? }, mode?, cli?, model? } } }—— 只有 Agent Card 上公布的 Conductor 编队技能可被委派且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查看。十、集成示例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);两个示例都读取了result.artifacts[0].content技能输出文本与result.metadata.routing_explanation路由解释前者拿到答案后者拿到为什么选了这条路由的可审计证据。十一、扩展指南添加一个新 Skill若需为 A2A Server 增加自定义技能可按以下五步操作前提是 fork 或本地运行此仓库仓库本身是只读的创建技能文件src/lib/a2a/skills/your-skill.ts导出一个异步函数(task: A2ATask) Promise{ artifacts, metadata }参考现有技能如smartRouting.ts的形状注册 handler在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覆盖正常路径与错误路径更新文档在本文对应的Available Skills表格中登记新技能。十二、源码脉络速览任务状态机与 TTLsrc/lib/a2a/taskManager.ts ——A2ATaskManager类、VALID_TRANSITIONS、60 秒清理定时器、SQLite 历史持久化技能调度src/lib/a2a/taskExecution.ts ——A2A_SKILL_HANDLERS注册表、executeA2ATaskWithState统一完成/失败收尾与记忆命中采集技能实现src/lib/a2a/skills/ ——smartRouting.ts、quotaManagement.ts、providerDiscovery.ts、costAnalysis.ts、healthReport.ts、listCapabilities.ts鉴权与 owner 隔离src/lib/a2a/authenticate.ts ——authenticateA2ARequest、resolveA2AOwner入口路由src/app/a2a/route.tsJSON-RPC 规范入口、src/app/api/a2a/*REST 辅助端点官方文档docs/frameworks/A2A-SERVER.md英文原版含 Enablement、REST 表、扩展指南等更完整的说明。至此你已拥有从发现 → 鉴权 → 调用 → 追踪 → 扩展的完整 A2A 接入链路用message/send获得带路由解释与成本核算的同步结果用message/stream获得实时流式输出用tasks/get/tasks/cancel管理异步任务再用六大内置技能覆盖路由、配额、发现、成本、健康与能力目录等场景——让任意遵循 A2A 协议的 Agent 都能把 OmniRoute 当成一个可信的智能路由大脑来使用。【免费下载链接】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），仅供参考
OmniRoute A2A Server 实战指南：把 OmniRoute 打造成可被任意 Agent 调用的智能路由 Agent
OmniRoute A2A Server 实战指南把 OmniRoute 打造成可被任意 Agent 调用的智能路由 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/OmniRouteOmniRoute 内置了符合 Agent-to-Agent ProtocolA2Av0.3 规范的 A2A Server它把 OmniRoute 暴露为一个智能路由 Agent外部 Agent 通过标准的 JSON-RPC 2.0 协议调用smart-routing、quota-management等技能即可复用 OmniRoute 的模型路由、成本核算、配额管理与弹性回退能力。读完本文你将掌握 A2A 端点的发现、鉴权、四大核心 RPC 方法、六大内置技能、任务生命周期与错误码并能在 Python/TypeScript 中完成真实调用还能按规范扩展自己的 A2A 技能。本文以 docs/i18n/fr/docs/frameworks/A2A-SERVER.md法文版与 docs/frameworks/A2A-SERVER.md英文原版为主体结合仓库源码src/lib/a2a/、src/app/a2a/进行原理级佐证。一、A2A Server 概览双面接口OmniRoute 的 A2A 面由两个互补的入口构成JSON-RPC 2.0 规范入口POST /a2a规范入口实现在src/app/a2a/route.ts承载message/send、message/stream、tasks/get、tasks/cancel四个方法REST 辅助入口/api/a2a/*为仪表盘和外部工具提供状态查询、任务列表、取消等辅助能力。所有任务的追踪由A2ATaskManager负责src/lib/a2a/taskManager.ts默认 5 分钟 TTL技能的调度则通过A2A_SKILL_HANDLERS注册表完成src/lib/a2a/taskExecution.ts。二、Agent Discovery发现 Agent Card与其他 A2A Agent 一样外部调用方首先通过 well-known 端点发现 OmniRoute 的能力声明curl http://localhost:20128/.well-known/agent.json该端点返回描述 OmniRoute 能力、技能清单与鉴权要求的Agent Card。Agent Card 中的version字段取自process.env.npm_package_version因此每次发布都会自动与package.json保持同步无需手工维护版本号。Agent Card 应始终与运行时 352 提供方目录保持一致提供方数量与 free/no-auth 元数据均来自运行时注册表。三、启用 A2A默认关闭需显式开启A2A 由Endpoints → A2A开关控制默认处于关闭状态。关闭时GET /api/a2a/status返回status: disabled与online: false对POST /a2a的 JSON-RPC 调用返回 HTTP 503并携带 JSON-RPC 错误码-32000A2A endpoint is disabled。四、AuthenticationBearer API Key所有/a2a请求都需要通过Authorization头携带 API KeyAuthorization: Bearer YOUR_OMNIROUTE_API_KEY如果服务器上未配置任何 API Key则鉴权被跳过keyless 本地优先模式。鉴权逻辑集中实现在 src/lib/a2a/authenticate.ts若REQUIRE_API_KEY特性开启则校验请求携带的 key 是否为合法 OmniRoute keyisValidApiKey否则若配置了OMNIROUTE_API_KEY环境变量则用timingSafeEqual做常量时间比较否则既无要求也无配置放行所有请求。同时resolveA2AOwner会对调用方的 API Key 做 SHA-256 哈希并截取前 32 位作为任务的 owner 标识GHSA-jcm5-6wpp-wjj8用于任务可见性隔离带 owner 的任务只对同一 owner 可见keyless 下产生的无主任务对所有调用方可见。tasks/get、tasks/cancel、listTasks均执行该 owner 作用域检查。五、JSON-RPC 2.0 方法所有方法统一走POST http://localhost:20128/a2a请求体遵循 JSON-RPC 2.0 规范jsonrpc、id、method、params。5.1message/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} } }响应示例{ 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是smart-routing技能的精华所在routing_explanation解释选中了哪个模型与提供方cost_envelope给出预估/实际成本resilience_trace记录弹性回退事件policy_verdict给出预算与配额策略裁决。5.2message/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:{...}}}流式过程中会周期性发送: heartbeat ...注释行保活A2ATaskManager内部通过beginStream()/endStream()跟踪活跃流数量activeStreams统计信息可通过getStats()获取。5.3tasks/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}}底层由 src/lib/a2a/taskManager.ts 的getTask实现读取时若发现任务已超过expiresAt且仍处于非终态会先将其标记为failedTask expired再按 owner 可见性过滤返回。5.4tasks/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}}cancelTask在变更状态之前执行 owner 检查且对任务不存在与任务存在但不属于你返回相同的 not-found 错误防止 IDOR 探测。六、Available Skills六大内置技能OmniRoute 通过 src/lib/a2a/taskExecution.ts 中的A2A_SKILL_HANDLERS注册了 6 个 A2A 技能每个技能模块位于src/lib/a2a/skills/目录下技能ID描述标签示例调用Smart Routingsmart-routing使用 OmniRoute 的 combo 引擎 评分将提示词路由到最优提供方/comborouting, 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 配置的 markdown 表格附带原始 SKILL.md URLcatalog, discovery, skillsList all OmniRoute capabilities以smart-routing为例其实现位于 src/lib/a2a/skills/smartRouting.ts它从任务输入中读取metadata.model默认auto、metadata.combo与metadata.budget随后调用 OmniRoute 自身的/v1/chat/completions完成路由请求超时 30 秒最后组装routing_explanation、cost_envelope、resilience_trace包含可选的fallback_needed事件与policy_verdict当实际成本超出budget时裁决allowed: false。list-capabilities技能对外部 Agent 尤其有用它返回结构化的 markdown 表格 artifact每行包含 ID、名称、类别、区域、端点和rawUrl列Agent 拿到rawUrl后即可立即抓取完整 SKILL.md 注入上下文metadata.totalSkills字段镜像目录大小当前为 45。实现见src/lib/a2a/skills/listCapabilities.ts可配合 docs/frameworks/AGENT-SKILLS.md 阅读。七、Task 生命周期与 TTL任务遵循如下状态机submitted → working → completed → failed → cancelled任务默认在 5 分钟后过期ttlMinutes可在A2ATaskManager构造时传入其他值如new A2ATaskManager(15)表示 15 分钟 TTL终态为completed、failed、cancelled事件日志记录每一次状态迁移。源码层面src/lib/a2a/taskManager.ts有更多细节值得关注合法迁移表VALID_TRANSITIONS明确定义了每个状态允许的后续状态如submitted只能转working/failed/cancelled非法迁移直接抛错后台清理构造函数启动一个每 60 秒执行一次的cleanupExpired定时器将过期且未处于终态的任务标记为failed消息 TTL expired并清理超过 2×TTL 的终态任务历史持久化任务通过upsertA2ATask、appendA2ATaskEvent写入 SQLite 历史表尽力而为失败仅告警不影响内存主路径并通过purgeA2AHistory按保留天数清理历史保留天数由环境变量OMNIROUTE_A2A_HISTORY_RETENTION_DAYS控制默认 30 天可观测性每次状态迁移会通过事件总线发布agent.task.updated事件监听器异常不会破坏任务写入路径任务执行时还会以最后一条用户消息为查询词做记忆检索OMNIROUTE_A2A_MEMORY_HITS0可关闭命中结果仅作为可观测数据写入metadata.memoryHits不会注入技能提示词。八、Error Codes错误码表代码含义-32700解析错误非法 JSON-32600无效请求 / 未授权-32601方法或技能未找到-32602无效参数-32603内部错误-32000A2A 端点未启用九、REST 辅助 API/a2a是规范的 JSON-RPC 入口以下 REST 端点为仪表盘与外部工具提供辅助访问详见 docs/frameworks/A2A-SERVER.md端点方法描述鉴权/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 发现公开缓存 3600s公开/api/a2a/tasksPOST向 OmniConductor 编队入站委派Conductor PRD RF5Bearer 与OMNIROUTE_API_KEYa2aEnabled入站 Conductor 委派外部 A2A Agent 可通过POST /api/a2a/tasks将编码工作委派给 OmniConductor 编队。请求体为{ skill: conductor | conductor-cli-profile, messages: [{role, content}], metadata: { conductor: { repo: { url, base_ref? }, mode?, cli?, model? } } }—— 只有 Agent Card 上公布的 Conductor 编队技能可被委派且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查看。十、集成示例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);两个示例都读取了result.artifacts[0].content技能输出文本与result.metadata.routing_explanation路由解释前者拿到答案后者拿到为什么选了这条路由的可审计证据。十一、扩展指南添加一个新 Skill若需为 A2A Server 增加自定义技能可按以下五步操作前提是 fork 或本地运行此仓库仓库本身是只读的创建技能文件src/lib/a2a/skills/your-skill.ts导出一个异步函数(task: A2ATask) Promise{ artifacts, metadata }参考现有技能如smartRouting.ts的形状注册 handler在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覆盖正常路径与错误路径更新文档在本文对应的Available Skills表格中登记新技能。十二、源码脉络速览任务状态机与 TTLsrc/lib/a2a/taskManager.ts ——A2ATaskManager类、VALID_TRANSITIONS、60 秒清理定时器、SQLite 历史持久化技能调度src/lib/a2a/taskExecution.ts ——A2A_SKILL_HANDLERS注册表、executeA2ATaskWithState统一完成/失败收尾与记忆命中采集技能实现src/lib/a2a/skills/ ——smartRouting.ts、quotaManagement.ts、providerDiscovery.ts、costAnalysis.ts、healthReport.ts、listCapabilities.ts鉴权与 owner 隔离src/lib/a2a/authenticate.ts ——authenticateA2ARequest、resolveA2AOwner入口路由src/app/a2a/route.tsJSON-RPC 规范入口、src/app/api/a2a/*REST 辅助端点官方文档docs/frameworks/A2A-SERVER.md英文原版含 Enablement、REST 表、扩展指南等更完整的说明。至此你已拥有从发现 → 鉴权 → 调用 → 追踪 → 扩展的完整 A2A 接入链路用message/send获得带路由解释与成本核算的同步结果用message/stream获得实时流式输出用tasks/get/tasks/cancel管理异步任务再用六大内置技能覆盖路由、配额、发现、成本、健康与能力目录等场景——让任意遵循 A2A 协议的 Agent 都能把 OmniRoute 当成一个可信的智能路由大脑来使用。【免费下载链接】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），仅供参考
