如何统一三大模型协议:Eta对OpenAI、Responses与Anthropic Messages的适配深度剖析
如何统一三大模型协议:Eta对OpenAI、Responses与Anthropic Messages的适配深度剖析
Eta 是一款系统级 Android AI Agent,它最容易被忽视、却最见工程功底的部分,是对三大模型协议(OpenAI Chat Completions、OpenAI Responses、Anthropic Messages)的统一适配:你在同一份 Eta 里切换 OpenAI、Claude 或任意 OpenAI-compatible 服务商,Agent Loop 的代码完全不用改。本文带你拆解 Eta 是如何把这三套"方言"收敛成一种"普通话"的。
为什么协议适配是 AI Agent 的隐形深水区 🧩
三家 API 的差异远不止"换个请求体":
| 维度 | Chat Completions | Responses API | Anthropic Messages |
|---|---|---|---|
| 鉴权 | Authorization: Bearer |
Authorization: Bearer |
x-api-key + anthropic-version |
| 系统指令 | messages 中的 system 消息 |
顶层 instructions |
顶层 system 字段 |
| 工具结果 | role: tool 独立消息 |
input Item | 并入 user 消息的 tool_result 块 |
| 流式终止 | finish_reason + [DONE] |
response.completed |
message_stop |
如果每接一个协议就复制一套"请求-流式-解析"代码,UI、重试、取消、测试全都要乘三倍。Eta 的做法是:把协议差异压缩进一层薄薄的边界,边界之内各说各话,边界之外只有一种语言。
统一抽象:AgentProviderClient 是唯一的"协议边界"
Eta 在 AgentProvider.kt 中定义了全部三个协议共用的接口:
internal interface AgentProviderClient {
val id: String
val capabilities: ProviderCapabilities
fun complete(
request: ProviderRequest,
runController: AgentRunController,
onEvent: (ProviderEvent) -> Unit = {}
): ProviderResponse
}
入参是统一的 ProviderRequest(配置 + 消息 + 工具),流式过程通过统一的 ProviderEvent(BlockStart / BlockDelta / BlockEnd / Usage / Completed)上报,返回值是统一的 ProviderResponse。上游的 Agent Loop、UI 与工具执行器永远只面对这一种事件,彻底与协议解耦。
哪个协议上场,由工厂根据配置决定——见 ProviderClientFactory.kt:
ProviderTypes.OPENAI_COMPATIBLE -> when (config.openAiEndpointMode) {
OpenAiEndpointMode.RESPONSES -> OpenAiResponsesProvider
else -> OpenAiChatCompletionsProvider
}
ProviderTypes.ANTHROPIC -> AnthropicMessagesProvider
配置模型上,服务商只有两类:openai_compatible(内部再细分 chat_completions / responses 两种端点模式)和 anthropic,定义在 Provider.kt。另外每个 Provider 都自带一份 ProviderCapabilities 能力声明(流式文本、流式工具、图片输入、并行工具调用等),上层功能按能力位降级,而不是写死协议名。
协议一:Chat Completions——兼容面最广的"老方言"
OpenAiChatCompletionsProvider.kt 面向绝大多数 OpenAI-compatible 端点,几个关键处理:
- URL 拼装:在 Base URL 后追加
chat/completions,见 ProviderUrls.kt; - system 合并:OpenAiRequestMessages.kt 把上下文中全部 system 内容按原顺序合并为首条唯一系统消息,兼容那些要求系统消息只能出现在开头的模型 Chat Template;
- 工具 ID 修复:流式工具调用按
index聚合,空 ID 不覆盖已收到的有效 ID;响应结束时为缺失/冲突的 ID 分配响应级唯一值,且只修复出站副本、不改写持久历史; - 用量统计:默认附加
stream_options.include_usage,唯独对 OpenRouter 关闭(避免其兼容层报错)。
协议二:Responses API——OpenAI 新范式与托管搜索
OpenAiResponsesProvider.kt 与请求构造器 ResponsesRequestBuilder.kt 处理的是 OpenAI 的新范式:
- 请求体不再是
messages,而是instructions+inputItems;Eta 把system/developer消息投影到instructions,历史重建为带type: "message"的 input Item,并显式写入store: false避免服务端留存; - 并行工具调用是它的独有开关:Chat Completions 的 capabilities 中
parallelToolCalls = false,而 Responses 端为true; - 托管网页搜索:仅 Responses 协议有独立开关,开启后请求只增加
web_search托管工具,搜索开始/结束作为独立运行事件投影到 UI,且不受本地browserTools开关控制;最终回答中的url_citation会去重并转成可点击的 Markdown 引用。
协议三:Anthropic Messages——结构差异最大的一支
AnthropicMessagesProvider.kt 承担最多的结构翻译工作:
- system 消息抽离到顶层
system字段,鉴权改用x-api-key+anthropic-version(默认2023-06-01,用户可配); - tool 消息的"再入 user":OpenAI 风格的
role: tool会被转换成 user 消息内的tool_result块,并与紧随其后的观察图片、用户补充合并进同一条 user 消息——因为官方接口会合并连续同角色消息,但兼容端点不一定这么做,第二条孤立的 tool_result 会被判为非法块(见 appendTurn 的注释); - 工具 schema 翻译:Anthropic 不接受
oneOf/anyOf/allOf顶层组合关键字,转换时会剥离; - max_tokens 按模型名自动给默认值,用户在 custom body 里显式填写的值优先级最高;
- 思考签名回传:工具回合会在当前 run 的模型上下文中按原顺序回传思考块、签名及加密块,供后续 tool_result 继续使用;自动压缩会被延后到签名回合完成,强制压缩则明确报错。
流式解析:共享 SSE 分帧,终态各回各家
三套协议都走 SSE,但事件语义完全不同(choices<a href="https://link.gitcode.com/i/6725f27e333cfc836cd1838e6dd5cf6a" target="_blank">0].delta / response.* 事件族 / content_block_* 事件族)。Eta 把协议无关的分帧逻辑抽到共享函数 [ProviderSseReader.kt:多行 data:、注释心跳、UTF-8 解码统一处理,回调返回 false 即视为"已收到终态",立即停止读取、不等服务端关闭连接。
收尾语义则各有讲究:
| 协议 | 结束条件 |
|---|---|
| Chat Completions | finish_reason 到达时结束可见块,再接收用量与 [DONE] |
| Responses | response.completed 到达即收尾 |
| Anthropic | message_stop 到达即收尾 |
缺少合法终态、或 Anthropic 可见块/工具块未闭合时,Eta 会返回"未完成"错误而不是静默吞掉。三种协议的推理内容也各自消费(reasoning_content / reasoning summary / thinking_delta),最终统一投影为 THINKING 块供 UI 展示。
统一出口:停止原因与事件的"归一化"
无论哪个协议,最终结果都会归一化到 AssistantStopReason:stop/end_turn → END_TURN,tool_calls/tool_use → TOOL_USE,length/max_tokens → OUTPUT_LIMIT,content_filter/refusal → CONTENT_FILTER。Agent Loop 只需判断"要不要执行工具批次",不需要知道对面是谁。
流式侧同理:三个 Provider 把各自的分片翻译成同一套 BlockStart → BlockDelta → BlockEnd 事件,并用 round + block index 的块身份避免正文、思考、工具三类内容互相串块;类型一旦切换,上一段可见块立即定稿。UI 只消费这套事件,天然协议无关。
细节打磨:从模型目录到推理强度
协议统一之外,Eta 还铺了几条"隐形道路":
- 推理强度映射:ProviderReasoning.kt 把统一的
reasoningEffort翻译成各服务商的私有写法(百炼、SiliconFlow、DeepSeek、Moonshot、OpenAI……每家一套),用户只感知"开/关/力度"; - 模型目录:从 models.dev 拉取公开元数据(随 APK 附带压缩快照),只列出可按 Chat Completions 接入且具备文本输出与工具调用能力的模型;读取目录不会外发 API Key;
- 自定义能力:自定义 Header / Body 在请求组装时合并,但
model、instructions等决定协议正确性的字段由运行时最终写入,用户配置无法"污染"协议骨架。
如何验证与延伸阅读
Eta 为每条协议链路都配了独立的单元测试,是阅读实现的最佳入口:
- OpenAiChatCompletionsProviderTest.kt
- OpenAiResponsesProviderTest.kt
- AnthropicMessagesProviderTest.kt
- ProviderSseReaderTest.kt、OpenAiChatToolCallIdsTest.kt、ProviderReasoningTest.kt
官方文档 docs/AGENT_RUNTIME.md 的"Provider 边界"章节逐条记录了消息投影、ID 修复、思考签名与托管搜索的行为约定,docs/TECHNICAL.md 则覆盖整体技术架构。
结语:一份会话,三种协议,零感知
这套设计的收益可以一句话概括:UI 只消费一种 ProviderEvent,工具目录只生成一份 JSON Schema,历史只存一种会话结构——协议差异被牢牢关在三个 Provider 对象与若干转换器里。对普通用户,这意味着在设置页切换服务商、在 Chat Completions 与 Responses 之间选择端点,甚至接入 Claude,都只是"换个模型"这么简单;而对开发者,Eta 的 agent/model/ 目录本身就是一份"多协议 AI Agent 适配"的可借鉴样板。


