콘텐츠로 이동

에이전트 실행

에이전트는 스스로 동작하지 않습니다. Runner 클래스나 run() 유틸리티로 실행해야 합니다.

턴 실행, 이벤트 스트리밍, 대화 상태 관리가 필요하다면 에이전트를 읽은 다음 이 페이지를 참고합니다. 에이전트를 어떻게 정의할지 아직 결정하지 않았다면 에이전트부터 시작합니다.

간단한 실행
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions: 'You are a helpful assistant',
});
const result = await run(
agent,
'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);
// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

사용자 정의 러너가 필요하지 않다면 싱글턴 기본 Runner 인스턴스를 실행하는 run() 유틸리티를 사용할 수도 있습니다.

또는 직접 러너 인스턴스를 만들 수 있습니다.

간단한 실행
import { Agent, Runner } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions: 'You are a helpful assistant',
});
// You can pass custom configuration to the runner
const runner = new Runner();
const result = await runner.run(
agent,
'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);
// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

에이전트를 실행하면 최종 출력과 전체 실행 기록이 담긴 실행 결과 객체를 받습니다.

Runner의 run 메서드를 사용할 때는 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주됨) 또는 OpenAI Responses API의 입력 항목 목록일 수 있습니다.

러너는 다음과 같은 루프를 실행합니다.

  1. 현재 입력으로 현재 에이전트의 모델을 호출합니다.
  2. LLM 응답을 확인합니다.
    • 최종 출력 → 반환합니다.
    • 핸드오프 → 새 에이전트로 전환하고, 누적된 대화 기록을 유지한 채 1단계로 돌아갑니다.
    • 도구 호출 → 도구를 실행하고, 결과를 대화에 추가한 후 1단계로 돌아갑니다.
  3. maxTurns가 null이 아닌 경우, maxTurns에 도달하면 MaxTurnsExceededError를 발생시킵니다.

앱이 시작될 때 Runner를 만들고 여러 요청에서 재사용합니다. 이 인스턴스는 모델 제공자, 트레이싱 옵션 등의 전역 설정을 저장합니다. 완전히 다른 설정이 필요한 경우에만 다른 Runner를 만듭니다. 간단한 스크립트에서는 내부적으로 기본 러너를 사용하는 run()을 호출할 수도 있습니다.

run() 메서드에는 실행을 시작할 초기 에이전트, 실행 입력, 옵션 집합을 전달합니다.

입력은 문자열(사용자 메시지로 간주됨), 입력 항목 목록, 또는 휴먼 인 더 루프 (HITL) 에이전트를 구축하는 경우 RunState 객체일 수 있습니다.

추가 옵션은 다음과 같습니다.

옵션기본값설명
streamfalsetrue이면 호출이 StreamedRunResult를 반환하고 모델에서 이벤트가 도착할 때마다 내보냅니다.
context–모든 도구 / 가드레일 / 핸드오프에 전달되는 컨텍스트 객체입니다. 자세한 내용은 컨텍스트 관리를 참고합니다.
maxTurns10안전을 위한 제한입니다. 한도에 도달하면 MaxTurnsExceededError를 발생시킵니다. null을 전달하면 제한을 비활성화합니다.
signal–취소에 사용하는 AbortSignal입니다.
session–세션 영속성 구현입니다. 세션을 참고합니다.
sessionInputCallback–세션 기록과 새 입력을 병합하는 사용자 정의 로직입니다. 모델 호출 전에 실행됩니다. 세션을 참고합니다.
callModelInputFilter–모델을 호출하기 직전에 모델 입력(항목 + 선택적 instructions)을 수정하는 훅입니다. 모델 호출 입력 필터를 참고합니다.
toolErrorFormatter–모델에 반환되는 도구 오류 메시지를 사용자 정의하는 훅입니다. 도구 오류 포매터를 참고합니다.
reasoningItemIdPolicy–이전 실행 항목을 모델 입력으로 다시 변환할 때 추론 항목의 id를 유지할지 생략할지 제어합니다. 추론 항목 ID 정책을 참고합니다.
tracing–실행별 트레이싱 설정 재정의입니다. includeTaskAndTurnSpans: false로 설정하면 기본 작업/턴 스팬 계층 구조를 생략합니다.
sandbox–SandboxAgent 실행에 사용할 샌드박스 클라이언트, 활성 세션, 세션 상태, 스냅샷, 매니페스트 재정의 또는 동시성 제한입니다. 개념을 참고합니다.
toolExecution–로컬 도구 호출을 위한 SDK 측 실행 설정입니다. toolExecution.maxFunctionToolConcurrency로 동시에 실행되는 함수 도구 수를 제한하고, toolExecution.preApprovalInputGuardrails로 승인 대기 요청 전에 함수 도구 입력 가드레일을 실행합니다.
toolNotFoundBehavior'raise_error'모델이 생성했으나 대응하는 함수 도구를 찾을 수 없는 호출을 제어합니다. 'return_error_to_model'을 사용하면 모델에 도구 오류를 반환하고 실행을 계속합니다.
toolNameCollisionPolicy'warn'활성화된 함수 도구와 핸드오프 간의 이름 충돌을 제어합니다. 경고를 남기고 현재 디스패치 대상으로 선택된 항목만 노출하는 대신, 모델 요청 전에 실패하도록 하려면 'error'를 사용합니다.
errorHandlers–지원되는 런타임 오류의 핸들러입니다. 오류 핸들러를 참고합니다.
conversationId–서버 측 대화를 재사용합니다(OpenAI Responses API + Conversations API에서만 사용 가능).
previousResponseId–대화를 생성하지 않고 이전 Responses API 호출에서 이어갑니다(OpenAI Responses API에서만 사용 가능).

스트리밍을 사용하면 LLM이 실행되는 동안 이벤트도 제공됩니다. StreamedRunResult는 실행이 진행됨에 따라 정보를 누적합니다. 결과의 completed 프로미스가 이행되면 결과의 요약 속성에 새로 생성된 모든 출력이 포함됩니다. for await 루프로 스트리밍 이벤트를 순회할 수 있습니다. 자세한 내용은 스트리밍을 참고합니다.

직접 Runner 인스턴스를 만드는 경우 RunConfig 객체를 전달하여 러너를 설정할 수 있습니다.

필드타입용도
modelstring | Model실행에 참여하는 모든 에이전트가 특정 모델을 사용하도록 강제합니다.
modelProviderModelProvider모델 이름에 해당하는 모델을 찾습니다. 기본값은 OpenAI 제공자입니다.
modelSettingsModelSettings에이전트별 설정을 재정의하는 전역 조정 매개변수입니다. 선택적으로 활성화할 수 있는 재시도 설정을 비롯한 자세한 내용은 모델을 참고합니다.
handoffInputFilterHandoffInputFilter핸드오프를 수행할 때 입력 항목을 수정합니다(핸드오프 자체에 이미 필터가 정의되어 있지 않은 경우).
inputGuardrailsInputGuardrail[]최초 사용자 입력에 적용되는 가드레일입니다.
outputGuardrailsOutputGuardrail[]최종 출력에 적용되는 가드레일입니다.
tracingDisabledbooleanOpenAI 트레이싱을 완전히 비활성화합니다.
traceIncludeSensitiveDataboolean스팬은 계속 내보내면서 트레이스에서 LLM/도구의 입력과 출력을 제외합니다.
workflowNamestringTraces 대시보드에 표시되며, 관련 실행을 그룹화하는 데 도움이 됩니다.
traceId / groupIdstringSDK가 생성하도록 두는 대신 트레이스 또는 그룹 ID를 직접 지정합니다.
traceMetadataRecord<string, string>모든 스팬에 첨부할 임의의 메타데이터입니다.
tracingTracingConfig내보내기용 API 키와 includeTaskAndTurnSpans를 포함한 Runner 수준의 트레이싱 기본값입니다. 개별 실행 옵션으로 이 값을 재정의할 수 있습니다.
sessionInputCallbackSessionInputCallback이 러너의 모든 실행에 적용되는 기본 기록 병합 전략입니다.
callModelInputFilterCallModelInputFilter각 모델 호출 전에 모델 입력을 수정하는 전역 훅입니다.
toolErrorFormatterToolErrorFormatter모델에 반환되는 도구 오류 메시지를 사용자 정의하는 전역 훅입니다.
reasoningItemIdPolicyReasoningItemIdPolicy생성된 항목을 이후 모델 호출의 입력으로 다시 사용할 때 추론 항목의 id를 유지할지 생략할지 정하는 기본 정책입니다.
sandboxSandboxRunConfigSandboxAgent 실행을 위한 기본 샌드박스 런타임 설정입니다.
toolExecutionToolExecutionConfig로컬 도구 호출을 위한 기본 SDK 측 실행 설정입니다. maxFunctionToolConcurrency는 각 턴에서 로컬 함수 도구의 동시 실행 수를 제한합니다. 설정하지 않거나 null이면 한 턴에서 생성된 모든 함수 도구 호출을 시작합니다. preApprovalInputGuardrails는 승인 대기 요청 전에 함수 도구 입력 가드레일을 실행하도록 활성화합니다.
toolNotFoundBehaviorToolNotFoundBehavior대응하는 함수 도구를 찾을 수 없는 호출의 기본 동작입니다. 'raise_error'는 ModelBehaviorError를 발생시키고, 'return_error_to_model'은 모델에 도구 오류를 반환하고 실행을 계속할 수 있게 합니다.
toolNameCollisionPolicyToolNameCollisionPolicy활성화된 함수 도구와 핸드오프의 이름에 적용되는 기본 충돌 정책입니다. 'warn'은 로그를 남기고 현재 디스패치 대상으로 선택된 항목을 노출하며, 'error'는 모델을 호출하기 전에 UserError를 발생시킵니다.

toolExecution.maxFunctionToolConcurrency는 1 이상의 정수여야 합니다. 이 설정은 로컬 함수 도구의 SDK 측 실행만 제한합니다. 제공자 측 modelSettings.parallelToolCalls는 변경하지 않습니다.

toolExecution.preApprovalInputGuardrails는 기본적으로 비활성화되어 있습니다. true로 설정하면 승인이 필요한 로컬 함수 도구는 SDK가 승인 대기 인터럽션(중단 처리)을 기록하기 전에 입력 가드레일을 실행합니다. 가드레일이 rejectContent를 반환하면 SDK는 승인을 요청하는 대신 해당 거부 메시지를 도구 출력으로 반환합니다. 가드레일이 호출을 허용하더라도 승인 요청은 여전히 발생하며, 승인이 처리된 후 도구를 실행하기 직전에 동일한 입력 가드레일이 다시 실행됩니다.

toolNameCollisionPolicy는 활성화된 함수 도구와 핸드오프 간의 충돌만 제어합니다. 네임스페이스가 지정된 도구, 지연 도구, 중복된 로컬 MCP 도구 이름에 대한 기존의 엄격한 검증은 변경되지 않습니다.

상태를 다음 턴으로 전달하는 일반적인 방법은 네 가지입니다.

전략상태 저장 위치적합한 용도다음 턴에 전달할 내용
result.history앱 메모리소규모 채팅 루프, 완전한 수동 제어, 모든 제공자result.history
session자체 스토리지 + SDK영속적인 채팅 상태, 재개 가능한 실행, 사용자 정의 저장소동일한 session 인스턴스(또는 저장소에 연결된 인스턴스)
conversationIdOpenAI Conversations API워커/서비스 간 서버 측 상태 공유동일한 conversationId와 새 사용자 턴만 전달
previousResponseIdOpenAI Responses API에서만 지원대화를 생성하지 않고 서버에서 관리하는 가장 간단한 이어가기 방식result.lastResponseId와 새 사용자 턴만 전달

result.history와 session은 클라이언트에서 관리합니다. conversationId와 previousResponseId는 OpenAI에서 관리하며, OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화마다 하나의 영속성 전략을 선택합니다. 두 계층을 의도적으로 조정하지 않는 한, 클라이언트에서 관리하는 기록과 서버에서 관리하는 상태를 혼용하면 컨텍스트가 중복될 수 있습니다.

샌드박스 에이전트는 활성 샌드박스 작업 공간이라는 또 하나의 상태 계층을 추가합니다. 대화 기록에는 일반 SDK session, conversationId 또는 previousResponseId를 사용하고, 샌드박스 파일 시스템 상태에는 sandbox.session, sandbox.sessionState, RunState 또는 스냅샷을 사용합니다. 작업 공간 수명 주기는 개념을 참고합니다.

runner.run()(또는 run() 유틸리티)을 한 번 호출할 때마다 애플리케이션 수준 대화의 한 턴에 해당합니다. RunResult의 어느 부분까지 최종 사용자에게 표시할지는 직접 선택합니다. finalOutput만 표시할 수도 있고, 생성된 모든 항목을 표시할 수도 있습니다.

대화 기록을 이어가는 예제
import { Agent, run } from '@openai/agents';
import type { AgentInputItem } from '@openai/agents';
let thread: AgentInputItem[] = [];
const agent = new Agent({
name: 'Assistant',
});
async function userSays(text: string) {
const result = await run(
agent,
thread.concat({ role: 'user', content: text }),
);
thread = result.history; // Carry over history + newly generated items
return result.finalOutput;
}
await userSays('What city is the Golden Gate Bridge in?');
// -> "San Francisco"
await userSays('What state is it in?');
// -> "California"

대화형 버전은 채팅 코드 예제를 참고합니다.

매 턴마다 전체 로컬 대화 기록을 보내는 대신 OpenAI Responses API가 대화 기록을 영속적으로 저장하도록 할 수 있습니다. 긴 대화나 여러 서비스를 조율할 때 유용합니다. 아래의 두 서버 관리 방식 모두 각 요청에 새 턴의 입력만 전달합니다. API가 이전 상태를 재사용합니다. 자세한 내용은 대화 상태 가이드를 참고합니다.

OpenAI는 서버 측 상태를 재사용하는 두 가지 방법을 제공합니다.

Conversations API로 대화를 한 번 생성한 다음 모든 턴에서 해당 ID를 재사용할 수 있습니다. SDK는 자동으로 새로 생성된 항목만 포함합니다.

서버 대화 재사용
import { Agent, run } from '@openai/agents';
import { OpenAI } from 'openai';
const agent = new Agent({
name: 'Assistant',
instructions: 'Reply very concisely.',
});
async function main() {
// Create a server-managed conversation:
const client = new OpenAI();
const { id: conversationId } = await client.conversations.create({});
const first = await run(agent, 'What city is the Golden Gate Bridge in?', {
conversationId,
});
console.log(first.finalOutput);
// -> "San Francisco"
const second = await run(agent, 'What state is it in?', { conversationId });
console.log(second.finalOutput);
// -> "California"
}
main().catch(console.error);
2. 마지막 턴에서 이어가기 위한 previousResponseId
섹션 제목: “2. 마지막 턴에서 이어가기 위한 previousResponseId”

Responses API만으로 시작하려는 경우 이전 응답에서 반환된 ID로 각 요청을 연결할 수 있습니다. 이렇게 하면 전체 대화 리소스를 생성하지 않고도 여러 턴에 걸쳐 컨텍스트를 유지할 수 있습니다.

previousResponseId로 연결
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions: 'Reply very concisely.',
});
async function main() {
const first = await run(agent, 'What city is the Golden Gate Bridge in?');
console.log(first.finalOutput);
// -> "San Francisco"
const previousResponseId = first.lastResponseId;
const second = await run(agent, 'What state is it in?', {
previousResponseId,
});
console.log(second.finalOutput);
// -> "California"
}
main().catch(console.error);

conversationId와 previousResponseId는 함께 사용할 수 없습니다. 여러 시스템에서 공유할 수 있는 이름이 지정된 대화 리소스가 필요하면 conversationId를 사용하고, 한 응답에서 다음 응답으로 이어가는 가장 비용이 적게 드는 SDK 수준의 기본 구성 요소만 필요하면 previousResponseId를 사용합니다.

callModelInputFilter를 사용하면 모델을 호출하기 직전에 모델 입력을 수정할 수 있습니다. 이 훅은 현재 에이전트, 컨텍스트, 병합된 입력 항목(세션 기록이 있으면 포함)을 받습니다. 업데이트된 input 배열과 선택적 instructions를 반환하여 민감한 데이터를 가리거나, 오래된 메시지를 삭제하거나, 추가 시스템 지침을 주입할 수 있습니다.

runner.run(..., { callModelInputFilter })에서 실행별로 설정하거나, Runner 설정에서 기본값으로 설정합니다(RunConfig의 callModelInputFilter).

반환값은 ModelInputData 객체여야 합니다: { input: AgentInputItem[], instructions? }. input 필드는 필수이며 배열이어야 합니다. 다른 형태를 반환하면 UserError가 발생합니다.

SDK는 필터를 호출하기 전에 준비된 턴 입력을 복제합니다. session도 사용하고 있다면 필터링된 복제본이 저장되므로, 여기에서 적용한 데이터 가리기나 잘라내기가 저장된 세션 기록에도 반영됩니다.

필터가 반복되는 모델 호출 간에 작업을 메모이제이션하기 위해 객체 동일성에 의존한다면 필터에 preserveInputIdentity = true를 설정합니다. 그러면 SDK는 각 필터 호출에 새 배열을 전달하더라도, SDK가 준비한 각 항목이 준비된 입력에 남아 있는 동안 해당 항목의 동일성을 유지합니다. 이 옵션은 호출자가 소유한 객체, 즉 원래 run()에 전달한 객체의 동일성은 유지하지 않습니다.

준비된 입력 항목의 동일성 유지
import { CallModelInputFilter, Runner } from '@openai/agents';
const inspectedItems = new WeakSet<object>();
const inspectInputOnce: CallModelInputFilter = ({ modelData }) => {
for (const item of modelData.input) {
if (item && typeof item === 'object' && !inspectedItems.has(item)) {
inspectedItems.add(item);
recordPreparedItem(item);
}
}
return modelData;
};
// Keep SDK-prepared item identities stable across repeated model calls so the
// WeakSet can recognize items that this filter already inspected. Do not mutate
// the items or their nested values.
inspectInputOnce.preserveInputIdentity = true;
const runner = new Runner({ callModelInputFilter: inspectInputOnce });
declare function recordPreparedItem(item: object): void;
export { runner };

SDK는 준비된 항목이나 그 안에 중첩된 값을 동결하지 않으므로 이 모드는 명시적으로 활성화해야 합니다. 필터와 필터가 호출하는 모든 헬퍼는 항목을 불변으로 취급하고, 직접 수정하는 대신 대체 값을 반환해야 합니다. 필터가 반환된 후에도 모델 요청과 세션 입력은 서로 독립된 복사본으로 유지됩니다.

conversationId 또는 previousResponseId를 사용하면 다음 Responses API 호출을 위해 준비된 페이로드에 훅이 실행됩니다. 이전의 서버 관리 컨텍스트는 API가 복원하므로, 해당 호출의 필터링된 배열은 이전 기록 전체가 아니라 새 턴의 변경분만 나타낼 수 있습니다. 이 최종 필터 단계 전에 저장된 기록과 현재 턴을 병합하는 방식을 변경해야 한다면 sessionInputCallback을 사용합니다.

toolErrorFormatter를 사용하면 모델에 반환되는 도구 오류 메시지를 사용자 정의할 수 있습니다. 이를 통해 SDK 기본 메시지 대신 도메인에 특화된 문구(예: 규정 준수 지침)를 반환할 수 있습니다.

포매터는 실행별로 설정하거나(runner.run(..., { toolErrorFormatter })), RunConfig에서 전역으로 설정할 수 있습니다(new Runner(...)의 toolErrorFormatter).

이 포매터는 승인 거부에 대한 전역 폴백입니다. result.state.reject(interruption, { message: '...' })로 특정 인터럽션(중단 처리)을 거부하면 해당 호출의 message가 toolErrorFormatter보다 우선합니다. 둘 다 제공되지 않으면 SDK는 기본 거부 문구인 Tool execution was not approved.를 사용합니다.

toolNotFoundBehavior: 'return_error_to_model'이 대응하는 함수 도구를 찾을 수 없는 호출을 모델에 전달할 도구 출력으로 변환할 때도 포매터가 실행됩니다. 이 경우 기본 메시지는 Tool '<name>' not found.입니다.

포매터는 다음을 받습니다.

  • kind ('approval_rejected' 또는 'tool_not_found')
  • toolType ('function', 'computer', 'shell' 또는 'apply_patch')
  • toolName
  • callId
  • defaultMessage (현재 오류 종류에 대한 SDK 폴백 메시지)
  • runContext

문자열을 반환하면 메시지를 재정의하고, undefined를 반환하면 SDK 기본값을 유지합니다. 포매터가 예외를 발생시키거나 문자열이 아닌 값을 반환하면 SDK는 경고를 로그에 남기고 현재 오류 종류에 대한 기본 메시지를 사용합니다.

reasoningItemIdPolicy를 사용하면 SDK가 이전에 생성된 실행 항목을 이후 모델 입력에 사용할 AgentInputItem[]로 다시 변환할 때 추론 항목의 id 필드를 유지할지 제어할 수 있습니다.

이는 SDK가 생성된 모델 항목을 입력으로 다시 사용하는 다음과 같은 경우에 영향을 미칩니다.

  • 동일한 실행 내의 후속 모델 호출(예: 도구 실행 후)
  • 생성된 항목을 입력/기록으로 재사용하는 후속 턴
  • 저장된 RunState에서 재개한 실행
  • result.history / result.output과 같은 파생 결과 뷰(모델 입력 형태의 배열)
  • 'preserve'(기본값)는 추론 항목 ID를 유지합니다.
  • 'omit'은 추론 항목을 입력으로 다시 보내기 전에 id 필드를 제거합니다.
  • 추론 항목이 아닌 항목은 영향을 받지 않습니다.

이 정책으로 변경되지 않는 항목은 다음과 같습니다.

  • 모델 응답 원문(result.rawResponses)
  • 실행 항목(result.newItems)
  • 제공자가 반환한 모델의 현재 턴 출력

즉, 이 정책은 SDK가 이전에 생성된 항목으로 다음 입력을 구성할 때 적용됩니다.

정책은 실행별로 설정하거나(runner.run(..., { reasoningItemIdPolicy: 'omit' })), 러너의 기본값으로 설정할 수 있습니다(new Runner({ reasoningItemIdPolicy: 'omit', ... })). 저장된 RunState에서 재개할 때는 재정의하지 않는 한 이전에 결정된 정책을 재사용합니다.

reasoningItemIdPolicy는 callModelInputFilter 전에 적용됩니다. 사용자 정의 동작이 필요하다면 callModelInputFilter에서 준비된 입력을 확인하고 모델 호출 전에 추론 ID를 직접 다시 추가하거나 제거할 수 있습니다.

다시 입력으로 사용하는 추론 항목을 ID 없이 정규화하려면 'omit'을 사용합니다(예: 전달되거나 다시 사용되는 모델 입력을 단순하게 유지하거나 앱 파이프라인의 연동 요구 사항에 맞추기 위해).

백엔드/제공자가 다시 입력으로 사용된 추론 항목을 요청 검증 오류로 거부하는 경우에도 유용한 문제 해결 옵션입니다(예: 후속 입력의 추론 항목 ID와 관련된 HTTP 400 오류). 이 경우 'omit'으로 다시 입력에 포함되는 추론 ID를 제거하면 백엔드가 새 요청에 대해 유효하지 않다고 판단하는 ID를 보내지 않을 수 있습니다.

SDK가 다시 사용하는 입력에서도 추론 항목 ID를 유지하기를 원하고 연동 대상이 이를 허용한다면 'preserve'를 유지합니다.

errorHandlers를 사용하면 지원되는 런타임 오류를 예외로 발생시키는 대신 최종 출력으로 변환할 수 있습니다. 지원되는 키는 maxTurns, modelRefusal, invalidFinalOutput입니다.

  • errorHandlers.maxTurns는 최대 턴 수 초과 오류만 처리합니다.
  • errorHandlers.modelRefusal은 ModelRefusalError로 전달되는 모델의 응답 거부를 처리합니다.
  • errorHandlers.invalidFinalOutput은 구조화된 최종 출력이 없거나 출력 스키마 검증에 실패할 때 발생하는 ModelBehaviorError 인스턴스를 처리합니다. 핸들러는 모델을 재시도하거나 도구의 부수 효과를 다시 발생시키지 않고 검증된 폴백을 반환합니다.
  • errorHandlers.default는 지원되는 오류 종류의 폴백으로 사용됩니다.
  • 핸들러는 { error, context, runData }를 받고 { finalOutput, includeInHistory? }를 반환할 수 있습니다. 반환된 finalOutput은 현재 에이전트의 outputType과 일치해야 합니다. structured outputs의 경우 SDK는 실행을 완료하기 전에 폴백을 검증합니다. undefined를 반환하면 해당 오류의 기본 동작을 유지합니다.

SDK는 다음과 같이 처리할 수 있는 몇 가지 오류를 발생시킵니다.

모두 기본 AgentsError 클래스를 상속하며, 이 클래스는 현재 실행 상태에 접근할 수 있는 state 속성을 제공할 수 있습니다.

다음은 GuardrailExecutionError를 처리하는 코드 예제입니다. 입력 가드레일은 첫 번째 사용자 입력에만 실행되므로, 이 예제는 원래 입력과 컨텍스트로 실행을 다시 시작합니다. 또한 모델을 다시 호출하지 않고 저장된 상태를 재사용하여 출력 가드레일을 재시도하는 방법도 보여줍니다.

가드레일 실행 오류
import {
Agent,
GuardrailExecutionError,
InputGuardrail,
InputGuardrailTripwireTriggered,
OutputGuardrail,
OutputGuardrailTripwireTriggered,
run,
} from '@openai/agents';
import { z } from 'zod';
// Shared guardrail agent to avoid re-creating it on every fallback run.
const guardrailAgent = new Agent({
name: 'Guardrail check',
instructions: 'Check if the user is asking you to do their math homework.',
outputType: z.object({
isMathHomework: z.boolean(),
reasoning: z.string(),
}),
});
async function main() {
const input = 'Hello, can you help me solve for x: 2x + 3 = 11?';
const context = { customerId: '12345' };
// Input guardrail example
const unstableInputGuardrail: InputGuardrail = {
name: 'Math Homework Guardrail (unstable)',
execute: async () => {
throw new Error('Something is wrong!');
},
};
const fallbackInputGuardrail: InputGuardrail = {
name: 'Math Homework Guardrail (fallback)',
execute: async ({ input, context }) => {
const result = await run(guardrailAgent, input, { context });
const isMathHomework =
result.finalOutput?.isMathHomework ??
/solve for x|math homework/i.test(JSON.stringify(input));
return {
outputInfo: result.finalOutput,
tripwireTriggered: isMathHomework,
};
},
};
const agent = new Agent({
name: 'Customer support agent',
instructions:
'You are a customer support agent. You help customers with their questions.',
inputGuardrails: [unstableInputGuardrail],
});
try {
// Input guardrails only run on the first turn of a run, so retries must start a fresh run.
await run(agent, input, { context });
} catch (e) {
if (e instanceof GuardrailExecutionError) {
console.error(`Guardrail execution failed (input): ${e}`);
try {
agent.inputGuardrails = [fallbackInputGuardrail];
// Retry from scratch with the original input and context.
await run(agent, input, { context });
} catch (ee) {
if (ee instanceof InputGuardrailTripwireTriggered) {
console.log('Math homework input guardrail tripped on retry');
} else {
throw ee;
}
}
} else {
throw e;
}
}
// Output guardrail example
const replyOutputSchema = z.object({ reply: z.string() });
const unstableOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
name: 'Answer review (unstable)',
execute: async () => {
throw new Error('Output guardrail crashed.');
},
};
const fallbackOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
name: 'Answer review (fallback)',
execute: async ({ agentOutput }) => {
const outputText =
typeof agentOutput === 'string'
? agentOutput
: (agentOutput?.reply ?? JSON.stringify(agentOutput));
const flagged = /math homework|solve for x|x =/i.test(outputText);
return {
outputInfo: { flaggedOutput: outputText },
tripwireTriggered: flagged,
};
},
};
const agent2 = new Agent<unknown, typeof replyOutputSchema>({
name: 'Customer support agent (output check)',
instructions: 'You are a customer support agent. Answer briefly.',
outputType: replyOutputSchema,
outputGuardrails: [unstableOutputGuardrail],
});
try {
await run(agent2, input, { context });
} catch (e) {
if (e instanceof GuardrailExecutionError && e.state) {
console.error(`Guardrail execution failed (output): ${e}`);
try {
agent2.outputGuardrails = [fallbackOutputGuardrail];
// Output guardrails can be retried using the saved state without another model call.
await run(agent2, e.state);
} catch (ee) {
if (ee instanceof OutputGuardrailTripwireTriggered) {
console.log('Output guardrail tripped after retry with saved state');
} else {
throw ee;
}
}
} else {
throw e;
}
}
}
main().catch(console.error);

입력과 출력의 재시도 비교:

  • 입력 가드레일은 실행의 맨 첫 번째 사용자 입력에만 실행되므로, 재시도하려면 동일한 입력/컨텍스트로 새 실행을 시작해야 합니다. 저장된 state를 전달해도 입력 가드레일은 다시 실행되지 않습니다.
  • 출력 가드레일은 모델 응답 후에 실행되므로, GuardrailExecutionError에 저장된 state를 재사용하여 모델을 다시 호출하지 않고 출력 가드레일을 다시 실행할 수 있습니다.

위 예제를 실행하면 다음과 같은 출력이 표시됩니다.

Guardrail execution failed (input): Error: Input guardrail failed to complete: Error: Something is wrong!
Math homework input guardrail tripped on retry
Guardrail execution failed (output): Error: Output guardrail failed to complete: Error: Output guardrail crashed.
Output guardrail tripped after retry with saved state

  • 에이전트: 실행 전 에이전트 정의
  • 실행 결과: finalOutput, 실행 항목, 인터럽션(중단 처리), 재개 상태
  • 세션: SDK가 관리하는 영속적 메모리
  • 도구: 실행 루프에서 사용하는 기능
  • 모델: 제공자 설정 및 Responses 전송 방식
  • 프로덕션 환경에 대비하려면 가드레일 또는 트레이싱을 추가합니다.