护栏

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

护栏有两种类型：

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

输入护栏

输入护栏分三步运行：

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

注意 输入护栏面向用户输入，因此只在该智能体是工作流中的第一个智能体时运行。护栏在智能体本身上配置，因为不同智能体通常需要不同的护栏。

执行模式

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

输出护栏

输出护栏分三步运行：

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

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

触发线（Tripwires）

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

护栏实现

护栏本质上是一个返回 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);

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