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 里。