护栏

护栏可以与您的智能体并行运行，或在其完成前阻塞执行，从而对用户输入或智能体输出进行检查与校验。例如，您可以在调用昂贵模型前先运行一个轻量模型作为护栏。如果护栏检测到恶意使用，它可以触发错误并阻止昂贵模型运行。

护栏分为两类：

输入护栏 运行在初始用户输入上。
输出护栏 运行在最终智能体输出上。

输入护栏

输入护栏分三步运行：

护栏接收与智能体相同的输入。
护栏函数执行并返回一个封装在InputGuardrailResult中的GuardrailFunctionOutput。
如果 tripwireTriggered 为 true，则抛出一个InputGuardrailTripwireTriggered 错误。

Note 输入护栏面向用户输入，因此仅当该智能体是工作流中的第一个智能体时才会运行。护栏在智能体上进行配置，因为不同智能体通常需要不同的护栏。

执行模式

runInParallel: true（默认）会在 LLM/工具调用的同时启动护栏。这样可最小化延迟，但如果护栏之后触发，模型可能已经消耗了 tokens 或运行了工具。
runInParallel: false 会在调用模型之前运行护栏，当护栏阻止请求时可避免 token 消耗与工具执行。当您更看重安全与成本而非延迟时使用此模式。

输出护栏

输出护栏分三步运行：

护栏接收由智能体产生的输出。
护栏函数执行并返回一个封装在OutputGuardrailResult中的GuardrailFunctionOutput。
如果 tripwireTriggered 为 true，则抛出一个OutputGuardrailTripwireTriggered 错误。

Note 仅当该智能体是工作流中的最后一个智能体时，输出护栏才会运行。有关实时语音交互，请参阅构建语音智能体。

触发线

当护栏失败时，它会通过触发线发出信号。一旦触发线被触发，runner 会抛出相应错误并停止执行。

护栏实现

护栏就是一个返回 GuardrailFunctionOutput 的函数。下面是一个最小示例：通过在幕后运行另一个智能体来检查用户是否在请求数学作业帮助。

import {
  Agent,
  run,
  InputGuardrailTripwireTriggered,
  InputGuardrail,
} from '@openai/agents';
import { z } from 'zod';

const guardrailAgent = new Agent({
  name: 'Guardrail check',
  instructions: 'Check if the user is asking you to do their math homework.',
  outputType: z.object({
    isMathHomework: z.boolean(),
    reasoning: z.string(),
  }),
});

const mathGuardrail: InputGuardrail = {
  name: 'Math Homework Guardrail',
  // Set runInParallel to false to block the model until the guardrail completes.
  runInParallel: false,
  execute: async ({ input, context }) => {
    const result = await run(guardrailAgent, input, { context });
    return {
      outputInfo: result.finalOutput,
      tripwireTriggered: result.finalOutput?.isMathHomework ?? false,
    };
  },
};

const agent = new Agent({
  name: 'Customer support agent',
  instructions:
    'You are a customer support agent. You help customers with their questions.',
  inputGuardrails: [mathGuardrail],
});

async function main() {
  try {
    await run(agent, 'Hello, can you help me solve for x: 2x + 3 = 11?');
    console.log("Guardrail didn't trip - this is unexpected");
  } catch (e) {
    if (e instanceof InputGuardrailTripwireTriggered) {
      console.log('Math homework guardrail tripped');
    }
  }
}

main().catch(console.error);

输出护栏的工作方式相同。

import {
  Agent,
  run,
  OutputGuardrailTripwireTriggered,
  OutputGuardrail,
} from '@openai/agents';
import { z } from 'zod';

// The output by the main agent
const MessageOutput = z.object({ response: z.string() });
type MessageOutput = z.infer<typeof MessageOutput>;

// The output by the math guardrail agent
const MathOutput = z.object({ reasoning: z.string(), isMath: z.boolean() });

// The guardrail agent
const guardrailAgent = new Agent({
  name: 'Guardrail check',
  instructions: 'Check if the output includes any math.',
  outputType: MathOutput,
});

// An output guardrail using an agent internally
const mathGuardrail: OutputGuardrail<typeof MessageOutput> = {
  name: 'Math Guardrail',
  async execute({ agentOutput, context }) {
    const result = await run(guardrailAgent, agentOutput.response, {
      context,
    });
    return {
      outputInfo: result.finalOutput,
      tripwireTriggered: result.finalOutput?.isMath ?? false,
    };
  },
};

const agent = new Agent({
  name: 'Support agent',
  instructions:
    'You are a user support agent. You help users with their questions.',
  outputGuardrails: [mathGuardrail],
  outputType: MessageOutput,
});

async function main() {
  try {
    const input = 'Hello, can you help me solve for x: 2x + 3 = 11?';
    await run(agent, input);
    console.log("Guardrail didn't trip - this is unexpected");
  } catch (e) {
    if (e instanceof OutputGuardrailTripwireTriggered) {
      console.log('Math output guardrail tripped');
    }
  }
}

main().catch(console.error);

guardrailAgent 在护栏函数内部使用。
护栏函数接收智能体输入或输出并返回结果。
可以在护栏结果中包含额外信息。
agent 定义应用护栏的实际工作流。