LiteLLM Agent Control Plane 统一 SDK 契约详解:为何所有运行时都长成一个 Anthropic 形状

原创2026-10-13 16:57:381,671 阅读

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."(流程对所有运行时完全一致,调用代码里不出现任何按运行时分支的块。)

LiteLLM Agent Control Plane 运行时选择界面:同一个界面下可切换 Claude、OpenCode 等不同 Agent 运行时

一个"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):

  1. 新建 sdk/providers/<name>/runtime/mod.rs;
  2. 实现 RuntimeAdapter 的 6 个必选方法,按需覆写可选方法;
  3. 在 provider 的 mod.rs 里调用 registry.register(...) 注册。

其余文件一行都不用改——不需要动路由、不需要动会话存储、不需要动 UI。

LiteLLM Agent Control Plane 添加运行时对话框:只需选择 API Spec(如 claude_managed_agents)、填写 API Base 和 Key

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):

LiteLLM Agent Control Plane 会话界面:同一套界面展示任意运行时的 Agent 会话事件流

为什么这个契约值得学

对 Agent 平台开发者来说,LAP 的 SDK 契约提供了三个可复用的模式:

  • 参考形状选择:与其发明自己的 API,不如锚定一个领域内最有代表性的形状(这里是 Anthropic),认知成本最低;
  • raw 逃生舱:标准化字段 + 原始响应并存,演进契约时不破坏已有调用方;
  • 结构测试守护架构:把"哪里不许出现什么代码"写成可执行断言,让契约可验证、可回归。

而这一切都运行在 Rust 实现的网关之上——LAP 对网关代理开销的定位是毫秒级的,抽象层不应该是性能税:

LLM 网关代理开销对比:Rust 实现的 litellm-rust 仅 0.05ms 代理开销

小结

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 + 一个结构测试"的组合拳,可以直接抄作业。

登录后查看全文
litellm-agent-control-plane