휴먼 인 더 루프 (HITL)

이 가이드에서는 Agents SDK의 승인 기반 휴먼 인 더 루프 (HITL) 흐름을 설명합니다. 도구 호출에 승인이 필요하면 SDK는 실행을 일시 중지하고 interruptions를 반환하며, 나중에 동일한 RunState에서 실행을 재개할 수 있게 합니다.

이 승인 적용 범위는 현재 최상위 에이전트에 국한되지 않고 실행 전체에 적용됩니다. 도구가 현재 에이전트에 속하거나, 핸드오프를 통해 도달한 에이전트에 속하거나, 중첩된 agent.asTool() 실행에 속하는 경우에도 동일한 패턴이 적용됩니다. 중첩된 agent.asTool()의 경우에도 인터럽션(중단 처리)은 외부 실행에 나타나므로, 외부 result.state에서 승인하거나 거부한 다음 원래 루트 실행을 재개합니다.

agent.asTool()을 사용할 때 승인은 서로 다른 두 계층에서 발생할 수 있습니다. 에이전트 도구 자체가 asTool({ needsApproval })을 통해 승인을 요구할 수 있으며, 중첩 실행이 시작된 후 중첩 에이전트 내부의 도구가 자체 승인을 요청할 수도 있습니다. 두 경우 모두 동일한 외부 실행의 인터럽션(중단 처리) 흐름을 통해 처리됩니다.

이 페이지에서는 interruptions를 통한 수동 승인 흐름을 중점적으로 설명합니다. 애플리케이션이 코드에서 결정할 수 있다면 일부 도구 유형은 프로그래밍 방식의 승인 콜백도 지원하므로 실행을 일시 중지하지 않고 계속할 수 있습니다. agent.asTool() 자체를 설정하는 방법은 도구를 참조하세요. 이 페이지에서는 해당 실행 계층 구조의 도구에 승인이 필요해진 이후의 동작을 설명합니다.

승인 흐름

needsApproval 옵션을 true로 설정하거나 불리언을 반환하는 비동기 함수로 설정하여 승인이 필요한 도구를 정의할 수 있습니다.

도구 승인 정의

import { tool } from '@openai/agents';
import z from 'zod';

const sensitiveTool = tool({
  name: 'cancelOrder',
  description: 'Cancel order',
  parameters: z.object({
    orderId: z.number(),
  }),
  // always requires approval
  needsApproval: true,
  execute: async ({ orderId }, args) => {
    // prepare order return
  },
});

const sendEmail = tool({
  name: 'sendEmail',
  description: 'Send an email',
  parameters: z.object({
    to: z.string(),
    subject: z.string(),
    body: z.string(),
  }),
  needsApproval: async (_context, { subject }) => {
    // check if the email is spam
    return subject.includes('spam');
  },
  execute: async ({ to, subject, body }, args) => {
    // send email
  },
});

흐름

1. 도구 호출이 실행되기 직전에 SDK가 해당 승인 규칙(needsApproval 또는 이에 상응하는 호스티드 MCP 설정)을 평가합니다.
2. 승인이 필요하지만 아직 결정이 저장되지 않았다면 도구 호출은 실행되지 않습니다. 대신 실행에 RunToolApprovalItem이 기록됩니다.
3. 해당 턴이 끝나면 실행이 일시 중지되고 실행 결과의 interruptions 배열에 대기 중인 모든 승인이 반환됩니다. 여기에는 중첩된 agent.asTool() 실행 내부에서 요청된 승인도 포함됩니다.
4. 대기 중인 각 항목을 result.state.approve(interruption) 또는 result.state.reject(interruption)으로 처리합니다. 실행의 나머지 구간에서 동일한 도구를 계속 승인하거나 거부하려면 { alwaysApprove: true } 또는 { alwaysReject: true }를 전달합니다. 거부할 때는 { message: '...' }를 전달하여 해당 도구 호출에 관해 모델로 다시 전송되는 거부 메시지를 제어할 수도 있습니다.
5. 업데이트된 result.state를 runner.run(agent, state)에 다시 전달하여 재개합니다. 여기서 agent는 해당 실행의 원래 최상위 에이전트입니다. SDK는 중첩된 에이전트 도구 실행을 포함하여 인터럽션(중단 처리)이 발생한 지점부터 계속합니다.

기본적으로 함수 도구 입력 가드레일은 승인된 후 도구가 실행되기 직전에만 실행됩니다. 대기 중인 승인을 표시하기 전에 동일한 입력 가드레일로 로컬 함수 도구 호출을 검증하려면 run() 또는 Runner에 toolExecution: { preApprovalInputGuardrails: true }를 전달합니다. 승인 전 가드레일이 호출을 거부하면 SDK는 승인 인터럽션(중단 처리)을 생성하는 대신 가드레일 메시지를 도구 출력으로 모델에 반환합니다. 호출을 허용하면 실행은 계속 승인을 위해 일시 중지되며, 승인 대기 중 도구 호출이 위험해졌을 가능성에 대비해 승인 후 입력 가드레일이 다시 실행됩니다.

needsApproval이 함수인 경우 SDK는 도구 인수가 검사 가능한 객체로 파싱된 후에만 이 함수를 호출합니다. 잘못된 형식의 JSON과 객체가 아닌 값은 안전 우선으로 처리됩니다. SDK는 콜백을 호출하거나 도구를 실행하지 않고 승인을 요청합니다. 해당 호출을 승인해도 도구는 실행되지 않으며, 일반적인 인수 파싱 오류 경로로 계속 진행됩니다. Realtime 함수 도구에도 동일한 규칙이 적용되며, 유효하지 않은 호출에 대해 tool_approval_requested를 발생시킵니다.

{ alwaysApprove: true } 또는 { alwaysReject: true }로 생성한 지속 결정은 실행 상태에 저장되므로 나중에 동일한 일시 중지 실행을 재개할 때 toString() / fromString()을 거쳐도 유지됩니다.

GA 모델에서 컴퓨터 도구 인터럽션(중단 처리)은 하나의 computer_call에 포함된 작업 배치를 나타낼 수 있습니다. SDK는 실행 전에 작업별로 needsApproval을 평가하므로, 대기 중인 하나의 승인으로 이동 + 클릭 같은 작업 시퀀스를 처리할 수 있습니다. UI를 렌더링하기 위해 interruption.rawItem을 검사한다면 GA의 actions 배열과 레거시 단일 action 필드를 모두 처리해야 합니다.

직렬화된 RunState는 현재 computer 도구 이름과 레거시 computer_use_preview 이름 모두에서 컴퓨터 승인을 보존하므로, 프리뷰에서 GA로 마이그레이션하는 동안에도 일시 중지된 실행을 원활하게 재개할 수 있습니다.

message를 제공하지 않으면 SDK는 구성된 toolErrorFormatter가 있을 경우 이를 사용하고, 그렇지 않으면 기본 거부 메시지를 사용합니다.

대기 중인 모든 승인을 한 번에 처리할 필요는 없습니다. 일부 항목만 승인하거나 거부한 후 다시 실행하면 처리된 호출은 계속 진행되고, 처리되지 않은 호출은 interruptions에 남아 실행을 다시 일시 중지합니다.

alwaysApprove: true 또는 alwaysReject: true로 생성한 지속 결정은 이후 동일한 도구 호출에 대한 기본값을 제공합니다. 특정 호출 ID에 대한 명시적 결정은 이 지속 기본값보다 우선합니다. 지속 승인 상태에서 한 호출을 거부하거나 지속 거부 상태에서 한 호출을 승인해도 다른 호출의 기본값은 변경되지 않습니다. 나중에 해당 명시적 결정을 교체하면 새 결정이 그 호출에 적용되고, 나머지 호출에는 지속 기본값이 계속 적용됩니다.

재개 전 입력 추가

실행이 일시 중지된 동안 새 사용자 입력이 도착했고 다음 모델 호출을 재개하기 전에 이를 반영해야 한다면 RunState.addInput()을 사용합니다. 승인을 처리하고 동일한 상태를 Runner.run()에 다시 전달하기 전에 입력을 추가합니다. 준비된 입력은 직렬화된 상태의 일부이므로, 처리되지 않은 승인이나 로컬 도구 작업 때문에 모델 호출이 지연되더라도 toString() / fromString()을 거쳐 유지됩니다.

준비된 항목의 복제된 스냅샷을 검사하려면 state.pendingInput을 읽고, 재개 전에 모두 제거하려면 state.clearPendingInput()을 호출합니다. addInput()은 문자열 또는 입력 항목 배열을 받습니다. 터미널 상태, 남은 턴이 없는 상태, 도구 결과로 실행이 종료될 수 있는 인터럽션(중단 처리)처럼 상태가 다른 모델 호출에 안전하게 도달할 수 없는 경우 UserError를 발생시킵니다.

반영된 준비 입력은 각 입력 건마다 실행의 newItems에 RunInputItem으로 추가되며, 원문 입력 항목은 history에 포함됩니다. 로컬 session을 사용하는 경우 SDK는 모델 요청을 시작하기 전에 반영된 입력을 한 번 저장합니다. conversationId 또는 previousResponseId를 사용하는 경우에는 서버가 응답을 수락할 때까지 입력이 대기 상태로 유지되므로, 수락 전에 발생한 것으로 확인된 실패는 입력을 잃지 않고 재개할 수 있습니다. 공급자가 요청이 이미 수락되었을 가능성이 있다고 보고하면 SDK는 해당 입력 건을 체크포인트로 기록하고, 조용히 다시 재생하는 대신 안전 우선으로 실패 처리합니다. 안전하지 않은 재생을 명시적으로 허용하는 별도 옵션은 모델 재시도를 참조하세요.

자동 승인 결정

수동 interruptions가 가장 일반적인 패턴이지만 유일한 방법은 아닙니다.

• 로컬 shellTool() 및 applyPatchTool()은 onApproval을 사용하여 코드에서 즉시 승인하거나 거부할 수 있습니다.
• 호스티드 MCP 도구는 requireApproval과 onApproval을 함께 사용하여 동일한 방식으로 프로그래밍 방식의 결정을 내릴 수 있습니다.
• 일반 함수 도구는 이 페이지에서 설명하는 수동 인터럽션(중단 처리) 흐름을 사용합니다.

이러한 콜백이 결정을 반환하면 사람의 응답을 기다리기 위해 일시 중지하지 않고 실행이 계속됩니다. Realtime 세션 API는 음성 에이전트 구축의 승인 흐름을 참조하세요.

스트리밍 및 세션

동일한 인터럽션(중단 처리) 흐름이 스트리밍 실행에서도 작동합니다. 스트리밍 실행이 일시 중지되면 stream.completed를 기다린 다음 stream.interruptions를 읽고 항목을 처리합니다. 재개된 출력도 계속 스트리밍하려면 { stream: true }를 사용하여 run()을 다시 호출합니다. 이 패턴의 스트리밍 버전은 스트리밍 중 휴먼 인 더 루프를 참조하세요.

session도 사용 중이라면 RunState에서 재개할 때 동일한 session을 계속 전달합니다. 그러면 입력을 다시 준비하지 않고 재개된 턴이 세션 메모리에 추가됩니다. 세션 수명 주기에 대한 자세한 내용은 세션을 참조하세요.

예제

아래는 터미널에서 승인을 요청하고 상태를 파일에 임시로 저장하는 휴먼 인 더 루프 (HITL) 흐름의 더 완전한 예제입니다.

휴먼인더루프 (HITL)

import { z } from 'zod';
import readline from 'node:readline/promises';
import fs from 'node:fs/promises';
import { Agent, run, tool, RunState, RunResult } from '@openai/agents';

const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the weather for a given city',
  parameters: z.object({
    location: z.string(),
  }),
  needsApproval: async (_context, { location }) => {
    // forces approval to look up the weather in San Francisco
    return location === 'San Francisco';
  },
  execute: async ({ location }) => {
    return `The weather in ${location} is sunny`;
  },
});

const dataAgentTwo = new Agent({
  name: 'Data agent',
  instructions: 'You are a data agent',
  handoffDescription: 'You know everything about the weather',
  tools: [getWeatherTool],
});

const agent = new Agent({
  name: 'Basic test agent',
  instructions: 'You are a basic agent',
  handoffs: [dataAgentTwo],
});

async function confirm(question: string) {
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  const answer = await rl.question(`${question} (y/n): `);
  const normalizedAnswer = answer.toLowerCase();
  rl.close();
  return normalizedAnswer === 'y' || normalizedAnswer === 'yes';
}

async function main() {
  let result: RunResult<unknown, Agent<unknown, any>> = await run(
    agent,
    'What is the weather in Oakland and San Francisco?',
  );
  let hasInterruptions = result.interruptions?.length > 0;
  while (hasInterruptions) {
    // Store the current run state
    await fs.writeFile(
      'result.json',
      JSON.stringify(result.state, null, 2),
      'utf-8',
    );

    // At this point, another process could review the saved state

    // Read the saved state later
    const storedState = await fs.readFile('result.json', 'utf-8');
    const state = await RunState.fromString(agent, storedState);

    for (const interruption of result.interruptions) {
      const confirmed = await confirm(
        `Agent ${interruption.agent.name} would like to use the tool ${interruption.name} with "${interruption.arguments}". Do you approve?`,
      );

      if (confirmed) {
        state.approve(interruption);
      } else {
        state.reject(interruption);
      }
    }

    // Resume execution from the restored state
    result = await run(agent, state);
    hasInterruptions = result.interruptions?.length > 0;
  }

  console.log(result.finalOutput);
}

main().catch((error) => {
  console.dir(error, { depth: null });
});

실제로 작동하는 엔드 투 엔드 버전은 전체 예제 스크립트를 참조하세요.

장시간 승인 대기 처리

휴먼 인 더 루프 (HITL) 흐름은 서버를 계속 실행하지 않고도 오랜 시간 동안 인터럽션(중단 처리) 상태를 유지할 수 있도록 설계되었습니다. 요청 처리를 종료하고 나중에 계속해야 한다면 상태를 직렬화한 후 나중에 재개할 수 있습니다.

result.state.toString() 또는 JSON.stringify(result.state)을 사용하여 상태를 직렬화할 수 있습니다. 나중에 실행을 재개하려면 직렬화된 상태를 RunState.fromString(agent, serializedState)에 전달합니다. 여기서 agent는 전체 실행을 시작한 에이전트 인스턴스입니다.

승인된 함수 도구 결과가 실행의 최종 출력이 될 수 있는 경우 출력 가드레일에는 더 엄격한 재개 경계가 적용됩니다. 활성 RunState는 직렬화 후에는 사용할 수 없는 출력 소유권 정보를 유지할 수 있습니다. 직렬화된 체크포인트가 대기 중인 출력이 어느 응답에 속하는지 확인할 수 없거나, 출력을 포함하지만 모호한 체크포인트를 세션이 연결된 상태로 재개하면 SDK는 추가 모델, 도구 또는 세션 부수 효과가 발생하기 전에 UserError를 발생시켜 안전 우선으로 처리합니다. 이 경우 안전한 입력으로 새 실행을 시작하세요. 동일한 에이전트 그래프를 다시 구성하고 원래 toolUseBehavior를 유지해야 합니다. 출력을 포함하는 모든 부분 승인 상태가 직렬화된 상태를 통해 문제없이 왕복 복원될 수 있다고 가정해서는 안 됩니다.

RunState를 직렬화할 때 SDK는 핸드오프 및 Agent.asTool() 그래프에 대한 안정적인 에이전트 식별자를 기록합니다. 실행을 재개하는 프로세스가 동일한 에이전트 그래프를 다시 구성한다면, 서로 다른 에이전트가 동일한 name을 공유하더라도 일시 중지된 실행을 재개할 수 있습니다.

RunState.fromString(agent, serializedState)에 전달되는 agent는 다시 구성된 그래프의 루트입니다. 역직렬화 중 SDK는 해당 에이전트의 핸드오프 및 Agent.asTool() 참조를 순회한 다음, 상태의 직렬화된 모든 에이전트 참조를 다시 구성된 그래프에 맞춰 확인합니다. 여기에는 현재 에이전트뿐만 아니라 생성된 항목, 처리된 모델 응답, 대기열의 다음 단계가 보유한 중첩 참조도 포함됩니다.

대체된 그래프로 재개해야 하는 경우, 예를 들어 모델이나 도구가 다른 런타임에 의해 래핑된 에이전트를 사용해야 한다면 먼저 원래 그래프로 상태를 역직렬화하고 다시 직렬화한 다음, 그 문자열을 대체 루트 에이전트로 역직렬화합니다. state.setCurrentAgent(agent) 호출은 활성 에이전트만 변경하며, 역직렬화 중 이미 확인된 중첩 참조는 다시 작성하지 않습니다.

재개된 프로세스에서 새 컨텍스트 객체를 주입해야 한다면 RunState.fromStringWithContext(agent, serializedState, context, { contextStrategy })를 대신 사용합니다.

• contextStrategy: 'merge'(기본값)는 제공된 RunContext를 유지하면서 직렬화된 승인 상태를 병합하고, 새 컨텍스트에 toolInput이 아직 정의되지 않은 경우 직렬화된 toolInput을 복원합니다.
• contextStrategy: 'replace'는 제공된 RunContext를 그대로 사용하여 실행을 다시 구성합니다.

직렬화된 실행 상태에는 애플리케이션 컨텍스트와 함께 승인, 사용량, 중첩된 toolInput, 대기 중인 중첩 에이전트 도구 재개 같은 SDK 관리 런타임 메타데이터가 포함됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 runContext.context를 영구 저장되는 데이터로 취급하고, 비밀 정보를 의도적으로 상태와 함께 전달하려는 경우가 아니라면 여기에 넣지 마세요.

실수로 비밀 정보를 영구 저장하지 않도록 기본적으로 트레이싱 API 키는 직렬화된 상태에서 제외됩니다. 트레이싱 자격 증명을 상태와 함께 의도적으로 이동해야 하는 경우에만 result.state.toString({ includeTracingApiKey: true })를 전달하세요.

이렇게 하면 직렬화된 상태를 데이터베이스나 요청과 함께 저장할 수 있습니다.

대기 중인 작업의 버전 관리

참고

이 내용은 에이전트를 변경하면서 직렬화된 상태를 더 오랫동안 저장하려는 경우에 주로 적용됩니다.

승인 요청에 오랜 시간이 걸리고 에이전트 정의에 의미 있는 방식으로 버전을 부여하거나 Agents SDK 버전을 올리려는 경우, 현재는 패키지 별칭을 사용해 두 버전의 Agents SDK를 병렬로 설치하고 자체 분기 로직을 구현하는 방식을 권장합니다.

실제로는 자체 코드에 버전 번호를 할당하고 이를 직렬화된 상태와 함께 저장한 다음, 역직렬화할 때 올바른 코드 버전을 사용하도록 분기해야 합니다.