护栏

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

护栏有两种类型：

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

输入护栏

输入护栏分三步运行：

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

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

输出护栏

输出护栏遵循相同模式：

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

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

绊线

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

护栏实现

护栏就是一个返回 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 定义应用护栏的实际工作流。