SteerPlane：为AI代理提供开源运行时护栏

SteerPlane 是一个开源的运行时护栏工具，旨在为 AI 代理提供安全性和可控性。随着 AI 代理能够调用 API、执行代码、浏览网络并做出实际决策，它们也带来了潜在的风险：一个配置错误的代理可能陷入无限循环，一夜之间消耗超过 10,000 美元的 API 费用，或者在没有任何可见性的情况下执行破坏性操作。SteerPlane 通过一行代码即可解决这些问题。

工作原理

SteerPlane 提供了 Python 装饰器和上下文管理器两种 API。使用 @guard 装饰器，开发者可以指定代理名称、最大成本（如 10.00 美元）、最大步骤数（如 50）、禁止操作（如 delete_*）和执行模式。在代理运行时，SteerPlane 会静默监控每一步，当达到财务或运行时限制时，可以暂停等待人工审批，而循环和策略违规则会立即终止。

核心功能

• 循环检测：使用 O(W²) 滑动窗口算法，在亚毫秒时间内检测单动作、交替和多步重复模式，无需调用 LLM。
• 成本上限：每个运行（SDK）或每个会话（网关）设置美元限制，每一步后检查，超限仅多一步。内置 25+ 模型（OpenAI、Anthropic、Google、Meta、Mistral）的定价。
• 流媒体网关：实时 SSE 块转发，支持流中段成本中止——如果预算在流中超出，SteerPlane 注入终止事件并切断连接。
• 策略引擎：支持允许/拒绝列表（glob 模式）和滑动窗口速率限制。
• 网关代理：兼容 OpenAI 的 API 代理，只需更改 base_url 即可实现零代码策略执行。代理通过网关传递其提供商的密钥，所有流量在转发前经过强制检查。
• 实时仪表板：基于 Next.js，提供自动刷新、动画时间线、成本分解和策略管理。
• CLI 工具：管理运行、状态、密钥等。
• 配置文件：.steerplane.yml 自动发现，无需在源代码中硬编码限制。
• 框架集成：支持 LangChain、OpenAI Agents SDK、CrewAI 和 AutoGen，零配置即插即用。
• Docker Compose：一键启动 API、Dashboard 和 PostgreSQL。
• 优雅降级：API 不可用时，SDK 在本地执行所有限制，代理永不无保护。

部署方式

推荐使用 Docker：克隆仓库，复制环境变量文件，然后运行 docker compose up -d。API 运行在 localhost:8000，Dashboard 在 localhost:3000，PostgreSQL 自动配置。也可手动安装 SDK 并启动 API 和 Dashboard，或使用 CLI 工具。

框架集成示例

• LangChain：使用 SteerPlaneCallbackHandler 作为回调，传入 agent_name、max_cost_usd 等参数。
• OpenAI Agents SDK：通过 SteerPlaneAgentHooks 包装代理的生命周期。
• CrewAI：使用 SteerPlaneCrewMonitor 并设置 step_callback。
• AutoGen：使用 SteerPlaneAutoGenMonitor 启动聊天。

网关代理（零代码模式）

对于无法修改的代理，SteerPlane 提供兼容 OpenAI 的网关代理，支持实时流和中段成本强制。代理只需将 base_url 指向网关，并在请求头中传递真实的提供商密钥。网关认证 SteerPlane 密钥后，先执行策略、成本和循环检测，再转发请求。

策略引擎

策略引擎在产生任何成本之前运行，按严格优先级顺序执行：拒绝列表 → 允许列表 → 速率限制。拒绝列表使用 glob 模式，任意匹配立即阻止；允许列表若设置，动作必须匹配至少一个模式才能继续；速率限制使用滑动窗口计数器，超过阈值后阻止。

执行模式

自托管免费版采用终止模式：任何违规立即确定性地终止。SDK 还提供 enforcement="alert" 选项（暂停 → 通知人工 → 批准/拒绝/延长 → 超时自动终止），这需要托管/企业版的后端支持。指向免费自托管 API 时，警报模式安全地终止运行并返回错误。

循环检测和策略违规始终触发立即终止，无论执行模式如何，这些是不可覆盖的安全约束。

SteerPlane 的开源 SDK 和免费自托管版为开发者提供了强大的运行时控制，而托管/企业版则增加了人工审批工作流、服务端密钥保管和 Redis 支持的多工作者网关状态。