가드레일

가드레일은 에이전트와 함께 실행되거나 완료될 때까지 실행을 차단할 수 있어, 사용자 입력이나 에이전트 출력에 대해 점검과 검증을 수행할 수 있습니다. 예를 들어, 비용이 큰 모델을 호출하기 전에 경량 모델을 가드레일로 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 오류를 트리거해 고비용 모델 실행을 중지할 수 있습니다.

가드레일에는 두 가지 종류가 있습니다:

1. 입력 가드레일은 초기 사용자 입력에서 실행됩니다
2. 출력 가드레일은 최종 에이전트 출력에서 실행됩니다

워크플로 경계

가드레일은 에이전트에 연결되지만, 워크플로의 모든 에이전트에서 반드시 실행되지는 않습니다:

• 입력 가드레일은 체인의 첫 번째 에이전트에서만 실행됩니다
• 출력 가드레일은 최종 출력을 생성하는 에이전트에서만 실행됩니다
• 도구 가드레일은 모든 함수 도구 호출에서 실행되며, 실행 전에는 입력 가드레일이, 실행 후에는 출력 가드레일이 실행됩니다

매니저나 핸드오프를 포함한 워크플로에서 각 사용자 정의 함수 도구 호출마다 점검이 필요하다면, 에이전트 수준 입력/출력 가드레일보다는 도구 가드레일을 사용하세요.

입력 가드레일

입력 가드레일은 3단계로 실행됩니다:

1. 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다
2. 가드레일 함수가 실행되어 InputGuardrailResult로 감싼 GuardrailFunctionOutput을 반환합니다
3. tripwireTriggered가 true이면 InputGuardrailTripwireTriggered 오류가 발생합니다

참고 입력 가드레일은 사용자 입력용이므로, 워크플로에서 해당 에이전트가 첫 번째 에이전트일 때만 실행됩니다. 에이전트마다 필요한 가드레일이 다른 경우가 많기 때문에, 가드레일은 에이전트 자체에 구성됩니다.

실행 모드

• runInParallel: true (기본값)는 LLM/도구 호출과 동시에 가드레일을 시작합니다. 지연 시간은 최소화되지만, 가드레일이 나중에 트리거되면 모델이 이미 토큰을 소비했거나 도구를 실행했을 수 있습니다
• runInParallel: false는 모델 호출 이전에 가드레일을 실행하여, 가드레일이 요청을 차단할 때 토큰 비용과 도구 실행을 방지합니다. 지연 시간보다 안전성과 비용을 우선할 때 사용하세요

출력 가드레일

출력 가드레일은 3단계로 실행됩니다:

1. 가드레일은 에이전트가 생성한 출력을 받습니다
2. 가드레일 함수가 실행되어 OutputGuardrailResult로 감싼 GuardrailFunctionOutput을 반환합니다
3. tripwireTriggered가 true이면 OutputGuardrailTripwireTriggered 오류가 발생합니다

참고 출력 가드레일은 해당 에이전트가 워크플로의 마지막 에이전트일 때만 실행됩니다. 실시간 음성 상호작용은 음성 에이전트 가이드를 참고하세요.

출력 가드레일 함수는 내부 modelResponse와 해당 턴에서 생성된 출력 항목을 담은 선택적 details 객체도 받습니다. 최종 출력만으로 응답 통과 여부를 판단하기 어렵다면 이를 사용하세요. 예를 들어, 가드레일 트리거 전에 전체 생성 항목 목록이나 프로바이더 응답 메타데이터를 검사하고 싶을 때 유용합니다.

도구 가드레일

도구 가드레일은 함수 도구를 감싸며, 실행 전후에 도구 호출을 검증하거나 차단할 수 있게 해줍니다. 도구 자체(tool() 옵션)를 통해 구성하며, 해당 도구의 모든 호출에서 실행됩니다.

실제로는 tool({...})에 inputGuardrails 및/또는 outputGuardrails를 설정한 사용자 정의 함수 도구를 의미합니다.

• 입력 도구 가드레일은 도구 실행 전에 실행되며, 메시지와 함께 호출을 거부하거나 tripwire를 발생시킬 수 있습니다
• 출력 도구 가드레일은 도구 실행 후에 실행되며, 출력을 거부 메시지로 대체하거나 tripwire를 발생시킬 수 있습니다

도구 가드레일은 behavior를 반환합니다:

• allow — 다음 가드레일 또는 도구 실행으로 계속 진행합니다
• rejectContent — 메시지로 단락 처리합니다(도구 호출 건너뜀 또는 출력 대체)
• throwException — 즉시 tripwire 오류를 발생시킵니다

도구 가드레일은 tool()로 정의한 함수 도구에 적용됩니다. 핸드오프는 모델에 함수형 도구처럼 제시되지만, 일반 함수 도구 파이프라인이 아니라 SDK의 핸드오프 경로를 통해 실행되므로 핸드오프 호출 자체에는 도구 가드레일이 적용되지 않습니다. 호스티드 툴과 내장 실행 도구(computerTool, shellTool, applyPatchTool)도 이 가드레일 파이프라인을 사용하지 않으며, agent.asTool()은 현재 도구 가드레일 옵션을 직접 노출하지 않습니다.

트립와이어

가드레일이 실패하면 tripwire를 통해 이를 알립니다. tripwire가 트리거되는 즉시 러너는 해당 오류를 발생시키고 실행을 중단합니다.

가드레일 구현

가드레일은 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);

도구 입력/출력 가드레일은 다음과 같습니다:

도구 가드레일

import {
  Agent,
  ToolGuardrailFunctionOutputFactory,
  defineToolInputGuardrail,
  defineToolOutputGuardrail,
  tool,
} from '@openai/agents';
import { z } from 'zod';

const blockSecrets = defineToolInputGuardrail({
  name: 'block_secrets',
  run: async ({ toolCall }) => {
    const args = JSON.parse(toolCall.arguments) as { text?: string };
    if (args.text?.includes('sk-')) {
      return ToolGuardrailFunctionOutputFactory.rejectContent(
        'Remove secrets before calling this tool.',
      );
    }
    return ToolGuardrailFunctionOutputFactory.allow();
  },
});

const redactOutput = defineToolOutputGuardrail({
  name: 'redact_output',
  run: async ({ output }) => {
    const text = String(output ?? '');
    if (text.includes('sk-')) {
      return ToolGuardrailFunctionOutputFactory.rejectContent(
        'Output contained sensitive data.',
      );
    }
    return ToolGuardrailFunctionOutputFactory.allow();
  },
});

const classifyTool = tool({
  name: 'classify_text',
  description: 'Classify text for internal routing.',
  parameters: z.object({
    text: z.string(),
  }),
  inputGuardrails: [blockSecrets],
  outputGuardrails: [redactOutput],
  execute: ({ text }) => `length:${text.length}`,
});

const agent = new Agent({
  name: 'Classifier',
  instructions: 'Classify incoming text.',
  tools: [classifyTool],
});

1. guardrailAgent는 가드레일 함수 내부에서 사용됩니다
2. 가드레일 함수는 에이전트 입력 또는 출력을 받아 결과를 반환합니다
3. 가드레일 결과에 추가 정보를 포함할 수 있습니다
4. agent는 가드레일이 적용되는 실제 워크플로를 정의합니다