휴먼 인 더 루프 (HITL)

이 가이드는 SDK에 내장된 휴먼인더루프 (HITL) 지원을 사용하여 인간 개입에 따라 에이전트 실행을 일시 중지하고 재개하는 방법을 보여줍니다.

현재 주요 사용 사례는 민감한 도구 실행에 대한 승인을 요청하는 것입니다.

승인 요청

needsApproval 옵션을 true 또는 boolean 을 반환하는 async 함수로 설정하여 승인이 필요한 도구를 정의할 수 있습니다.

도구 승인 정의

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. 에이전트가 도구(또는 여러 개)를 호출하기로 결정하면 needsApproval 을 평가하여 이 도구가 승인이 필요한지 확인합니다.
2. 승인이 필요한 경우, 에이전트는 승인이 이미 승인되었거나 거부되었는지 확인합니다.
   • 승인이 승인되거나 거부되지 않은 경우, 도구는 도구 호출을 실행할 수 없다는 정적 메시지를 에이전트에 반환합니다.
   • 승인/거부가 없는 경우 도구 승인 요청이 트리거됩니다.
3. 에이전트는 모든 도구 승인 요청을 수집하고 실행을 인터럽트합니다.
4. 인터럽션이 있는 경우, 실행 결과에는 보류 중인 단계를 설명하는 interruptions 배열이 포함됩니다. 도구 호출에 확인이 필요한 경우 type: "tool_approval_item" 을 가진 ToolApprovalItem 이 나타납니다.
5. 도구 호출을 승인하거나 거부하려면 result.state.approve(interruption) 또는 result.state.reject(interruption) 를 호출할 수 있습니다.
6. 모든 인터럽션을 처리한 후, result.state 를 runner.run(agent, state) 로 다시 전달하여 실행을 재개할 수 있습니다. 여기서 agent 는 전체 실행을 트리거한 원래 에이전트입니다.
7. 흐름은 1단계부터 다시 시작됩니다.

예제

아래는 터미널에서 승인을 요청하고 상태를 파일에 임시 저장하는 휴먼인더루프 (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) {
    // storing
    await fs.writeFile(
      'result.json',
      JSON.stringify(result.state, null, 2),
      'utf-8',
    );

    // from here on you could run things on a different thread/process

    // reading later on
    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.rawItem.name} with "${interruption.rawItem.arguments}". Do you approve?`,
      );

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

    // resume execution of the current state
    result = await run(agent, state);
    hasInterruptions = result.interruptions?.length > 0;
  }

  console.log(result.finalOutput);
}

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

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

장시간 승인 처리

휴먼인더루프 흐름은 서버를 계속 실행하지 않고도 오랜 시간 동안 인터럽트 가능하도록 설계되었습니다. 요청을 종료하고 나중에 계속해야 하는 경우 상태를 직렬화하여 나중에 재개할 수 있습니다.

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

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

보류 중인 작업 버저닝

참고

이는 주로 에이전트를 변경하는 동안 직렬화된 상태를 오랜 시간 저장하려는 경우에 적용됩니다.

승인 요청에 시간이 오래 걸리고 에이전트 정의를 의미 있게 버저닝하거나 Agents SDK 버전을 올릴 계획이라면, 패키지 별칭을 사용해 두 가지 버전의 Agents SDK 를 병행 설치하여 자체 분기 로직을 구현하는 것을 권장합니다.

실제로는 자체 코드에 버전 번호를 부여하고 이를 직렬화된 상태와 함께 저장하며, 역직렬화를 코드의 올바른 버전으로 안내하는 것을 의미합니다.