コンテンツにスキップ

ガードレール

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

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

  1. Input guardrails は最初のユーザー入力に対して実行されます
  2. Output guardrails は最終的なエージェント出力に対して実行されます

Input guardrails は次の 3 ステップで実行されます:

  1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります
  2. ガードレール関数が実行され、 GuardrailFunctionOutputInputGuardrailResult にラップして返します
  3. tripwireTriggeredtrue の場合、 InputGuardrailTripwireTriggered エラーがスローされます

Note
Input guardrails はユーザー入力向けであるため、ワークフロー内でエージェントが 最初の エージェントである場合にのみ実行されます。ガードレールはエージェント自身に設定します。エージェントごとに必要なガードレールが異なることが多いためです。

Output guardrails も同じパターンに従います:

  1. ガードレールはエージェントに渡されたものと同じ入力を受け取ります
  2. ガードレール関数が実行され、 GuardrailFunctionOutputOutputGuardrailResult にラップして返します
  3. tripwireTriggeredtrue の場合、 OutputGuardrailTripwireTriggered エラーがスローされます

Note
Output guardrails はワークフロー内でエージェントが 最後の エージェントである場合にのみ実行されます。リアルタイム音声インタラクションについては 音声エージェントの構築 を参照してください。

ガードレールが失敗すると、トリップワイヤーによってそれが通知されます。トリップワイヤーが作動すると直ちにランナーが対応するエラーをスローし、実行を停止します。

ガードレールは GuardrailFunctionOutput を返す単なる関数です。以下は、内部で別のエージェントを実行してユーザーが数学の宿題の助けを求めているかどうかを判定する最小限の例です。

Input guardrail example
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);

Output guardrails も同じ方法で動作します。

Output guardrail example
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. 追加情報を guardrail 結果に含めることができます
  4. agent がガードレールを適用する実際のワークフローを定義します