가드레일
가드레일은 에이전트와 병렬로 실행되어, 사용자 입력 또는 에이전트 출력에 대한 점검과 검증을 수행할 수 있습니다. 예를 들어, 비용이 큰 모델을 호출하기 전에 경량 모델을 가드레일로 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 오류를 발생시켜 비용이 큰 모델의 실행을 중단할 수 있습니다.
가드레일에는 두 가지 종류가 있습니다:
- 입력 가드레일은 최초 사용자 입력에서 실행됩니다.
- 출력 가드레일은 최종 에이전트 출력에서 실행됩니다.
입력 가드레일
섹션 제목: “입력 가드레일”입력 가드레일은 세 단계로 실행됩니다:
- 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다.
- 가드레일 함수가 실행되어
GuardrailFunctionOutput
을(를)InputGuardrailResult
로 감싸 반환합니다. tripwireTriggered
가true
이면InputGuardrailTripwireTriggered
오류가 발생합니다.
참고 입력 가드레일은 사용자 입력을 대상으로 하므로, 워크플로에서 에이전트가 첫 번째 에이전트인 경우에만 실행됩니다. 가드레일은 에이전트마다 필요한 가드레일이 다를 수 있으므로 에이전트 자체에 구성합니다.
출력 가드레일
섹션 제목: “출력 가드레일”출력 가드레일도 동일한 패턴을 따릅니다:
- 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다.
- 가드레일 함수가 실행되어
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
는 가드레일이 적용되는 실제 워크플로를 정의합니다.