가드레일과 인간 검토

가드레일과 인간 검토 (Guardrails and human review)

자동 검사에는 가드레일을, 승인 결정에는 인간 검토를 사용해요. 이 둘을 함께 사용해 실행이 언제 계속되고, 일시 중지되고, 멈춰야 하는지 정의할 수 있어요.

출처: 문서

본문

자동 검사에는 가드레일(guardrails)을, 승인 결정에는 인간 검토(human review)를 사용하세요. 이 둘을 함께 사용해 실행이 언제 계속되고, 일시 중지되고, 멈춰야 하는지 정의해요.

  • 가드레일은 입력, 출력, 또는 도구 동작을 자동으로 검증해요.
  • 인간 검토는 사람이나 정책이 민감한 작업을 승인하거나 거부할 수 있도록 실행을 일시 중지해요.

올바른 제어 선택하기

사용 사례 시작할 것
메인 모델이 실행되기 전에 허용되지 않는 사용자 요청 차단 입력 가드레일
시스템 밖으로 나가기 전에 최종 출력 검증 또는 마스킹 출력 가드레일
함수 도구 호출 주변의 인자 또는 결과 검사 도구 가드레일
취소, 편집, 셸 명령, 민감한 MCP 작업 같은 부수 효과 전에 일시 중지 인간 참여 승인(Human-in-the-loop)

차단형 가드레일 추가하기

워크플로우의 값비싸거나 부수 효과가 있는 부분이 시작되기 전에 빠른 검증 단계를 실행하고 싶을 때 입력 가드레일을 사용하세요.

입력 가드레일로 요청 차단하기

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.");
  }
}

import asyncio

from pydantic import BaseModel

from agents import (
    Agent,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
    TResponseInputItem,
    input_guardrail,
)


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


guardrail_agent = Agent(
    name="Homework check",
    instructions="Detect whether the user is asking for math homework help.",
    output_type=MathHomeworkOutput,
)


@input_guardrail
async def math_guardrail(
    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,
        tripwire_triggered=result.final_output.is_math_homework,
    )


agent = Agent(
    name="Customer support",
    instructions="Help customers with support questions.",
    input_guardrails=[math_guardrail],
)


async def main() -> None:
    try:
        await Runner.run(agent, "Can you solve 2x + 3 = 11 for me?")
    except InputGuardrailTripwireTriggered:
        print("Guardrail blocked the request.")


if __name__ == "__main__":
    asyncio.run(main())

메인 에이전트를 시작하는 비용이나 위험이 너무 높을 때는 차단 실행(blocking execution)을 사용하세요. 추측 작업을 피하는 것보다 낮은 지연 시간이 더 중요할 때는 병렬 가드레일을 사용하세요.

인간 검토를 위해 일시 중지하기

승인(approvals)은 도구 호출에 대한 human-in-the-loop 경로예요. 모델이 여전히 작업이 필요하다고 결정할 수 있지만, 여러분이 승인하거나 거부할 때까지 실행이 일시 중지돼요.

민감한 작업 전 승인을 위해 일시 중지하기

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: "Handle support requests and ask for approval when needed.",
  tools: [cancelOrder],
});

let result = await run(agent, "Cancel order 123.");

if (result.interruptions?.length) {
  const state = result.state;
  for (const interruption of result.interruptions) {
    state.approve(interruption);
  }
  result = await run(agent, state);
}

console.log(result.finalOutput);

import asyncio

from agents import Agent, Runner, function_tool


@function_tool(needs_approval=True)
async def cancel_order(order_id: int) -> str:
    return f"Cancelled order {order_id}"


agent = Agent(
    name="Support agent",
    instructions="Handle support requests and ask for approval when needed.",
    tools=[cancel_order],
)


async def main() -> None:
    result = await Runner.run(agent, "Cancel order 123.")

    if result.interruptions:
        state = result.to_state()
        for interruption in result.interruptions:
            state.approve(interruption)
        result = await Runner.run(agent, state)

    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

이와 동일한 중단(interruption) 패턴은 승인 도구가 핸드오프 후 또는 중첩된 TypeScript의 agent.asTool() / Python의 agent.as_tool() 호출 안 등 워크플로우 더 깊은 곳에 있더라도 적용돼요.

승인 수명 주기

도구 호출에 검토가 필요하면, SDK는 매번 동일한 패턴을 따라요:

  1. 실행은 도구를 실행하는 대신 승인 중단(approval interruption)을 기록해요.
  2. 결과는 interruptions와 재개 가능한 state를 반환해요.
  3. 애플리케이션이 보류 중인 항목을 승인하거나 거부해요.
  4. 새 사용자 턴을 시작하는 대신 state에서 동일한 실행을 재개해요.

검토에 시간이 걸릴 수 있다면 state를 직렬화해 저장하고 나중에 재개하세요. 그것도 여전히 동일한 실행이에요.

워크플로우 경계가 중요해요

에이전트 수준 가드레일은 모든 곳에서 실행되지 않아요:

  • 입력 가드레일은 체인의 첫 번째 에이전트에서만 실행돼요.
  • 출력 가드레일은 최종 출력을 생성하는 에이전트에서만 실행돼요.
  • 도구 가드레일은 연결된 함수 도구에서 실행돼요.

매니저 스타일 워크플로우의 모든 커스텀 도구 호출 주변에 검사를 필요로 한다면, 에이전트 수준 입력 또는 출력 가드레일에만 의존하지 마세요. 부수 효과를 만드는 도구 옆에 검증을 두세요.

실행 전 사이버 보안 작업 검토하기

승인된 사이버 보안 워크플로우의 경우, 각 민감한 도구 호출을 실행 전에 평가하세요. 부수 효과가 발생하는 경계에서 서면 참여 범위(written engagement scope)를 강제하기 위해 도구 가드레일과 승인 중단을 사용하세요:

  1. 제안된 대상, 작업, 도구 인자, 호출 정체성, 참여 기간을 승인된 범위와 대조해 확인하세요.
  2. 별도의 정책 구성 요소 또는 검토자에게 정확한 제안 작업과 평가에 필요한 컨텍스트만 제공하세요.
  3. 범위 밖의 호스트, 자격 증명 탈취, 지속성(persistence), 데이터 유출, 파괴적인 변경, 프로덕션 접근, 정책 우회 시도를 거부하세요.
  4. 도구가 실행되기 전에 모호하거나 고위험 작업은 명시적 인간 승인을 위해 일시 중지하세요.
  5. 독립적인 파일시스템, 네트워크, 정체성, 프로젝트 경계를 강제하고, 결정과 실행 결과를 기록하며, 검토가 타임아웃되거나 불가능해지면 fail closed 하세요.

Responses API와 Agents SDK 애플리케이션은 Codex Auto-review를 자동으로 상속하지 않아요. 여러분의 자체 harness에 검토와 강제를 추가하세요. 오픈소스 Codex reviewer policy가 한 가지 접근 방식을 보여줘요. 승인된 모델 접근에 대해서는 Models and Trusted Access를, 안전한 참여 설정에 대해서는 Recommended configuration을 검토하세요.

스트리밍과 지연 검토는 동일한 상태 모델을 사용해요

스트리밍은 별도의 승인 시스템을 만들지 않아요. 스트리밍된 실행이 일시 중지되면, 안정될 때까지 기다렸다가 interruptions를 검사하고 승인을 해결한 뒤 동일한 state에서 재개하세요. 검토가 나중에 이루어지면, 직렬화된 상태를 저장하고 결정이 도착했을 때 동일한 실행을 계속하세요.

다음 단계

제어 경계가 명확해지면 그 경계 주변의 런타임이나 도구 표면을 다루는 가이드로 계속 진행하세요.

[Running agents

    See how interruptions and resumptions fit into the runtime loop.](https://developers.openai.com/api/docs/guides/agents/running-agents)

[Results and state

    Learn which result surfaces paused runs return to your application.](https://developers.openai.com/api/docs/guides/agents/results)

[Using tools

    Decide which tool surfaces need validation or approval before side effects
  happen.](https://developers.openai.com/api/docs/guides/tools#usage-in-the-agents-sdk)

더 알아보기 (Learn more)

관련 문서: 에이전트 실행과 결과 및 상태를 참고하세요.