가드레일
가드레일은 에이전트와 함께 병렬로 실행되어, 사용자 입력 또는 에이전트 출력에 대한 검사와 검증을 수행할 수 있게 합니다. 예를 들어, 비용이 큰 모델을 호출하기 전에 경량 모델을 가드레일로 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 오류를 발생시켜 비용이 큰 모델의 실행을 중단할 수 있습니다.
가드레일에는 두 가지 종류가 있습니다:
- 입력 가드레일은 초기 사용자 입력에서 실행됩니다.
- 출력 가드레일은 최종 에이전트 출력에서 실행됩니다.
입력 가드레일
섹션 제목: “입력 가드레일”입력 가드레일은 세 단계로 실행됩니다:
- 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다.
- 가드레일 함수가 실행되어
GuardrailFunctionOutput을(를)InputGuardrailResult안에 감싸 반환합니다. tripwireTriggered가true이면InputGuardrailTripwireTriggered오류가 발생합니다.
참고 입력 가드레일은 사용자 입력을 위한 것이므로, 워크플로에서 에이전트가 첫 번째 에이전트일 때만 실행됩니다. 가드레일은 에이전트 자체에 구성됩니다. 에이전트마다 요구되는 가드레일이 다른 경우가 많기 때문입니다.
출력 가드레일
섹션 제목: “출력 가드레일”출력 가드레일은 3단계로 실행됩니다:
- 가드레일은 에이전트가 생성한 출력을 받습니다.
- 가드레일 함수가 실행되어
GuardrailFunctionOutput을(를)OutputGuardrailResult안에 감싸 반환합니다. tripwireTriggered가true이면OutputGuardrailTripwireTriggered오류가 발생합니다.
참고 출력 가드레일은 워크플로에서 에이전트가 마지막 에이전트일 때만 실행됩니다. 실시간 음성 상호작용은 음성 에이전트 구축을 참고하세요.
트립와이어
섹션 제목: “트립와이어”가드레일이 실패하면 트립와이어를 통해 이를 신호합니다. 트립와이어가 트리거되는 즉시 러너는 해당 오류를 던지고 실행을 중단합니다.
가드레일 구현
섹션 제목: “가드레일 구현”가드레일은 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', 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 agentconst MessageOutput = z.object({ response: z.string() });type MessageOutput = z.infer<typeof MessageOutput>;
// The output by the math guardrail agentconst MathOutput = z.object({ reasoning: z.string(), isMath: z.boolean() });
// The guardrail agentconst guardrailAgent = new Agent({ name: 'Guardrail check', instructions: 'Check if the output includes any math.', outputType: MathOutput,});
// An output guardrail using an agent internallyconst 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);guardrailAgent는 가드레일 함수 내부에서 사용됩니다.- 가드레일 함수는 에이전트 입력 또는 출력을 받아 결과를 반환합니다.
- 가드레일 결과에 추가 정보를 포함할 수 있습니다.
agent는 가드레일이 적용되는 실제 워크플로를 정의합니다.