휴먼 인 더 루프 (HITL)
이 가이드에서는 SDK의 승인 기반 휴먼인더루프 (HITL) 흐름을 다룹니다. 도구 호출에 승인이 필요하면 SDK는 실행을 일시 중지하고 interruptions를 반환하며, 나중에 동일한 RunState에서 실행을 재개할 수 있게 합니다.
이 승인 처리는 현재 최상위 에이전트에 국한되지 않고 실행 전체에 적용됩니다. 도구가 현재 에이전트에 속하든, 핸드오프를 통해 도달한 에이전트에 속하든, 중첩된 agent.asTool() 실행에 속하든 동일한 패턴이 적용됩니다. 중첩된 agent.asTool()의 경우에도 인터럽션(중단 처리)은 외부 실행에 나타나므로, 외부 result.state에서 승인하거나 거부한 뒤 원래 루트 실행을 재개합니다.
agent.asTool()에서는 두 가지 계층에서 승인이 발생할 수 있습니다. 에이전트 도구 자체가 asTool({ needsApproval })를 통해 승인을 요구할 수 있고, 중첩 실행이 시작된 후 중첩 에이전트 내부의 도구가 별도로 승인을 요청할 수도 있습니다. 두 경우 모두 동일한 외부 실행의 인터럽션(중단 처리) 흐름을 통해 처리됩니다.
이 페이지에서는 interruptions를 통한 수동 승인 흐름에 중점을 둡니다. 앱에서 코드로 결정을 내릴 수 있다면, 일부 도구 유형은 실행을 일시 중지하지 않고 계속할 수 있도록 프로그래밍 방식의 승인 콜백도 지원합니다. agent.asTool() 자체를 설정하는 방법은 도구를 참조하세요. 이 페이지에서는 해당 실행 계층의 도구 중 하나라도 승인이 필요해졌을 때 어떤 일이 일어나는지 다룹니다.
computerTool()에서는 onSafetyCheck를 사용하여 Responses API가 반환한 안전 검사 결과를 수락하거나 거부합니다. 이 콜백은 id와 code 값이 비어 있지 않은 대기 중인 검사가 있는 컴퓨터 호출에 대해서만 실행되며, 이 페이지에서 설명하는 일시 중지 및 재개 승인 흐름을 사용하지 않습니다. 자세한 내용과 예시는 컴퓨터 안전 검사를 참조하세요.
승인 흐름
섹션 제목: “승인 흐름”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 },});- 도구 호출이 실행되기 직전에 SDK는 승인 규칙(
needsApproval또는 호스티드 MCP의 동등한 설정)을 평가합니다. - 승인이 필요하고 아직 저장된 결정이 없으면 도구 호출은 실행되지 않습니다. 대신 실행에
RunToolApprovalItem이 기록됩니다. - 해당 턴이 끝나면 실행이 일시 중지되고, 대기 중인 모든 승인이 실행 결과의
interruptions배열로 반환됩니다. 여기에는 중첩된agent.asTool()실행 내부에서 요청된 승인도 포함됩니다. result.state.approve(interruption)또는result.state.reject(interruption)으로 대기 중인 각 항목을 처리합니다. 동일한 도구에 대해 실행이 끝날 때까지 승인 또는 거부 상태를 유지하려면{ alwaysApprove: true }또는{ alwaysReject: true }를 전달합니다. 거부할 때는{ message: '...' }를 전달하여 해당 도구 호출에 대해 모델로 반환되는 거부 메시지를 지정할 수도 있습니다.- 업데이트된
result.state를runner.run(agent, state)에 다시 전달하여 재개합니다. 여기서agent는 해당 실행의 원래 최상위 에이전트입니다. SDK는 중첩된 에이전트 도구 실행을 포함하여 중단된 지점부터 계속합니다.
기본적으로 함수 도구의 입력 가드레일은 승인 후 도구가 실행되기 직전에만 실행됩니다. 승인 대기 항목이 표시되기 전에 동일한 입력 가드레일로 로컬 함수 도구 호출을 검증하려면 run() 또는 Runner에 toolExecution: { preApprovalInputGuardrails: true }를 전달하세요. 승인 전 가드레일이 호출을 거부하면 SDK는 승인 인터럽션(중단 처리)을 생성하는 대신 가드레일 메시지를 도구 출력으로 모델에 반환합니다. 호출을 허용하면 실행은 여전히 승인을 위해 일시 중지되며, 대기하는 동안 도구 호출이 안전하지 않은 상태로 바뀌었을 가능성에 대비하여 승인 후 입력 가드레일이 다시 실행됩니다.
needsApproval이 함수인 경우, SDK는 도구 인수가 검사 가능한 객체로 파싱된 후에만 이 함수를 호출합니다. 잘못된 형식의 JSON과 객체가 아닌 값은 안전한 차단(fail-closed) 방식으로 처리됩니다. 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()을 다시 호출하세요. 이 패턴의 스트리밍 버전은 스트리밍 중 휴먼인더루프 (HITL)를 참조하세요.
session도 사용하고 있다면 RunState에서 재개할 때 동일한 session을 계속 전달하세요. 그러면 입력을 다시 준비하지 않고 재개된 턴이 세션 메모리에 추가됩니다. 세션 수명 주기에 대한 자세한 내용은 세션을 참조하세요.
다음은 터미널에서 승인을 요청하고 상태를 파일에 임시로 저장하는 휴먼인더루프 (HITL) 흐름의 더 완전한 예시입니다.
// This local CLI trusts its saved state. Browser/mobile approval UIs should keep// snapshots on the server; see human-in-the-loop-server.ts in agent-patterns.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가 입증할 수 있는 경우 현재 응답에서 생성된 항목의 정확한 소유 관계를 기록하므로, 지원되는 출력 포함 부분 승인 체크포인트는 직렬화와 역직렬화를 거칠 수 있습니다. 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 })를 전달하세요.
직렬화된 상태는 서버 측 데이터베이스처럼 애플리케이션이 제어하는 저장소에 저장하세요.
서버에서 승인 상태 유지
섹션 제목: “서버에서 승인 상태 유지”직렬화된 RunState에는 승인 결정, 대기 중인 도구 호출, 도구 인수, 애플리케이션 컨텍스트를 비롯한 실행 상태가 포함됩니다. RunState.fromString()은 해당 상태를 복원하지만, 스냅샷이나 이를 제출하는 사람을 인증하지는 않습니다. 신뢰할 수 있는 저장소에서 가져온 스냅샷이거나 애플리케이션에서 전체 스냅샷의 무결성, 소유권, 재전송 방지 여부를 검증한 경우에만 역직렬화하세요. 스키마 검증과 도구 호출 지문은 스냅샷을 인증하지 않습니다. SDK에서 에이전트나 생성된 항목의 소유 관계를 참조하는 것 역시 애플리케이션 사용자의 권한을 부여하지 않습니다.
브라우저 또는 모바일 승인 인터페이스에서는 전체 스냅샷을 애플리케이션이 제어하는 서버 저장소에 보관하세요. 검토자에게는 열람 권한이 있는 표시 정보와 대기 중인 결정에 대한 불투명 식별자만 보내세요. 실행 ID나 결정 ID는 권한의 증거가 아닙니다. 도구 이름과 인수를 신뢰할 수 없는 표시 콘텐츠로 취급하세요. 민감한 값을 필터링하고 HTML을 렌더링할 때 콘텐츠를 이스케이프하세요. 전체 실행 결과와 오류는 서버에 보관하고, 애플리케이션에서 선택한 출력만 클라이언트에 반환하세요.
결정이 도착하면 서버는 다음을 수행해야 합니다.
- 애플리케이션의 세션 또는 인증 미들웨어를 사용하여 검토자를 인증합니다. 인증된 신원 정보를 승인 요청 본문에서 가져와서는 안 됩니다.
- 저장된 실행과 선택된 대기 중 호출에 대해 검토자의 권한을 확인합니다.
- 서버에 저장된 대기 중 요청을 기준으로 결정 식별자와 불리언 결정을 검증합니다. 클라이언트에서 대체 도구 호출, 인수, 승인 기록 또는 직렬화된 상태를 받지 마세요.
- 역직렬화 및 실행 재개 전에 소유권 확인과 대기 중 요청의 사용 완료 처리를 원자적으로 수행합니다. 동시 제출이나 재전송된 제출로 동일한 스냅샷을 두 번 재개해서는 안 됩니다. 공유 저장소에서는 트랜잭션 또는 동등한 원자적 조건부 전환을 사용하세요.
- 서버가 보유한 스냅샷을 로드하고,
state.getInterruptions()로 대기 중인 항목을 가져온 뒤, 해당 항목에만state.approve()또는state.reject()를 적용하고 실행을 재개합니다.
다음 예시에서는 일괄 처리 대상인 모든 대기 중 호출에 대해 각각 하나의 결정이 필요합니다. 이는 애플리케이션 정책이며, SDK는 앞서 설명한 부분 승인도 지원합니다. 저장소는 하나의 프로세스에 있는 하나의 이벤트 루프로 제한됩니다. 소유자 확인, 검증, 사용 완료 처리 사이에는 await가 없습니다. 역직렬화나 실행이 실패하거나 실행이 취소되어도 요청은 사용 완료 상태로 유지됩니다. 사용 완료 처리는 이 스냅샷의 재제출을 방지하지만, 도구의 부수 효과가 정확히 한 번만 발생함을 보장하지는 않습니다. 복구나 다른 실행을 시작하기 전에 완료되었거나 완료 여부가 불확실한 도구의 부수 효과를 확인하고 정합성을 맞추세요.
import { randomUUID } from 'node:crypto';import { Agent, Runner, RunState, type RunResult } from '@openai/agents';import { z } from 'zod';
export type PendingApproval = { kind: 'approval'; requestId: string; prompts: { decisionId: string; toolName: string; arguments: string }[];};
type StoredRun = { ownerId: string; snapshot: string; decisionIds: string[];};
// Simulation only: one event loop in one process. Production storage needs an// atomic owner-checked consume operation and bounded retention. Consumption is// permanent even after failure/cancellation; reconcile side effects before retry.export class ApprovalServer { #agent: Agent; #runner = new Runner({ tracingDisabled: true }); #pending = new Map<string, StoredRun>();
constructor(agent: Agent) { this.#agent = agent; }
// An HTTP adapter must obtain this identity from trusted authentication // middleware and apply request/CSRF protections. Never read it from the body. async start(authenticatedUserId: string, message: string) { const result = await this.#runner.run(this.#agent, message); return this.#save(authenticatedUserId, result); }
#save<TContext, TAgent extends Agent<any, any>>( ownerId: string, result: RunResult<TContext, TAgent>, ) { const interruptions = result.state.getInterruptions(); if (interruptions.length === 0) { // RunResult stays on the server; the app selects what the client may see. return { kind: 'completed' as const, output: result.finalOutput }; } const requestId = randomUUID(); const decisionIds = interruptions.map(() => randomUUID()); this.#pending.set(requestId, { ownerId, snapshot: result.state.toString(), decisionIds, }); const response: PendingApproval = { kind: 'approval', requestId, // Detached display values only. Filter arguments for the reviewer's access // policy; this demo uses synthetic weather data. Escape HTML in a web UI. prompts: interruptions.map((item, index) => ({ decisionId: decisionIds[index], toolName: item.name ?? 'unknown_tool', arguments: item.arguments ?? '', })), }; return response; }
async decide( authenticatedUserId: string, requestId: string, decisions: unknown, signal?: AbortSignal, ) { const stored = this.#pending.get(requestId); if (!stored || stored.ownerId !== authenticatedUserId) { throw new Error('Approval request is unavailable.'); } // Validate JSON request data, not client-supplied calls, state, or identity. const parsed = z.record(z.string(), z.boolean()).safeParse(decisions); if ( !parsed.success || Object.keys(parsed.data).length !== stored.decisionIds.length || !stored.decisionIds.every((id) => Object.prototype.hasOwnProperty.call(parsed.data, id), ) ) { throw new Error( 'Provide one boolean decision for every pending tool call.', ); } // No await between the owner check and consume. The parsed decisions are a // detached copy, so client mutation while deserialization awaits has no effect. this.#pending.delete(requestId); const state = await RunState.fromString(this.#agent, stored.snapshot); const interruptions = state.getInterruptions(); for (const [index, interruption] of interruptions.entries()) { if (parsed.data[stored.decisionIds[index]]) { state.approve(interruption); } else { state.reject(interruption); } } const result = await this.#runner.run(this.#agent, state, { signal }); return this.#save(authenticatedUserId, result); }}전체 코드 예제는 CLI 클라이언트/서버 시뮬레이션을 참조하세요. 이는 배포 가능한 HTTP 서비스가 아닙니다. 프로덕션 애플리케이션은 신뢰할 수 있는 인증, 표시되는 정보와 선택된 호출에 대한 권한 부여, 해당하는 경우 요청 및 CSRF 보호, 제한된 저장소 보존 기간, 공유 저장소에서의 원자적 사용 완료 처리, 복구 정책을 제공해야 합니다. CLI는 합성 도구 데이터를 사용하고 트레이싱을 비활성화합니다. 실제 애플리케이션의 스냅샷과 진단 정보에는 민감한 데이터가 포함될 수 있습니다.
contextStrategy: 'replace'로 RunState.fromStringWithContext()를 사용하거나 직렬화된 승인 기록만 제거한다고 해서 신뢰할 수 없는 스냅샷이 안전해지는 것은 아닙니다. 다른 필드가 여전히 실행을 제어합니다. 클라이언트가 전체 스냅샷을 전달한다면, 역직렬화 전에 전체 스냅샷의 무결성을 검증하고, 권한이 있는 사용자 및 실행에 연결하며, 재전송을 방지하세요. 무결성 검증은 스냅샷을 암호화하거나 클라이언트로부터 내용을 숨기지 않습니다.
대기 중인 작업의 버전 관리
섹션 제목: “대기 중인 작업의 버전 관리”승인 요청을 처리하는 데 시간이 오래 걸리고 에이전트 정의를 체계적으로 버전 관리하거나 Agents SDK 버전을 올리려는 경우, 현재는 패키지 별칭을 사용하여 Agents SDK의 두 버전을 병렬로 설치하고 자체 분기 로직을 구현하는 것을 권장합니다.
실제로는 자체 코드에 버전 번호를 부여하고 이를 직렬화된 상태와 함께 저장한 뒤, 역직렬화가 올바른 버전의 코드를 사용하도록 하는 방식입니다.