LiteLLM Agent Platform：让 AI 编程 Agent 在 Kubernetes 沙箱中安全运行

2026 年 5 月 8 日，BerriAI 开源了 LiteLLM Agent Platform（LAP）——一个基于 Kubernetes 的自托管基础设施，专门用于在生产环境中运行 AI 编程 Agent（如 Claude Code、OpenAI Codex、Gemini CLI 等）。

LAP 解决的核心问题很直接：如何在让 AI Agent 帮你写代码的同时，不把真正的 API 密钥暴露给它？

这篇文章将从架构设计、安全机制、会话管理和实战部署四个维度，拆解这个平台的完整技术实现。

本文大纲
- 为什么需要 Agent Platform
- 核心架构：五个组件的协作
- Vault Proxy：凭证隔离的关键设计
- 沙箱生命周期管理
- 支持的 Agent 类型
- 快速上手：三种部署方式
- 最新动态：5 月 29 日版本更新

为什么需要 Agent Platform

AI 编程 Agent 正在快速进入生产工作流。Claude Code 能理解整个代码库并直接提交 PR，Codex 能在终端中自主完成编码任务，opencode 能自动化 CI 流程。但它们都有一个共同的前提——需要 API 密钥才能运行。

这在生产环境中带来三个问题：

1. 凭证泄露风险：Agent 进程持有真实的 API 密钥，一旦被注入攻击或提示词注入，密钥可能被窃取
2. 团队隔离困难：不同团队使用不同的模型和密钥，如何在一个平台上安全地多租户运行
3. 会话持久化：Agent 任务可能需要数小时，Pod 重启或升级后如何保持会话状态

LAP 的回答是：把所有 Agent 关进 Kubernetes 沙箱里，用 Vault Proxy 做凭证代理，让 Agent 永远只看到"假"密钥。

核心架构：五个组件的协作

MERMAID_BLOCK_0

LAP 的架构由五个核心组件构成：

请求流程

完整的请求流程是这样的：

1. 客户端发起请求：用户通过 UI、CLI（lap 命令）或 API 发起会话
2. 创建 Sandbox CR：Web 服务创建一个 Sandbox 自定义资源，Controller 调度一个 Pod
3. Pod 启动：Pod 内包含 Vault Sidecar 和 Harness 容器，Stub 凭证注入到 Harness 的环境变量中
4. Agent 就绪：Harness 克隆代码仓库、安装依赖、监听协议（JSON API 或 PTY WebSocket）
5. 客户端连接：用户通过消息流或终端附件与 Agent 交互
6. 出站请求经过 Vault：Agent 的所有出站 HTTPS 请求都流经 Vault Sidecar，后者将 Stub 替换为真实密钥

这里最关键的设计是：真实密钥只存在于 Vault Sidecar 的进程内存中，从不进入 Agent 进程，从不被记录，从不被持久化。

Vault Proxy：凭证隔离的关键设计

Vault Proxy 是 LAP 最核心的安全机制。它作为一个 HTTPS 代理 Sidecar 运行在每个沙箱 Pod 中，拦截所有出站连接。

Stub 凭证机制

沙箱启动时，Harness 容器的环境变量中注入的是 Stub 凭证，而非真实密钥：

# Agent 看到的环境变量
GITHUB_TOKEN=stub_github_a8f1
LITELLM_API_KEY=stub_litellm_bb20

Agent 可以执行 echo $GITHUB_TOKEN，但只能看到 Stub 值。真实密钥只存在于 Vault Sidecar 的内存中。

替换流程

Agent 进程 ──(携带 stub)──> Vault Sidecar ──(替换为真密钥)──> 目标服务器

当 Vault Sidecar 在请求中检测到 Stub 凭证时，它会在数据包离开节点之前将其替换为真实值。目标服务器收到的是真实密钥，Agent 进程完全不知道替换发生过。

举个例子：

# Harness 发出的请求
Authorization: Bearer stub_litellm_bb20

# 到达 LiteLLM Gateway 的请求
Authorization: Bearer sk-real-litellm-key-xxxxxxxxx

这意味着即使 Agent 被提示词注入攻击、或者以 bypass-permissions 模式运行，它也无法窃取真实凭证——因为它根本没有。

保留环境变量

以下环境变量由 Vault 和 Harness 运行时管理，用户不能通过 API 设置（尝试设置会返回 400）：

REPO_URL, BRANCH, LITELLM_API_KEY, LITELLM_API_BASE,
LITELLM_DEFAULT_MODEL, AGENT_PROMPT, PORT, GIT_TOKEN,
AGENT_REQUIREMENTS

其中 GIT_TOKEN 仅在初始 git clone 时使用，随后被擦除。如果需要在 Agent Shell 中持久使用 Git 凭证（如 git push、gh pr create），应传入 GITHUB_TOKEN 或 GH_TOKEN——这些会通过 Vault 正常代理。

沙箱生命周期管理

每个沙箱就是一个 Kubernetes Pod，运行单个 Agent 会话。LAP 定义了清晰的生命周期状态：

空闲超时

一个处于 ready 状态的会话，如果 24 小时内没有任何交互，Worker 会自动回收 Pod，状态变为 dead。每次消息或终端操作都会重置倒计时。

对于 TUI 类 Agent（Claude Code、Codex），按 Ctrl-D 可以脱离会话而不终止它——会话保持活跃，下次运行 lap <agent-name> 即可重新连接。

每会话环境变量

可以为每个会话注入短期密钥（Vault 代理但不持久化）：

curl -s $LAP_URL/api/v1/managed_agents/agents/$AGENT_ID/session \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "open a PR",
    "env_vars": {
      "GITHUB_TOKEN": "ghp_...",
      "CIRCLECI_TOKEN": "cci_..."
    }
  }'

限制条件：最多 50 个 key，总量不超过 16 KB，key 命名符合 ^[A-Za-z_][A-Za-z0-9_]*$，且不能与保留 key 重叠。

支持的 Agent 类型

LAP 开箱即支持六种 Agent Harness：

TUI 类 Harness（Claude Code、Codex）通过 lap 命令附加终端。API 类 Harness 通过 POST /sessions/{id}/message 发送消息。

创建 Agent

通过 API 创建一个 Claude Code Agent：

curl -X POST $LAP_URL/api/v1/managed_agents/agents \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-claude","harness_id":"claude-code","model":"anthropic/claude-sonnet-4"}'

快速上手：三种部署方式

方式一：本地开发（无 Kubernetes）

最快的方式是跳过 Kubernetes，直接在本地运行 Harness。适用于 claude-agent-sdk 和 opencode 这类 HTTP JSON API 的 Agent。

git clone https://github.com/BerriAI/litellm-agent-platform.git
cd litellm-agent-platform
cp .env.example .env
# 编辑 .env 填入 DATABASE_URL、MASTER_KEY、LITELLM_API_BASE、LITELLM_API_KEY

# 终端 1 — 启动平台
npm install && npm run dev          # http://localhost:3000

# 终端 2 — 启动 Harness
cd harnesses/claude-agent-sdk
npm install && npm run build
REPO_DIR=/path/to/repo \
LITELLM_API_BASE=https://gateway.litellm.ai/ \
LITELLM_API_KEY=sk-... \
node dist/server.js                 # http://localhost:4096

设置 LOCAL_SANDBOX_URL=http://localhost:4096 和 WARM_POOL_SIZE=0 让平台跳过 Kubernetes，所有会话路由到本地 Harness。会话在 2 秒内进入 ready 状态。

方式二：本地 Kubernetes（kind）

适用于需要 TTY Harness（Claude Code、Codex）或想匹配生产行为的场景。

git clone https://github.com/BerriAI/litellm-agent-platform.git
cd litellm-agent-platform
cp .env.example .env
bin/kind-up.sh        # 创建 kind 集群、安装 Sandbox Controller、加载 Harness 镜像
docker compose up     # 启动 Postgres、运行迁移、启动 Web + Worker

bin/kind-up.sh 是幂等的——创建名为 agent-sbx 的 kind 集群，安装 Sandbox Controller，加载 Harness 镜像。

方式三：生产部署（AWS EKS）

推荐的生产配置是 EKS 作为沙箱集群，Render 托管 Web + Worker。

bin/eks-up.sh    # 创建 EKS 集群，配置正确的节点组和 Sandbox Controller

然后通过 Render Blueprint 一键部署 Web + Worker。

生产环境必需的环境变量：

最新动态：5 月 29 日版本更新

LAP 保持每周发布节奏。5 月 29 日的更新带来了多项重要功能：

Daytona Sandbox Provider

除了 Kubernetes Pod，现在可以在 Daytona 上运行 Agent 沙箱，为 opencode inline harness 提供更多运行选择。

S3 工件存储

Agent 在沙箱中生成的文件现在会上传到 S3（支持 Cloudflare R2 等自定义端点），并在会话视图中展示。Agent 还可以通过 upload_artifact MCP 工具主动发布文件并获取可分享链接。

setup.sh 约定

在连接的代码仓库根目录放置 setup.sh，沙箱会在创建时自动执行。可以在 UI 中编辑，或让 Agent 通过 lap_update_sandbox_setup 工具更新。

opencode Inline Harness

全新的共享 inline opencode harness，无需为每个 Agent 分配独立 Pod——Skills、MCP 工具、System Prompt 和 Memory 都可以跨会话复用。Linear、Slack、GitHub 等 MCP Server 开箱即用。

每个 Agent 的出站白名单

每个 Agent 可以声明它需要访问的主机列表，Vault 的凭证替换只作用于白名单内的主机。这让安全边界更加精细。

Reviewer Agent

Reviewer 现在作为真正的 LAP Agent 会话运行，能对正在监听的会话进行主动评估和日志分析。

其他亮点

• 中断运行中的 Turn：从会话视图中停止长时间运行的 Agent Turn，无需终止沙箱
• 图片附件：粘贴截图、拖拽文件或附加图片到聊天中
• 屏幕录制：Claude Agent SDK Agent 内置屏幕录制工具
• 实时预览：编码 Agent 会话中提供 "View Preview" 按钮，直接查看沙箱中运行的应用
• Lazy Sandbox：Agent 大脑在平台上运行，只在真正需要时才启动沙箱 Pod——首 Turn 更快，空闲成本更低

选择 Kubernetes 的理由

LAP 选择 Kubernetes 而非自建容器编排，有三个核心原因：

1. 可移植性：本地用 kind，生产用 EKS / GKE / AKS / 自建机房，无缝切换
2. 安全原语：Pod 级隔离、RBAC、Network Policy 都是现成的
3. 强隔离运行时：通过 CRD 的 runtimeClass 字段，可以启用 gVisor 或 Kata Containers，获得比普通 Pod 更强的隔离能力

这意味着没有云厂商锁定——沙箱运行时路径完全自主可控。

小结

LiteLLM Agent Platform 为 AI 编程 Agent 的生产部署提供了一个完整的基础设施方案。它的核心设计理念是：

• 凭证永远不暴露：Vault Proxy 在网络层做替换，Agent 进程只看到 Stub
• 沙箱级隔离：每个 Agent 会话运行在独立的 Kubernetes Pod 中
• 会话持久化：24 小时空闲超时、Ctrl-D 脱离/重连、滚动部署不丢进度
• 多 Agent 支持：Claude Code、Codex、opencode、Gemini、Hermes 六种 Harness 开箱即用

对于正在将 AI 编程 Agent 引入团队工作流的组织来说，LAP 提供了一个值得关注的起点——开源、自托管、安全可控。

项目地址：github.com/BerriAI/litellm-agent-platform
文档地址：docs.litellm-agent-platform.ai

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/
每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。