如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

护栏与人工审查

在 SDK 工作流中加入自动验证和人工审批。

使用护栏执行自动检查,通过人工审查决定是否批准操作。两者共同决定一次运行何时继续、暂停或停止。

  • 护栏会自动验证输入、输出或工具行为。
  • 人工审查会暂停运行,以便由审查人员或策略决定批准还是拒绝敏感操作。

选择合适的控制机制

使用场景 优先使用
在主模型运行前拦截不允许的用户请求 输入护栏
在最终输出离开系统前验证其内容或遮盖敏感信息 输出护栏
检查函数工具调用的参数或结果 工具护栏
在执行会产生副作用的操作前暂停,例如取消、编辑、运行 shell 命令或执行敏感 MCP 操作 人工审批

添加阻塞式护栏

如果您希望在工作流进入开销较大或会产生副作用的环节前先做一次快速验证,请使用输入护栏。

使用输入护栏拦截请求
import { Agent, InputGuardrailTripwireTriggered, run } from "@openai/agents";
import { z } from "zod";

const guardrailAgent = new Agent({
  name: "Homework check",
  instructions: "Detect whether the user is asking for math homework help.",
  outputType: z.object({
    isMathHomework: z.boolean(),
    reasoning: z.string(),
  }),
});

const agent = new Agent({
  name: "Customer support",
  instructions: "Help customers with support questions.",
  inputGuardrails: [
    {
      name: "Math homework guardrail",
      runInParallel: false,
      async execute({ input, context }) {
        const result = await run(guardrailAgent, input, { context });
        return {
          outputInfo: result.finalOutput,
          tripwireTriggered: result.finalOutput?.isMathHomework === true,
        };
      },
    },
  ],
});

try {
  await run(agent, "Can you solve 2x + 3 = 11 for me?");
} catch (error) {
  if (error instanceof InputGuardrailTripwireTriggered) {
    console.log("Guardrail blocked the request.");
  } else {
    throw error;
  }
}

如果启动主智能体的成本或风险过高,请使用阻塞式执行。如果降低延迟更重要,且可以接受在验证结果出来前就开始执行任务,请使用并行护栏。

暂停运行以进行人工审查

通过审批机制,您可以在工具调用执行前进行人工审查。模型仍可判断需要执行某项操作,但运行会暂停,直到您批准或拒绝该操作。

在执行敏感操作前暂停并等待审批
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const cancelOrder = tool({
  name: "cancel_order",
  description: "Cancel a customer order.",
  parameters: z.object({ orderId: z.number() }),
  needsApproval: true,
  async execute({ orderId }) {
    return `Cancelled order ${orderId}`;
  },
});

const agent = new Agent({
  name: "Support agent",
  instructions: "Use cancel_order to handle cancellation requests.",
  tools: [cancelOrder],
});

let result = await run(agent, "Cancel order 123.");

if (result.interruptions?.length) {
  const state = result.state;
  for (const interruption of result.interruptions) {
    console.log(`Approval required: ${interruption.name}`);
    state.approve(interruption);
  }
  result = await run(agent, state);
}

console.log(result.finalOutput);

即使需要审批的工具位于工作流更深处,例如在智能体交接之后,或在嵌套的 agent.asTool() 调用中,也适用同样的中断机制。

审批生命周期

每当工具调用需要审查时,SDK 都会按以下流程处理:

  1. 运行会记录一次审批中断,暂缓执行工具。
  2. 返回的结果包含 interruptions 和可用于恢复运行的 state。
  3. 您的应用批准或拒绝待审批项。
  4. 您从 state 恢复同一次运行,无需开始新一轮用户交互。

如果审查可能需要一段时间,请将 state 序列化并保存,稍后再恢复。恢复后仍是同一次运行。

护栏在工作流中的作用范围

智能体级护栏只在特定环节运行:

  • 输入护栏仅针对调用链中的第一个智能体运行。
  • 输出护栏仅针对生成最终输出的智能体运行。
  • 工具护栏仅针对已关联的函数工具运行。

如果您需要在由管理智能体协调的工作流中检查每一次自定义工具调用,请勿仅依赖智能体级的输入或输出护栏。请在会产生副作用的工具处执行验证。

在执行前审查网络安全操作

对于已获授权的网络安全工作流,请在执行每次敏感工具调用前对其进行评估。在可能产生副作用的环节,使用工具护栏和审批中断,确保操作符合书面约定的授权范围:

  1. 对照已批准的范围,核查拟操作的目标、拟执行的操作、工具参数、调用方身份和作业时间窗口。
  2. 向独立的策略组件或审查人员提供拟执行操作的确切内容,并仅提供评估该操作所需的上下文。
  3. 拒绝访问授权范围外的主机,禁止窃取凭据、建立持久化访问、外传数据、实施破坏性更改、访问生产环境或尝试绕过策略。
  4. 对于含义不明确或风险较高的操作,请暂停执行,待人工明确批准后再运行工具。
  5. 分别强制执行文件系统、网络、身份和项目的边界限制,记录审批决定和执行结果。如果审查超时或无法进行,则拒绝执行。

使用 Responses API 和 Agents SDK 的应用不会自动继承 Codex 自动审查功能。请在您自己的执行框架中加入审查和策略执行机制。Codex 开源审查策略展示了一种实现方式。请参阅模型与可信访问了解获批的模型访问权限,并参阅推荐配置了解如何安全地配置网络安全作业环境。

流式运行和延后审查使用相同的状态模型

流式运行沿用同一套审批机制。如果流式运行暂停,请等它进入稳定状态,再检查 interruptions,处理待审批项,并从同一 state 恢复运行。如果稍后才进行审查,请保存序列化后的状态,待审批决定作出后继续同一次运行。

后续步骤

明确各项控制机制的作用范围后,您可以继续阅读相应指南,了解相关的运行机制或工具接口。