가드레일로 자동 검사를 수행하고, 승인이 필요한 작업은 사람이 검토하도록 하세요. 두 방식을 함께 사용하면 언제 실행을 계속하거나 일시 중지하거나 종료할지 정할 수 있습니다.
- 가드레일은 입력, 출력 또는 도구의 동작을 자동으로 검증합니다.
- 사람의 검토 단계에서는 실행을 일시 중지합니다. 이때 사람이 직접 민감한 작업을 승인하거나 거부할 수 있고, 정책에 따라 자동으로 결정할 수도 있습니다.
상황에 맞는 제어 방식 선택하기
| 사용 사례 | 먼저 적용할 방식 |
|---|---|
| 주 모델을 실행하기 전에 허용되지 않은 사용자 요청 차단 | 입력 가드레일 |
| 최종 출력을 시스템 외부로 보내기 전에 검증하거나 민감한 부분 가리기 | 출력 가드레일 |
| 함수 도구를 호출하기 전에 인수를 검사하거나 호출 후 결과 검사 | 도구 가드레일 |
| 취소, 편집, 셸 명령어 실행, 민감한 MCP 작업 등 사이드 이펙트가 발생하기 전에 일시 중지 | 사람의 승인 |
차단형 가드레일 추가하기
워크플로우에서 비용이 많이 들거나 사이드 이펙트가 발생하는 단계에 진입하기 전에 빠르게 검증하려면 입력 가드레일을 사용하세요.
import { Agent, InputGuardrailTripwireTriggered, run } from "@openai/agents";
import { z } from "zod";
const guardrailAgent = new Agent({
name: "Homework check",
instructions: "Detect whether the user is asking for math homework help.",
outputType: z.object({
isMathHomework: z.boolean(),
reasoning: z.string(),
}),
});
const agent = new Agent({
name: "Customer support",
instructions: "Help customers with support questions.",
inputGuardrails: [
{
name: "Math homework guardrail",
runInParallel: false,
async execute({ input, context }) {
const result = await run(guardrailAgent, input, { context });
return {
outputInfo: result.finalOutput,
tripwireTriggered: result.finalOutput?.isMathHomework === true,
};
},
},
],
});
try {
await run(agent, "Can you solve 2x + 3 = 11 for me?");
} catch (error) {
if (error instanceof InputGuardrailTripwireTriggered) {
console.log("Guardrail blocked the request.");
} else {
throw error;
}
}주 에이전트를 시작하는 데 드는 비용이나 위험이 너무 크다면 가드레일 검사가 끝날 때까지 실행을 차단하세요. 검사 결과가 나오기 전에 작업을 시작해도 될 만큼 지연 시간 단축이 중요하다면 가드레일을 병렬로 실행하세요.
사람이 검토할 때까지 실행 일시 중지하기
승인을 통해 사람이 도구 호출에 개입할 수 있습니다. 모델은 여전히 작업이 필요하다고 판단할 수 있지만, 해당 작업을 승인하거나 거부할 때까지 실행은 일시 중지됩니다.
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";
const cancelOrder = tool({
name: "cancel_order",
description: "Cancel a customer order.",
parameters: z.object({ orderId: z.number() }),
needsApproval: true,
async execute({ orderId }) {
return `Cancelled order ${orderId}`;
},
});
const agent = new Agent({
name: "Support agent",
instructions: "Use cancel_order to handle cancellation requests.",
tools: [cancelOrder],
});
let result = await run(agent, "Cancel order 123.");
if (result.interruptions?.length) {
const state = result.state;
for (const interruption of result.interruptions) {
console.log(`Approval required: ${interruption.name}`);
state.approve(interruption);
}
result = await run(agent, state);
}
console.log(result.finalOutput);핸드오프 이후나 중첩된 agent.asTool()
승인 절차
도구 호출에 검토가 필요하면 SDK는 항상 같은 절차를 따릅니다.
- 도구를 실행하는 대신 승인을 위해 실행이 일시 중지되었음을 기록합니다.
- 실행 결과에
interruptions와 실행을 재개하는 데 필요한state가 포함됩니다. - 애플리케이션에서 대기 중인 항목을 승인하거나 거부합니다.
- 새 사용자 턴을 시작하는 대신
state에서 기존 실행을 재개합니다.
검토에 시간이 걸릴 수 있다면 state를 직렬화해 저장한 뒤 나중에 재개하세요. 이때도 같은 실행이 이어집니다.
워크플로우에서 가드레일이 적용되는 범위
에이전트 수준 가드레일이 작동하는 범위는 제한적입니다.
- 입력 가드레일은 체인의 첫 번째 에이전트에서만 실행됩니다.
- 출력 가드레일은 최종 출력을 생성하는 에이전트에서만 실행됩니다.
- 도구 가드레일은 해당 가드레일이 연결된 함수 도구에서 실행됩니다.
관리자 에이전트가 작업을 조율하는 워크플로우에서 모든 사용자 정의 도구 호출을 검사해야 한다면 에이전트 수준의 입력 또는 출력 가드레일에만 의존하지 마세요. 사이드 이펙트를 일으키는 도구에 검증 로직을 배치하세요.
사이버 보안 작업 실행 전 검토하기
승인된 사이버 보안 워크플로우에서는 민감한 도구 호출을 실행 전에 각각 평가하세요. 사이드 이펙트가 발생하는 지점에 도구 가드레일과 승인 대기 절차를 적용해 문서에 명시된 작업 범위를 준수하도록 하세요.
- 제안된 대상, 작업, 도구 인수, 호출 주체의 신원, 작업 수행 시간이 승인된 범위에 부합하는지 확인하세요.
- 별도의 정책 구성 요소나 검토자에게 제안된 작업의 정확한 내용과 이를 평가하는 데 필요한 컨텍스트만 제공하세요.
- 범위를 벗어난 호스트에 대한 접근, 자격 증명 탈취, 지속적인 접근 권한 확보, 데이터 유출, 파괴적 변경, 프로덕션 환경 접근, 정책 우회 시도를 거부하세요.
- 허용 여부가 모호하거나 위험이 큰 작업은 일시 중지하고, 사람이 명시적으로 승인한 후에만 도구를 실행하세요.
- 파일 시스템, 네트워크, 신원, 프로젝트별로 독립적인 접근 경계를 적용하고 결정 사항과 실행 결과를 기록하세요. 검토 시간이 초과되거나 검토를 수행할 수 없으면 실행을 차단하세요.
Responses API와 Agents SDK를 사용하는 애플리케이션에는 Codex 자동 검토가 자동으로 적용되지 않습니다. 자체 하네스에 검토 절차와 정책 집행 로직을 추가하세요. 오픈 소스 Codex 검토자 정책에서 구현 방식의 예를 확인할 수 있습니다. 승인된 모델 접근 권한은 모델과 신뢰할 수 있는 액세스를, 보안 작업을 안전하게 설정하는 방법은 권장 구성을 참고하세요.
스트리밍과 지연 검토에 동일한 상태 모델 사용하기
스트리밍에서도 같은 승인 체계를 사용합니다. 스트리밍 중 실행이 일시 중지되면 중지 처리가 완료될 때까지 기다린 뒤 interruptions를 확인하고 승인 요청을 처리하세요. 그런 다음 같은 state에서 실행을 재개하세요. 나중에 검토할 경우에는 직렬화한 상태를 저장해 두었다가 결정이 내려지면 기존 실행을 이어가세요.
다음 단계
각 제어 방식이 적용되는 범위를 파악했다면 관련 런타임이나 도구 인터페이스를 다루는 가이드를 살펴보세요.