LiteLLM Agent Control Plane 统一 SDK 契约详解:为何所有运行时都长成一个 Anthropic 形状
LiteLLM Agent Control Plane 统一 SDK 契约详解:为何所有运行时都长成一个 Anthropic 形状
LiteLLM Agent Control Plane(LAP,常称 LAP)是"一个入口调用所有 Agent"的统一控制平面。这篇文章详解它的核心设计——统一 SDK 契约:如何让 Claude Managed Agents、Cursor、Gemini Antigravity、Elastic Agent Builder 等完全不同的 Agent 运行时,在调用方眼中都"长成一个 Anthropic 形状",用同一套四步流程创建 Agent、开会话、收发事件,调用代码里永远不出现 if runtime == ... 这种分支。
一个痛点:N 个运行时,N 套 API
如果你同时对接过几家 Agent 平台,大概都体会过这种痛:
- 有的平台用
/v1/agents建 Agent,有的用/v1beta/agents; - 有的平台有"环境(Environment)"概念,有的根本没有;
- 有的平台发提示词走"事件"接口,有的直接叫"run(运行)";
- 流式事件更是五花八门,事件名、字段名、结束信号各不相同。
每接一个运行时,就要重写一遍业务代码。LAP 的解法很直白:在 SDK 层定死一份统一的 API 契约,把所有差异锁死在适配器里。
四步统一流程:agents → environments → sessions → events
无论底层是哪个运行时,SDK 对外都只暴露同一条四步流程(参考实现见 docs/engineering/sdk-api-contract.mdx):
let agent = client.beta().agents().create(params).await?;
let env = client.beta().environments().create(params).await?;
let session = client.beta().sessions().create(params).await?;
// 发送提示词
client.beta().sessions().events().send(session_id, params).await?;
// 流式接收回复
let stream = client.beta().sessions().events().stream(session_id).await?;
官方文档里有一句话是这个契约的灵魂:"The flow is identical for every runtime. No match runtime or if runtime == X blocks appear in calling code."(流程对所有运行时完全一致,调用代码里不出现任何按运行时分支的块。)
一个"Anthropic 形状":输入与输出类型
统一不是"谁迁就谁",而是选定 Anthropic Managed Agents API 作为参考形状——它天然以 Agent、Environment、Session、Event 为资源模型,最贴近"托管 Agent"的领域语言。
输入侧:CreateAgentParams、CreateEnvironmentParams、CreateSessionParams 等参数结构是唯一的。同一个 system 字段,Anthropic 直接接收、Cursor 会被映射为 prompt.text、Gemini 会被映射为 system_instruction——差异由适配器消化,调用方无感。
输出侧:ManagedAgent、Session、AgentEvent 三类结构对所有人都是 Anthropic 形状。以 ManagedAgent 为例,字段包括 id、name、model、system、tools、mcp_servers、created_at 等(完整字段表见 docs/engineering/sdk-api-contract.mdx)。
这里有一个值得学习的细节:每个输出结构都带一个 raw 字段,保存未经修改的原始 provider 响应。这就是"逃生舱"——统一类型覆盖不到的字段,随时可以从 raw 里捞出来。标准化不牺牲信息量,这是契约设计里少见的克制。
事件流归一化:把 Cursor 事件"翻译"成 Anthropic 事件
最棘手的是流式事件。Cursor 的原生事件叫 assistant、thinking、tool_call、status,而契约要求的是 agent.message、agent.thinking、agent.tool_use、session.status_idle 这套名字。
LAP 的答案是在每个适配器的 normalize_stream 方法里做归一化。看 Cursor 适配器的实现(src/sdk/providers/cursor/runtime/stream.rs):它维护一个流式状态机,把 assistant 文本块累积后一次性 flush 成 agent.message,把 tool_call 翻译成成对的 agent.tool_use / agent.tool_result,把 status: FINISHED 翻译成终止信号 session.status_idle。
归一化后,所有运行时的事件都收敛到同一张小表:
| 事件 | 含义 |
|---|---|
session.status_running |
会话正在处理 |
agent.message |
Agent 回复,data.content 是内容块数组 |
agent.tool_use |
Agent 调用了工具 |
agent.tool_result |
工具返回结果 |
session.status_idle |
会话结束,终止事件——读到它就该停止读流 |
调用方拿到事件后可以用 event.kind() 和 event.payload() 获得类型化访问(src/sdk/agents/events.rs),不必手动解析 JSON。
Provider 归一化全景:哪些部分是"合成"的
契约文档给出了最直观的对照表,一眼能看出每个运行时被"削圆"了哪些棱角(节选自 docs/engineering/sdk-api-contract.mdx):
| 关注点 | Anthropic | Cursor | Gemini Antigravity |
|---|---|---|---|
agents.create 路径 |
POST /v1/agents |
POST /v1/agents |
POST /v1beta/agents |
environments.create |
真实接口 | 合成({ id: name }) |
合成(remote) |
sessions.create |
真实接口 | 合成(复用 agent ID) | 合成会话句柄 |
send_events |
POST /v1/sessions/{id}/events |
POST /v1/agents/{id}/runs |
POST /v1beta/interactions |
stream_events |
原生 SSE | 事件归一化后输出 | interaction steps 归一化后输出 |
注意"合成(Synthetic)"这一列:Cursor 根本没有 Environment 概念,适配器就本地造一个 { id: name } 返回;Gemini 的流式接口其实是轮询——适配器每 2 秒拉一次 interaction 状态、去重后伪装成事件流吐出(src/sdk/providers/gemini/runtime/mod.rs)。这些"假动作"全部发生在适配器内部,契约上层浑然不觉。
RuntimeAdapter:把所有差异关进一个 trait
契约的执行载体是 RuntimeAdapter trait(src/sdk/providers/base/runtime.rs),定义在 sdk/providers/base/:
- 必选方法:
create_session、send_events、stream_events——任何运行时必须实现的"最小能力集"; - 可选方法(有默认实现):
create_agent、create_environment、normalize_stream、provider_run_id_from_agent_raw等——行为与 Anthropic 不同的运行时才需要覆写,否则直接返回"不支持"。
这套"必选 + 可选"的划分很讲究:它既保证任何运行时都能被同一套流程驱动,又不强迫简单运行时去实现用不到的接口。每个 provider 的入口常量也统一:RUNTIME_ID、RUNTIME_NAME、DEFAULT_API_BASE(见 src/sdk/agents/types_runtime.rs)。
接入新运行时:三步,其他文件零改动
正因为差异被锁在适配器里,扩展成本极低。官方流程(src/sdk/AGENTS.md):
- 新建
sdk/providers/<name>/runtime/mod.rs; - 实现
RuntimeAdapter的 6 个必选方法,按需覆写可选方法; - 在 provider 的
mod.rs里调用registry.register(...)注册。
其余文件一行都不用改——不需要动路由、不需要动会话存储、不需要动 UI。
UI 层的"Add Runtime"甚至只是三个输入框:别名、API Spec、API Base/Key。选完即接——因为 UI 背后走的正是同一份统一契约。
一致性测试:用测试守护契约
更少见的是,LAP 把"目录结构"也写进了测试。tests/sdk_structure.rs 中的 sdk_tree_matches_provider_endpoint_contract 会在 CI 里断言:
src/sdk/transformations/目录不允许存在(历史遗留的散乱转换层被整体拆除);providers/mod.rs里不允许出现match runtime或AgentRuntime::分派;src/managed_agents/providers/不允许存在(运行时装配逻辑只属于sdk/providers/<provider>/runtime/)。
换句话说:如果有人图省事,把某个运行时特有的逻辑写进了公共层,测试会直接红。契约不只是文档约定,而是被 CI 强制执行的架构规则。
契约如何落到用户界面
统一契约的收益最终体现在产品层面。会话页面上,每个 session 都带着 runtime、agent、model 等上下文标签,右侧 Inspector 面板展示 system prompt 与会话状态——无论底层跑的是 OpenCode 还是 Claude,前端拿到的事件流完全同构(src/sdk/README.md):
为什么这个契约值得学
对 Agent 平台开发者来说,LAP 的 SDK 契约提供了三个可复用的模式:
- 参考形状选择:与其发明自己的 API,不如锚定一个领域内最有代表性的形状(这里是 Anthropic),认知成本最低;
raw逃生舱:标准化字段 + 原始响应并存,演进契约时不破坏已有调用方;- 结构测试守护架构:把"哪里不许出现什么代码"写成可执行断言,让契约可验证、可回归。
而这一切都运行在 Rust 实现的网关之上——LAP 对网关代理开销的定位是毫秒级的,抽象层不应该是性能税:
小结
LiteLLM Agent Control Plane 的"统一 SDK 契约"本质上是一次架构上的"收敛":入口收敛为四步流程,出口收敛为 Anthropic 形状的事件流,差异收敛到 sdk/providers/<provider>/runtime/ 这个目录里。想深入细节,建议按顺序读三份材料:契约文档 docs/engineering/sdk-api-contract.mdx、trait 定义 src/sdk/providers/base/runtime.rs、以及 Cursor 归一化示例 src/sdk/providers/cursor/runtime/mod.rs。当你自己需要对接多个异构 Agent 平台时,这套"一个形状 + 一个 trait + 一个结构测试"的组合拳,可以直接抄作业。



