护栏

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

护栏有两种类型：

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

输入护栏

输入护栏分三步运行：

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

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

输出护栏

输出护栏分三步运行：

1. 护栏接收由智能体产生的输出。
2. 护栏函数执行并返回一个 GuardrailFunctionOutput，该对象被包裹在 OutputGuardrailResult 中。
3. 如果 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',
  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 定义应用护栏的实际工作流。