09. 가드레일: 에이전트를 안전하게 만들기

비유로 시작하기: 건물 입구의 보안 검색대

중요한 건물에는 입구에 보안 검색대가 있습니다. 들어가는 사람(입력)을 검사하고, 나가는 물건(출력)도 확인합니다. 위험한 것이 감지되면 즉시 통과를 막습니다. 가드레일이 바로 에이전트의 보안 검색대입니다.

왜 필요할까요? 예를 들어 고객지원 에이전트가 비싼 고성능 모델을 쓴다고 합시다. 악의적 사용자가 "수학 숙제 풀어줘"처럼 본래 목적과 무관한 요청을 잔뜩 보내면, 비싼 모델이 헛돌며 비용만 나갑니다. 가드레일을 두면 값싼 모델로 먼저 걸러, 부적절한 요청은 비싼 모델에 닿기도 전에 차단할 수 있습니다.

입력 가드레일 vs 출력 가드레일

flowchart LR
    classDef user fill:#FFE082,stroke:#F9A825,color:#000
    classDef guard fill:#EF9A9A,stroke:#C62828,color:#000
    classDef agent fill:#80DEEA,stroke:#00838F,color:#000
    classDef result fill:#A5D6A7,stroke:#2E7D32,color:#000

    U[사용자 입력]:::user --> IG{입력 가드레일}:::guard
    IG -->|통과| A[메인 에이전트]:::agent
    IG -->|트립와이어 작동| X[차단 · 예외 발생]:::guard
    A --> OG{출력 가드레일}:::guard
    OG -->|통과| F[사용자에게 응답]:::result
    OG -->|트립와이어 작동| X2[차단]:::guard

입력 가드레일은 사용자 입력이 메인 에이전트에 닿기 전에 검사합니다. 체인의 첫 번째 에이전트에서만 실행됩니다. 출력 가드레일은 에이전트가 최종 답을 낸 뒤, 사용자에게 가기 전에 검사합니다. 최종 출력을 내는 에이전트에서만 실행됩니다.

입력 가드레일 만들기

가드레일의 핵심은 트립와이어(tripwire)입니다. 검사 함수가 tripwire_triggered=True를 반환하면, SDK가 즉시 예외를 발생시켜 실행을 멈춥니다.

강의의 예제 흐름(수학 숙제 차단)을 따라가 봅시다. 작은 가드레일 에이전트가 "이게 수학 숙제인가?"를 판단합니다.

from pydantic import BaseModel
from agents import (
    Agent, Runner, GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered, RunContextWrapper, input_guardrail,
)

# 1) 판단용 작은 에이전트 (값싼 모델 사용)
class MathCheck(BaseModel):
    is_math_homework: bool
    reasoning: str

guardrail_agent = Agent(
    name="GuardrailCheck",
    instructions="사용자가 수학 숙제 풀이를 요청하는지 판단한다.",
    output_type=MathCheck,
)

# 2) 가드레일 함수
@input_guardrail
async def math_guardrail(
    ctx: RunContextWrapper, agent: Agent, input_data
) -> GuardrailFunctionOutput:
    result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
    check = result.final_output_as(MathCheck)
    return GuardrailFunctionOutput(
        output_info=check,
        tripwire_triggered=check.is_math_homework,  # 수학 숙제면 차단
    )

# 3) 메인 에이전트에 가드레일 부착
agent = Agent(
    name="CustomerSupport",
    instructions="고객의 질문에 친절히 답한다.",
    input_guardrails=[math_guardrail],
)

이제 실행해 봅니다.

import asyncio

async def main():
    try:
        await Runner.run(agent, "2x + 3 = 11에서 x를 구해줘.")
        print("가드레일 미작동 — 예상과 다름")
    except InputGuardrailTripwireTriggered:
        print("수학 숙제 가드레일 작동 — 요청 차단됨")

asyncio.run(main())

수학 숙제 요청이 들어오면 InputGuardrailTripwireTriggered 예외가 발생하고, 메인 에이전트는 실행조차 되지 않습니다. 비싼 모델을 보호한 것입니다.

📌 핵심: 가드레일은 에이전트에 부착(input_guardrails=[...])합니다. Runner가 아니라 Agent에 다는 이유는, 에이전트마다 다른 검사가 필요하기 때문입니다. 코드가 관련 에이전트 옆에 모여 가독성도 좋아집니다.

출력 가드레일

출력 가드레일도 구조가 같습니다. @output_guardrail을 쓰고, 에이전트의 최종 출력을 검사합니다. 민감 정보 누출, 시스템 프롬프트 유출, 부적절한 내용 등을 막는 데 씁니다.

from agents import output_guardrail, OutputGuardrailTripwireTriggered

@output_guardrail
async def no_secrets_guardrail(
    ctx: RunContextWrapper, agent: Agent, output
) -> GuardrailFunctionOutput:
    leaked = "내부전용" in str(output)  # 단순 예시
    return GuardrailFunctionOutput(
        output_info={"checked": True},
        tripwire_triggered=leaked,
    )

agent = Agent(
    name="Assistant",
    instructions="고객 질문에 답한다.",
    output_guardrails=[no_secrets_guardrail],
)

값싼 모델로 비싼 모델 지키기

가드레일의 비용 효율을 정리하면 다음과 같습니다.

⚠️ 흔한 실수: 가드레일 검사에 메인 모델만큼 비싸고 느린 모델을 쓰는 것. 그러면 비용 절감 효과가 사라집니다. 가드레일은 빠르고 저렴한 모델로 두는 것이 핵심입니다.

💡 팁: 입력 가드레일은 체인의 첫 에이전트에서만, 출력 가드레일은 최종 출력 에이전트에서만 돕니다. 멀티 에이전트 중간 단계의 함수 도구 호출까지 검사하려면 도구 가드레일(tool guardrail)이라는 별도 메커니즘을 씁니다.

💡 실습 아이디어(강의의 Guardrails 실습 대응): 금융 상담 에이전트에 "투자 자문이 아닌 일반 질문만 허용"하는 입력 가드레일을 붙여 보세요. 작은 분류 에이전트가 질문 유형을 판단하고, 자문성 질문이면 트립와이어를 작동시켜 차단합니다.

이 장에서 배운 것

• 가드레일은 입력·출력을 검사하는 에이전트의 보안 검색대다.
• 입력 가드레일은 첫 에이전트에서, 출력 가드레일은 최종 출력 에이전트에서 실행된다.
• 트립와이어가 작동하면 SDK가 예외를 던져 즉시 실행을 멈춘다.
• 값싼 모델로 가드레일을 돌려 비싼 메인 모델을 보호하면 비용을 아낀다.

✍️ 확인 문제

1. 가드레일을 Runner.run이 아니라 Agent에 부착하도록 설계한 이유는 무엇인가?
2. 트립와이어가 작동했을 때 메인 에이전트는 실행되는가? 그 결과 어떤 이점이 생기는가?
3. 가드레일로 비용을 절감하려는데 효과가 없다. 가장 의심스러운 설정은 무엇인가?

이전 부: 08. 멀티 에이전트 팀
다음 장: 10. 핸드오프