가드레일

가드레일을 사용하면 사용자 입력과 에이전트 출력을 검사하고 검증할 수 있습니다. 예를 들어 고객 요청을 지원하기 위해 매우 지능적이지만 느리고 비용이 많이 드는 모델을 사용하는 에이전트가 있다고 가정해 보겠습니다. 악의적인 사용자가 모델에 수학 숙제를 도와달라고 요청하도록 두어서는 안 됩니다. 따라서 빠르고 저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 즉시 오류를 발생시켜 시간과 비용을 절약할 수 있습니다. 차단 실행은 비용이 많이 드는 모델이 시작되지 않도록 보장합니다. 병렬 실행에서는 가드레일이 완료되기 전에 비용이 많이 드는 모델이 이미 시작되었을 수 있습니다. 자세한 내용은 아래의 "실행 모드"를 참조하세요.

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

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

워크플로 경계

가드레일은 에이전트와 도구에 연결되지만, 워크플로에서 모두 같은 시점에 실행되는 것은 아닙니다.

입력 가드레일은 체인의 첫 번째 에이전트에 대해서만 실행됩니다.
출력 가드레일은 최종 출력을 생성하는 에이전트에 대해서만 실행됩니다.
도구 가드레일은 서버에 가드레일이 구성된 로컬 MCP 도구를 포함하여 가드레일이 적용된 모든 함수 도구 호출에 대해 실행됩니다. 입력 가드레일은 실행 전에, 출력 가드레일은 실행 후에 실행됩니다.

관리자, 핸드오프 또는 위임된 전문 에이전트가 포함된 워크플로에서 각 사용자 정의 함수 도구 호출 전후에 검사가 필요하다면 에이전트 수준의 입력/출력 가드레일에만 의존하지 말고 도구 가드레일을 사용하세요.

입력 가드레일

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

먼저 가드레일이 에이전트에 전달된 것과 동일한 입력을 받습니다.
다음으로 가드레일 함수가 실행되어 GuardrailFunctionOutput을 생성하고, 이 결과는 InputGuardrailResult로 래핑됩니다.
마지막으로 .tripwire_triggered가 true인지 확인합니다. true이면 InputGuardrailTripwireTriggered 예외가 발생하므로 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다.

Note

입력 가드레일은 사용자 입력에 대해 실행되도록 설계되었으므로 에이전트가 첫 번째 에이전트인 경우에만 해당 에이전트의 가드레일이 실행됩니다. guardrails 속성이 왜 Runner.run에 전달되지 않고 에이전트에 있는지 궁금할 수 있습니다. 이는 가드레일이 실제 에이전트와 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행하게 되므로 코드를 함께 배치하면 가독성에 도움이 됩니다.

실행 모드

입력 가드레일은 두 가지 실행 모드를 지원합니다.

병렬 실행(기본값, run_in_parallel=True): 가드레일이 에이전트 실행과 동시에 실행됩니다. 두 작업이 동시에 시작되므로 지연 시간이 가장 짧습니다. 하지만 가드레일의 트립와이어가 발동하면 에이전트가 취소되기 전에 이미 토큰을 소비하고 도구를 실행했을 수 있습니다.
차단 실행(run_in_parallel=False): 가드레일이 에이전트가 시작되기 전에 실행되어 완료됩니다. 가드레일 트립와이어가 발동하면 에이전트는 실행되지 않으므로 토큰 소비와 도구 실행을 방지할 수 있습니다. 비용을 최적화하거나 도구 호출로 발생할 수 있는 부작용을 방지하려는 경우에 적합합니다.

출력 가드레일

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

먼저 가드레일이 에이전트에서 생성된 출력을 받습니다.
다음으로 가드레일 함수가 실행되어 GuardrailFunctionOutput을 생성하고, 이 결과는 OutputGuardrailResult로 래핑됩니다.
마지막으로 .tripwire_triggered이 true인지 확인합니다. true이면 OutputGuardrailTripwireTriggered 예외가 발생하므로 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다.

Note

출력 가드레일은 최종 에이전트 출력에 대해 실행되도록 설계되었으므로 에이전트가 마지막 에이전트인 경우에만 해당 에이전트의 가드레일이 실행됩니다. 입력 가드레일과 마찬가지로 이렇게 처리하는 이유는 가드레일이 실제 에이전트와 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행하게 되므로 코드를 함께 배치하면 가독성에 도움이 됩니다.

출력 가드레일은 항상 에이전트 실행이 완료된 후 실행되므로 run_in_parallel 매개변수를 지원하지 않습니다.

출력 트립와이어와 가드레일 함수에서 발생한 예외는 세션에서 서로 다르게 처리됩니다. 트립와이어는 최종 출력 후보를 거부합니다. 트립와이어가 발동하면 러너는 거부된 최종 출력 후보를 제외하고, 이미 완료된 도구 호출 및 도구 출력 항목과 해당 호출을 재생하는 데 필요한 추론 컨텍스트를 구성된 세션에 영구 저장하도록 요청합니다. 러너는 스트리밍 실행과 비스트리밍 실행 모두에 이 트립와이어 규칙을 적용합니다. 가드레일 함수가 트립와이어 결과를 반환하는 대신 예외를 발생시키면 러너는 판정을 알 수 없는 것으로 처리하며, 가드레일 예외를 외부로 전달하기 전에 완료된 최종 턴 항목을 영구 저장하도록 구성된 세션에 요청합니다. 이 세션 쓰기도 실패하면 세션 쓰기 오류가 우선합니다. 스트리밍 실행은 비스트리밍 실행과 동일한 영구 저장 순서를 사용하며 stream_events()에서 최종 예외를 발생시킵니다. 출력 가드레일이 실행되는 동안 RunResultStreaming.cancel()을 즉시 호출하면 진행 중인 가드레일이 취소되고 최종 턴 세션 쓰기는 시작되지 않습니다.

종료 함수 도구 출력은 에이전트 수준 출력 가드레일이 값을 검사하기 전에 도구가 이미 실행되었으므로 추가 처리가 필요합니다. Agent.tool_use_behavior가 해당 도구 결과를 최종 출력으로 만들고 출력 트립와이어가 이를 거부하면, SDK는 검증된 필드에서 함수 호출/출력 쌍을 재구성할 수 있는 경우에만 재생 가능한 쌍을 유지합니다. 유지되는 function_call_output 페이로드는 기본 텍스트 "Output withheld by an output guardrail."로 대체됩니다. 원래 도구 출력 페이로드는 세션, RunState, 스트리밍된 결과 상태 또는 샌드박스 메모리 입력에 유지되지 않습니다. SDK는 함수 인수를 포함하여 재생에 필요한 검증된 함수 호출 메타데이터를 유지하므로, 해당 메타데이터에는 거부된 출력에도 포함되었던 데이터가 들어 있을 수 있습니다. 현재 응답의 OutputGuardrailResult 객체도 agent_output을 최종 결정된 플레이스홀더로 대체하고 output_info을 비웁니다. 현재 응답의 ToolOutputGuardrailResult 객체는 허용/거부 동작 유형을 보존하지만, 페이로드가 포함된 output_info 및 거부 메시지를 동일한 플레이스홀더로 대체합니다. 이전에 수락된 턴과 가드레일 결과는 변경되지 않습니다. 응답에 추론이나 SDK가 안전하게 정제할 수 없는 다른 형태가 포함되어 있으면 SDK는 거부된 출력 페이로드를 유지하지 않고 현재 응답의 후행 부분 전체를 폐기합니다. 예외를 발생시킨 가드레일 함수는 거부 판정을 반환하지 않은 것이므로 완료된 종료 도구 턴에는 위에서 설명한 예외 영구 저장 동작이 적용됩니다.

애플리케이션에 데이터가 포함되지 않은 다른 플레이스홀더가 필요하면 RunConfig.output_guardrail_blocked_message를 비어 있지 않은 문자열이나 동기식 포매터로 설정하세요. 포매터는 SDK 기본값, 가드레일 이름, 에이전트 및 활성 실행 컨텍스트가 포함된 OutputGuardrailBlockedMessageArgs를 받습니다. 거부된 도구 출력이나 가드레일 output_info은 절대 받지 않습니다. 반환된 텍스트는 SDK가 정제된 종료 도구 턴을 유지하는 모든 위치에서 영구 저장되고 재생되므로 민감한 데이터를 포함하지 않도록 하고 실행 컨텍스트의 비밀 값을 복사하지 마세요. 포매터가 예외를 발생시키거나 None을 반환하거나 비어 있거나 문자열이 아닌 값을 반환하거나 awaitable을 생성하면 SDK는 기본 플레이스홀더를 사용합니다. RunConfig이 생성될 때 비동기 포매터 함수는 거부됩니다.

from agents import OutputGuardrailBlockedMessageArgs, RunConfig


def blocked_message(args: OutputGuardrailBlockedMessageArgs[dict[str, str]]) -> str:
    return f"Output blocked by policy: {args.guardrail_name}."


run_config = RunConfig(output_guardrail_blocked_message=blocked_message)

도구 가드레일

도구 가드레일은 FunctionTool 인스턴스를 래핑하며 해당 도구의 호출을 실행 전후에 검증하거나 차단할 수 있게 합니다. 도구 자체에 구성되며 해당 도구가 호출될 때마다 실행됩니다.

입력 도구 가드레일은 도구가 실행되기 전에 실행되며 호출을 건너뛰거나, 출력을 메시지로 대체하거나, 트립와이어를 발생시킬 수 있습니다.
출력 도구 가드레일은 도구가 실행된 후 실행되며 출력을 대체하거나 트립와이어를 발생시킬 수 있습니다.
함수 도구에 승인이 필요한 경우 입력 도구 가드레일은 일반적으로 승인 후 실행 직전에 실행됩니다. 대기 중인 승인 인터럽션(중단 처리)이 발생하기 전에 이러한 입력 검사를 실행하려면 RunConfig.tool_execution을 ToolExecutionConfig(pre_approval_tool_input_guardrails=True)로 설정하세요. 이 사전 승인 검사를 통과한 호출도 승인 후 도구 실행 전에 다시 검사됩니다.
도구 가드레일은 FunctionTool 실행 파이프라인을 사용합니다. tool 또는 function_tool로 생성한 사용자 정의 도구에 직접 연결할 수 있습니다. 로컬 MCP 서버에 tool_input_guardrails 및 tool_output_guardrails을 설정할 수도 있습니다. SDK는 해당 서버가 제공하는 모든 도구에 이 목록을 연결합니다. 핸드오프는 함수 도구 파이프라인이 아니라 SDK의 핸드오프 파이프라인을 통해 실행되므로 도구 가드레일은 핸드오프 호출 자체에 적용되지 않습니다. 호스티드 툴(WebSearchTool, FileSearchTool, HostedMCPTool, CodeInterpreterTool, ImageGenerationTool)과 기본 제공 실행 도구(ComputerTool, ShellTool, ApplyPatchTool, LocalShellTool)는 이 가드레일 파이프라인을 사용하지 않으며, Agent.as_tool()은 현재 도구 가드레일 옵션을 직접 제공하지 않습니다. 로컬 MCP 구성에 대해서는 MCP 서버 도구 가드레일을 참조하세요.

자세한 내용은 아래 코드 스니펫을 참조하세요.

트립와이어

에이전트 입력 또는 출력이 가드레일을 통과하지 못하면 가드레일은 트립와이어를 통해 이를 알릴 수 있습니다. 러너는 즉시 InputGuardrailTripwireTriggered 또는 OutputGuardrailTripwireTriggered 예외를 발생시키고 에이전트 실행을 중단합니다. 도구 가드레일은 각각 해당하는 ToolInputGuardrailTripwireTriggered 및 ToolOutputGuardrailTripwireTriggered 예외를 사용합니다.

에이전트 수준 트립와이어의 경우 예외의 guardrail_result은 트립와이어를 발동시킨 가드레일을 식별합니다. 러너가 발생시킨 입력 트립와이어의 경우 exception.run_data.input_guardrail_results에는 실행이 중단되기 전에 완료된 모든 입력 가드레일 결과가 포함되며, 여기에는 트립와이어를 발동시킨 결과도 포함됩니다. 출력 트립와이어는 exception.run_data.output_guardrail_results을 통해 이에 상응하는 누적 결과를 제공합니다.

반면 도구 트립와이어 예외는 트립와이어를 발동시킨 guardrail 및 output을 직접 노출합니다. 해당 예외의 run_data.tool_input_guardrail_results 및 run_data.tool_output_guardrail_results 목록에는 실패 전에 완료된 턴에서 누적된 결과가 유지되며, 트립와이어를 발동시킨 결과는 예외의 output을 통해 확인할 수 있습니다. MaxTurnsExceeded과 같이 러너가 관리하는 다른 실패도 완료된 도구 가드레일 결과를 이 목록에 유지합니다. stream_events()이 예외를 발생시킨 후 스트리밍된 결과에는 동일하게 누적된 에이전트 및 도구 가드레일 결과 목록이 노출됩니다. 러너가 관리하는 실행 경로 외부에서 예외가 발생하면 run_data은 None일 수 있습니다.

가드레일 구현

입력을 받아 GuardrailFunctionOutput을 반환하는 함수를 제공해야 합니다. 이 예제에서는 내부적으로 에이전트를 실행하여 이를 구현합니다.

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

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

guardrail_agent = Agent( # (1)!
    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( # (2)!
    ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
) -> GuardrailFunctionOutput:
    result = await Runner.run(guardrail_agent, input, context=ctx.context)

    return GuardrailFunctionOutput(
        output_info=result.final_output, # (3)!
        tripwire_triggered=result.final_output.is_math_homework,
    )


agent = Agent(  # (4)!
    name="Customer support agent",
    instructions="You are a customer support agent. You help customers with their questions.",
    input_guardrails=[math_guardrail],
)

async def main():
    # This should trip the guardrail
    try:
        await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?")
        print("Guardrail didn't trip - this is unexpected")

    except InputGuardrailTripwireTriggered:
        print("Math homework guardrail tripped")

가드레일 함수에서 이 에이전트를 사용합니다.
에이전트의 입력/컨텍스트를 받아 결과를 반환하는 가드레일 함수입니다.
가드레일 결과에 추가 정보를 포함할 수 있습니다.
워크플로를 정의하는 실제 에이전트입니다.

출력 가드레일도 유사합니다.

from pydantic import BaseModel
from agents import (
    Agent,
    GuardrailFunctionOutput,
    OutputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
)
from agents.decorators import output_guardrail
class MessageOutput(BaseModel): # (1)!
    response: str

class MathOutput(BaseModel): # (2)!
    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(  # (3)!
    ctx: RunContextWrapper, agent: Agent, output: MessageOutput
) -> GuardrailFunctionOutput:
    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( # (4)!
    name="Customer support agent",
    instructions="You are a customer support agent. You help customers with their questions.",
    output_guardrails=[math_guardrail],
    output_type=MessageOutput,
)

async def main():
    # This should trip the guardrail
    try:
        await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?")
        print("Guardrail didn't trip - this is unexpected")

    except OutputGuardrailTripwireTriggered:
        print("Math output guardrail tripped")

실제 에이전트의 출력 유형입니다.
가드레일의 출력 유형입니다.
에이전트의 출력을 받아 결과를 반환하는 가드레일 함수입니다.
워크플로를 정의하는 실제 에이전트입니다.

마지막으로 도구 가드레일 예제입니다.

import json
from agents import (
    Agent,
    Runner,
    ToolGuardrailFunctionOutput,
)
from agents.decorators import tool, tool_input_guardrail, tool_output_guardrail

@tool_input_guardrail
def block_secrets(data):
    args = json.loads(data.context.tool_arguments or "{}")
    if "sk-" in json.dumps(args):
        return ToolGuardrailFunctionOutput.reject_content(
            "Remove secrets before calling this tool."
        )
    return ToolGuardrailFunctionOutput.allow()


@tool_output_guardrail
def redact_output(data):
    text = str(data.output or "")
    if "sk-" in text:
        return ToolGuardrailFunctionOutput.reject_content("Output contained sensitive data.")
    return ToolGuardrailFunctionOutput.allow()


@tool(
    tool_input_guardrails=[block_secrets],
    tool_output_guardrails=[redact_output],
)
def classify_text(text: str) -> str:
    """Classify text for internal routing."""
    return f"length:{len(text)}"


agent = Agent(name="Classifier", tools=[classify_text])
result = Runner.run_sync(agent, "hello world")
print(result.final_output)