给 AI Agent 装“刹车”：SteerPlane 如何把预算、循环与危险操作收进同一条运行时控制线
给 Agent 加权限通常不难：给模型一组工具、放开网络、接上数据库，再让它自行规划。但真正棘手的是运行中失控。一个错误的提示词、重试条件或工具返回值，可能让它重复同一动作；一个没有上限的任务，也可能持续消耗模型额度。更危险的是，事后从日志里看到事故，并不能阻止已经执行的删除、提权或外部调用。
SteerPlane 是一个 MIT 许可证的 Python/Node.js 项目，定位为 Agent 的运行时控制平面。它把成本上限、步数限制、循环检测、动作策略和运行记录放在 Agent 执行路径上。项目提供 Python SDK、TypeScript SDK、OpenAI 兼容网关、CLI、FastAPI 服务与可视化面板；截至本文核查，PyPI 与 npm 的最新版本均为 0.4.1，Python 端要求 3.10+。
它适合处理的不是“模型回答得对不对”，而是另一类工程问题：即使 Agent 的判断出了偏差，系统怎样尽快、可预测地停止它？
先区分三种不同的失控
成本、循环和权限不是同一个问题，不能只用一个“最大 token”参数覆盖。
- 预算失控：Agent 一直调用模型、检索或外部 API。SteerPlane 可按单次运行设置美元上限；网关模式则可按会话统计。README 明确说明检查发生在每一步之后，因此超额范围最多落在单步内。
- 行为循环：模型可能重复一个动作，也可能在两个或多步之间往复。SteerPlane 的循环检测基于滑动窗口，不需要再调用模型来判断循环，这对“坏状态下继续花钱诊断”的场景尤其重要。
- 不应发生的动作：即使预算尚未耗尽，
delete_、sudo_这类工具动作也不该被允许。策略引擎按拒绝列表、允许列表、限速的顺序评估，先挡住禁止操作，再决定其他操作是否可继续。
这些限制最好作为应用边界的一部分，而不是写在提示词里。提示词可以要求模型谨慎，但不能提供强制执行语义。
用装饰器把限制贴在 Agent 入口
Python SDK 的最小接入方式是 @guard。下面的配置使用 README 已展示的字段：它限制一次支持 Agent 最多 50 步、10 美元，并拒绝匹配危险模式的动作。
from steerplane import guard
@guard(
agent_name="support_bot",
max_cost_usd=10.00,
max_steps=50,
denied_actions=["delete_*", "sudo_*"],
enforcement="alert",
alert_threshold=0.8,
alert_timeout_sec=1800,
)
def run_agent():
agent.run()
这里有一个容易忽略的部署边界：开源自托管免费层运行的是 kill mode，违反限制时立即终止。示例中的 alert 选项可以由 SDK 暴露，但“暂停、通知人工、批准或拒绝”的完整工作流属于 hosted/enterprise 部署；若把 alert 配置指向免费自托管 API，它会失败关闭（终止运行），而不是在没有保护的情况下继续执行。
如果你不希望每个 Agent 函数都重复写参数，可在项目根目录放置 .steerplane.yml。项目说明的合并优先级是：显式装饰器参数优先，其次是配置文件，最后才是内置默认值。这样可以把团队的预算和动作策略纳入代码审查。
api_url: http://localhost:8000
agent_name: support_bot
defaults:
max_cost_usd: 25.0
max_steps: 100
max_runtime_sec: 1800
policy:
denied_actions:
- "delete_*"
- "drop_*"
rate_limits:
- pattern: "search_*"
max_count: 10
window_seconds: 60
不方便改 Agent 源码时，用网关收口
第三方框架、遗留服务或多个团队维护的 Agent，往往无法都改成装饰器接入。SteerPlane 的另一条路径是 OpenAI 兼容网关：客户端只把 base_url 指向本地网关，模型请求在转发前经过策略、成本和循环检查。
import os
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/gateway/v1",
api_key=os.environ["STEERPLANE_API_KEY"],
default_headers={"X-LLM-API-Key": os.environ["PROVIDER_API_KEY"]},
)
README 描述该网关支持 OpenAI 与 Anthropic 的流式转发，并能在流式过程中因成本越界截断连接。它的关键价值不只是“换一个地址”：应用使用 SteerPlane API key 完成网关认证，提供商密钥随请求交给网关；网关在允许后再向上游转发。要让这条控制线有意义，网络层还应避免 Agent 直接绕过网关访问模型提供商，否则预算与策略只能覆盖部分流量。
用可观测性验证“刹车”真的接上了
部署后不要只看配置文件。先运行一个低成本的演练任务，再用 CLI 确认服务、运行记录和逐步事件是否出现：
pip install "steerplane[cli]" steerplane status steerplane runs list steerplane runs inspect RUN_ID
对于高风险工具，建议在非生产环境故意触发一次拒绝规则，并检查运行记录是否标出策略违规；再设置很小的 max_steps，确认会在预期步数停止。这样验证的是控制面是否真的位于调用路径，而不是仅验证 Python 包可以导入。
SteerPlane 也有取舍。它能对已知的调用、成本和动作模式做确定性拦截，却不能替代业务授权模型：例如“哪个客户的数据允许导出”“这笔退款是否合理”，仍需由你的工具服务、RBAC 和人工审批流程决定。其循环检测也只能识别运行轨迹中的重复结构，不能保证识别所有语义上无价值的任务。
不过，对已开始赋予 Agent 网络、命令和数据访问能力的团队而言，把预算上限、循环终止、动作策略与运行记录放在同一条强制路径上，是比继续加长系统提示词更可靠的第一步。
把控制规则拆成可测试的层次
实际落地时，最容易犯的错是把所有限制都设成一个很大的“全局阈值”。更稳妥的做法是把规则按不可逆程度分层：先阻止不允许的操作，再限制频率和资源，最后为可恢复的业务动作保留人工决策空间。
例如，delete_ 与 sudo_ 适合进入拒绝列表，因为它们的后果通常需要独立授权；search_* 一类读操作则可配合滑动窗口限速，防止 Agent 因检索结果为空而高频重试。若团队已经梳理出可执行工具清单，再增加允许列表：一旦设置，动作必须匹配其中至少一条规则才会继续。README 给出的优先顺序是拒绝列表、允许列表、限速，因此策略设计应先检查规则是否互相矛盾，避免一个本应可用的工具被过宽的模式误伤。
成本限制也建议按任务拆分。交互式客服、离线批处理和代码迁移的可接受成本并不相同；把它们全部放在每月总预算下，会让短任务的异常消耗难以及时暴露。优先在单次运行设置 max_cost_usd 与 max_steps，再让网关层负责会话级控制。这样告警或终止时，记录会更接近真正的失败单元：某一次任务，而不是一整天的模糊总量。
失败模式：控制面本身也需要演练
运行时护栏不是部署完就自动可靠。至少要把以下几类检查写进集成测试或上线清单。
第一，确认旁路不可达。若应用既配置了网关地址，又保留可直连上游模型的网络出口或备用客户端，真正压力来临时很可能绕过控制面。对不改代码的 Agent，网关模式的价值取决于网络策略、环境变量和 SDK 初始化是否都指向同一个入口。
第二，确认终止后的业务补偿。SteerPlane 可以中断运行，但它无法替你撤销已完成的外部副作用。调用支付、发邮件、写数据库的工具应设计幂等键、事务状态或补偿接口；被终止的 Agent 下次恢复时，先读取状态而不是盲目重做。
第三，确认降级语义符合风险偏好。项目说明 SDK 在 API 不可用时仍在本地执行限制，这有助于避免控制服务短暂不可达就让 Agent 裸奔。但团队仍要明确哪些限制必须本地可执行，哪些依赖服务端状态；尤其是多人共享预算、跨进程限速等问题，不能只靠单进程内存判断。
最后，区分运行时策略和质量评估。SteerPlane 能阻止超额、循环和违反规则的调用，却不会判断一段生成的 SQL 是否符合业务含义，也不会替代测试、审查或权限审批。把它接在执行路径上，是为了缩小错误的爆炸半径；质量门、RBAC 与审计则仍应在前后两端协同工作。