agent 跑长任务时,最难的不是让它开始,而是让它在该停的时候真的停。OpenAI 11 月公开的 Control Room 给了三个可以照抄的设计:每个作业有 id、每次采样前先问许可、闸门自己挂了就默认拒绝。这篇教程用一百多行代码把这个结构做出来,并给出三个必须测的场景。
先定三条规则
第一,作业必须有身份:启动时向闸门注册,拿到 job_id,之后所有调用都带着它。第二,授权放在动作之前,不是放在事后审计里——工具调用、模型采样、写文件,每一次都问一遍。第三,fail-closed:闸门不可达、超时、返回 5xx,一律当作拒绝。第三条最容易被写成「失败时放行」,那等于没有闸门。
第一步:作业注册与状态机
最小实现只需要一个字典加一把锁。状态只有 active 和 stopped,停止时记下时间和原因,便于事后追责。
import threading, time, uuid
class ControlRoom:
def __init__(self):
self._jobs = {}
self._lock = threading.Lock()
def register(self, purpose):
job_id = f"job_{uuid.uuid4().hex[:8]}"
with self._lock:
self._jobs[job_id] = {"purpose": purpose, "state": "active"}
return job_id
def stop(self, job_id, reason):
with self._lock:
job = self._jobs[job_id]
job["state"] = "stopped"
job["stopped_at"] = time.time()
job["reason"] = reason
def authorize(self, job_id):
with self._lock:
job = self._jobs.get(job_id)
return bool(job and job["state"] == "active")第二步:把授权插在工具调用前
不要在每个工具函数里各写一遍检查——包一层,所有调用都走它。这样新增工具时不会漏。
class Denied(Exception):
pass
def guarded_call(room, job_id, tool, *args, **kwargs):
if not room.authorize(job_id):
raise Denied(f"{job_id} 已停止,拒绝调用 {tool.__name__}")
return tool(*args, **kwargs)
# 用法
result = guarded_call(room, job_id, fetch_page, url)第三步:fail-closed 不是一句口号
闸门跑在另一个进程或另一台机器上时,客户端必须把超时和连接失败都算成拒绝。下面这段是所有实现里最容易写错的地方:except 分支必须 return False,不能 return True。
import requests
def authorize_remote(job_id, base="http://127.0.0.1:8787", timeout=0.5):
try:
r = requests.get(f"{base}/authorize/{job_id}", timeout=timeout)
return r.status_code == 200 and r.json().get("allowed") is True
except Exception:
return False # 超时、连不上、5xx 一律拒绝第四步:审计日志要能回答三个问题
日志不是给人看的流水账,要能回答:谁下的停止指令、什么时候生效、停止前这个作业调了哪些工具。每次授权请求记一行(job_id、工具名、时间、结果),停止指令单独记一条,别混在一起。真出事时,这三样决定了你能不能解释清楚模型到底做了什么。
三个必须测的场景
一是正常路径:作业跑完,授权全通过,日志里没有拒绝记录。二是中途停止:作业跑到一半调用 stop,下一次工具调用必须立刻抛 Denied,且不再产生任何输出。三是闸门被杀掉:直接 kill -9 闸门进程,客户端必须在超时后拒绝,而不是卡住或放行。第三个场景最常被跳过,也最接近真实故障。
上线前的检查清单
每个 agent 作业都要有 job_id 与对应的用途说明;所有外部动作统一走包装函数;客户端超时小于业务重试间隔;闸门故障时的行为写在架构文档里;日志能按 job_id 还原全部工具调用;停机的实测时间写进 SLA,而不是写在 PPT 里。