如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 恢復執行。如果要延後審查,請儲存序列化後的狀態,待收到審查決定後再繼續同一次執行。

後續步驟

釐清各項控制機制的適用範圍後,請接著閱讀相關執行環境或工具介面的指南。