가드레일

가드레일은 사용자 입력과 에이전트 출력에 대한 점검 및 유효성 검사를 가능하게 합니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(따라서 느리고/비싼) 모델을 사용하는 에이전트를 상상해 보세요. 악의적인 사용자가 수학 숙제를 도와 달라고 모델에 요청하는 것은 원치 않을 것입니다. 이때 빠르고/저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 즉시 오류를 발생시켜 비용이 큰 모델의 실행을 막을 수 있으므로 시간과 비용을 절약할 수 있습니다 (블로킹 가드레일을 사용하는 경우에 해당합니다. 병렬 가드레일의 경우, 가드레일이 완료되기 전에 비용이 큰 모델이 이미 실행되기 시작했을 수 있습니다. 자세한 내용은 아래 "실행 모드"를 참조하세요).

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

입력 가드레일은 초기 사용자 입력에서 실행됨
출력 가드레일은 최종 에이전트 출력에서 실행됨

입력 가드레일

입력 가드레일은 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 매개변수를 지원하지 않습니다.

트립와이어

입력 또는 출력이 가드레일을 통과하지 못하면, 가드레일은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 확인하는 즉시{Input,Output}GuardrailTripwireTriggered 예외를 발생시키고 에이전트 실행을 중단합니다.

가드레일 구현

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

frompydanticimportBaseModelfromagentsimport(Agent,GuardrailFunctionOutput,InputGuardrailTripwireTriggered,RunContextWrapper,Runner,TResponseInputItem,input_guardrail,)classMathHomeworkOutput(BaseModel):is_math_homework:boolreasoning:strguardrail_agent=Agent(# (1)!name="Guardrail check",instructions="Check if the user is asking you to do their math homework.",output_type=MathHomeworkOutput,)@input_guardrailasyncdefmath_guardrail(# (2)!ctx:RunContextWrapper[None],agent:Agent,input:str|list[TResponseInputItem])->GuardrailFunctionOutput:result=awaitRunner.run(guardrail_agent,input,context=ctx.context)returnGuardrailFunctionOutput(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],)asyncdefmain():# This should trip the guardrailtry:awaitRunner.run(agent,"Hello, can you help me solve for x: 2x + 3 = 11?")print("Guardrail didn't trip - this is unexpected")exceptInputGuardrailTripwireTriggered:print("Math homework guardrail tripped")

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

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

frompydanticimportBaseModelfromagentsimport(Agent,GuardrailFunctionOutput,OutputGuardrailTripwireTriggered,RunContextWrapper,Runner,output_guardrail,)classMessageOutput(BaseModel):# (1)!response:strclassMathOutput(BaseModel):# (2)!reasoning:stris_math:boolguardrail_agent=Agent(name="Guardrail check",instructions="Check if the output includes any math.",output_type=MathOutput,)@output_guardrailasyncdefmath_guardrail(# (3)!ctx:RunContextWrapper,agent:Agent,output:MessageOutput)->GuardrailFunctionOutput:result=awaitRunner.run(guardrail_agent,output.response,context=ctx.context)returnGuardrailFunctionOutput(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,)asyncdefmain():# This should trip the guardrailtry:awaitRunner.run(agent,"Hello, can you help me solve for x: 2x + 3 = 11?")print("Guardrail didn't trip - this is unexpected")exceptOutputGuardrailTripwireTriggered:print("Math output guardrail tripped")