ガードレール

ガードレールはエージェントと 並行して 実行され、ユーザー入力やエージェント出力に対するチェックや検証を行います。たとえば、コストの高いモデルを呼び出す前に、軽量モデルをガードレールとして実行できます。ガードレールが悪意ある使用を検知した場合は、エラーを発生させ、コストの高いモデルの実行を停止できます。

ガードレールには 2 種類あります:

入力ガードレール は初回のユーザー入力に対して実行されます
出力ガードレール は最終的なエージェント出力に対して実行されます

入力ガードレール

入力ガードレールは 3 段階で実行されます:

ガードレールはエージェントに渡されたものと同じ入力を受け取ります
ガードレール関数が実行され、InputGuardrailResult でラップされた GuardrailFunctionOutput を返します
tripwireTriggered が true の場合、InputGuardrailTripwireTriggered エラーがスローされます

注入力ガードレールはユーザー入力を対象としているため、ワークフロー内でエージェントが最初のエージェントである場合にのみ実行されます。ガードレールはエージェント自体に設定します。これは、エージェントによって必要なガードレールが異なることが多いためです。

出力ガードレール

出力ガードレールも同じパターンに従います:

ガードレールはエージェントに渡されたものと同じ入力を受け取ります
ガードレール関数が実行され、OutputGuardrailResult でラップされた GuardrailFunctionOutput を返します
tripwireTriggered が true の場合、OutputGuardrailTripwireTriggered エラーがスローされます

注出力ガードレールは、ワークフロー内でエージェントが最後のエージェントである場合にのみ実行されます。リアルタイムの音声対話については音声エージェントの構築を参照してください。

トリップワイヤー

ガードレールが失敗すると、トリップワイヤーによってそれを通知します。トリップワイヤーが発火するとすぐに、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);

guardrailAgent はガードレール関数内で使用されます
ガードレール関数はエージェントの入力または出力を受け取り、その結果を返します
追加情報をガードレール結果に含めることができます
agent はガードレールが適用される実際のワークフローを定義します