가드레일(Guardrails)로 입출력 검증하기

가드레일(Guardrails)로 입출력 검증하기

가드레일은 사용자 입력과 에이전트 출력을 검사·검증하는 메커니즘이에요. 예를 들어 고객 요청을 처리하는 비싸고 느린 모델을 쓰는 에이전트가 있다고 해볼게요. 악성 사용자에게 수학 숙제를 풀어 달라고 시키는 상황에서, 빠르고 저렴한 모델로 검사를 돌려 이상하면 바로 오류를 던져 비용·시간을 아끼는 게 가드레일의 핵심 사용처예요. 차단(blocking) 실행이면 비싼 모델이 아예 시작되지 않고, 병렬 실행이면 가드레일이 끝나기 전에 이미 시작될 수도 있어요.

가드레일은 두 종류로 나뉘는데, 입력 가드레일(최초 사용자 입력에 동작)과 출력 가드레일(최종 에이전트 출력에 동작)이에요. 에이전트와 도구에 붙지만 실행 시점은 다릅니다.

  • 입력 가드레일은 체인의 첫 번째 에이전트에만 동작해요.
  • 출력 가드레일은 최종 출력을 만드는 에이전트에만 동작해요.
  • 도구 가드레일은 가드된 함수 도구가 호출될 때마다 실행되어, 관리자·핸드오프·전문가 위임이 섞인 워크플로에선 에이전트 수준 가드레일보다 이걸 쓰는 게 좋아요.

입력 가드레일

입력 가드레일은 세 단계로 진행돼요. 먼저 가드레일이 에이전트에 전달된 것과 같은 입력을 받아요. 그다음 가드레일 함수가 GuardrailFunctionOutput을 만들어 InputGuardrailResult로 감싸요. 마지막으로 .tripwire_triggered가 참인지 확인하고, 참이면 InputGuardrailTripwireTriggered 예외를 던져요.

from pydantic import BaseModel
from agents import Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered, RunContextWrapper, Runner
from agents.decorators import input_guardrail

class MathHomeworkOutput(BaseModel):
    is_math_homework: bool
    reasoning: str

guardrail_agent = Agent(
    name="Guardrail check",
    instructions="Check if the user is asking you to do their math homework.",
    output_type=MathHomeworkOutput,
)

@input_guardrail
async def math_guardrail(ctx, agent, input):
    result = await Runner.run(guardrail_agent, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_math_homework,
    )

agent = Agent(
    name="Customer support agent",
    instructions="You help customers with their questions.",
    input_guardrails=[math_guardrail],
)

입력 가드레일은 두 실행 모드를 지원해요.

  • 병렬 실행(기본, run_in_parallel=True): 가드레일이 에이전트 실행과 동시에 돌아요. 지연이 가장 낮지만, 트립와이어가 발동되면 에이전트가 이미 토큰을 쓰거나 도구를 실행했을 수 있어요.
  • 차단 실행(run_in_parallel=False): 가드레일이 에이전트가 시작되기 전에 완료돼요. 트립와이어가 발동하면 에이전트가 아예 실행되지 않아 토큰·부작용을 막아요. 비용 최적화에 좋아요.

출력 가드레일

출력 가드레일도 비슷한 흐름으로, 에이전트가 만든 출력을 받아 가드레일 함수가 GuardrailFunctionOutput을 만들고 .tripwire_triggered가 참이면 OutputGuardrailTripwireTriggered 예외를 던져요. 출력 가드레일은 에이전트가 끝난 뒤 항상 실행되므로 run_in_parallel 파라미터를 지원하지 않아요.

from pydantic import BaseModel
from agents import Agent, GuardrailFunctionOutput, OutputGuardrailTripwireTriggered, RunContextWrapper, Runner
from agents.decorators import output_guardrail

class MathOutput(BaseModel):
    reasoning: str
    is_math: bool

guardrail_agent = Agent(
    name="Guardrail check",
    instructions="Check if the output includes any math.",
    output_type=MathOutput,
)

@output_guardrail
async def math_guardrail(ctx, agent, output):
    result = await Runner.run(guardrail_agent, output.response, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_math,
    )

agent = Agent(
    name="Customer support agent",
    instructions="You help customers with their questions.",
    output_guardrails=[math_guardrail],
    output_type=MessageOutput,
)

트립와이어가 발동하면 SDK는 이미 완료된 도구 호출 항목은 보존하되, 거부된 후보 최종 출력은 제외하고 세션에 기록해요. 차단 메시지를 바꾸고 싶다면 RunConfig.output_guardrail_blocked_message로 다른 자리표시자 텍스트나 포맷터를 지정할 수 있어요.

더 알아보기