에이전트 실행

에이전트는 자체적으로 아무것도 하지 않습니다. 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가 필요하지 않다면 싱글톤 기본 Runner 인스턴스를 실행하는 run() 유틸리티를 사용할 수도 있습니다.

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

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 수명 주기와 구성

에이전트 루프

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

그런 다음 runner는 루프를 실행합니다.

현재 에이전트의 모델을 현재 입력으로 호출합니다.
LLM 응답을 검사합니다.
- 최종 출력 → 반환합니다.
- 핸드오프 → 새 에이전트로 전환하고, 누적된 대화 기록을 유지한 뒤 1로 이동합니다.
- 도구 호출 → 도구를 실행하고 결과를 대화에 추가한 뒤 1로 이동합니다.
maxTurns가 null이 아닌 한, maxTurns에 도달하면 MaxTurnsExceededError를 발생시킵니다.

Runner 수명 주기

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

실행 인자

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

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

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

Option	Default	Description
`stream`	`false`	`true`이면 호출이 `StreamedRunResult`를 반환하고 모델에서 이벤트가 도착하는 대로 내보냅니다.
`context`	–	모든 도구 / 가드레일 / 핸드오프로 전달되는 컨텍스트 객체입니다. 자세한 내용은 컨텍스트 관리를 참고하세요.
`maxTurns`	`10`	안전 제한입니다. 도달하면 `MaxTurnsExceededError`를 발생시킵니다. 제한을 비활성화하려면 `null`을 전달하세요.
`signal`	–	취소를 위한 `AbortSignal`입니다.
`session`	–	세션 영속성 구현입니다. 세션을 참고하세요.
`sessionInputCallback`	–	세션 기록과 새 입력을 병합하는 사용자 지정 로직입니다. 모델 호출 전에 실행됩니다. 세션을 참고하세요.
`callModelInputFilter`	–	모델을 호출하기 직전에 모델 입력(항목 + 선택적 instructions)을 편집하는 훅입니다. 모델 호출 입력 필터를 참고하세요.
`toolErrorFormatter`	–	모델에 반환되는 도구 승인 거부 메시지를 사용자 지정하는 훅입니다. 도구 오류 포매터를 참고하세요.
`reasoningItemIdPolicy`	–	이전 실행 항목이 모델 입력으로 다시 변환될 때 추론 항목 `id`를 보존할지 생략할지 제어합니다. 추론 항목 ID 정책을 참고하세요.
`tracing`	–	실행별 트레이싱 구성 재정의입니다(예: 내보내기 API 키).
`sandbox`	–	`SandboxAgent` 실행을 위한 샌드박스 클라이언트, 라이브 세션, 세션 상태, 스냅샷, 매니페스트 재정의 또는 동시성 제한입니다. 개념을 참고하세요.
`toolExecution`	–	로컬 도구 호출을 위한 SDK 측 실행 설정입니다. `toolExecution.maxFunctionToolConcurrency`를 사용해 한 번에 실행되는 함수 도구 수를 제한하고, `toolExecution.preApprovalInputGuardrails`를 사용해 승인 대기 요청 전에 함수 도구 입력 가드레일을 실행할 수 있습니다.
`errorHandlers`	–	지원되는 런타임 오류(현재 `maxTurns`)를 처리하는 핸들러입니다. 오류 핸들러를 참고하세요.
`conversationId`	–	서버 측 대화를 재사용합니다(OpenAI Responses API + Conversations API 전용).
`previousResponseId`	–	대화를 만들지 않고 이전 Responses API 호출에서 이어갑니다(OpenAI Responses API 전용).

스트리밍

스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 시작되면 StreamedRunResult에는 생성된 모든 새 출력을 포함해 실행에 대한 완전한 정보가 포함됩니다. for await 루프를 사용해 스트리밍 이벤트를 반복 처리할 수 있습니다. 자세한 내용은 스트리밍을 읽어보세요.

실행 구성

직접 Runner 인스턴스를 만드는 경우 RunConfig 객체를 전달해 runner를 구성할 수 있습니다.

Field	Type	Purpose
`model`	`string \| Model`	실행의 모든 에이전트에 특정 모델을 강제합니다.
`modelProvider`	`ModelProvider`	모델 이름을 해석합니다. 기본값은 OpenAI 공급자입니다.
`modelSettings`	`ModelSettings`	에이전트별 설정보다 우선하는 전역 튜닝 매개변수입니다. 옵트인 재시도 구성을 포함한 자세한 내용은 모델을 참고하세요.
`handoffInputFilter`	`HandoffInputFilter`	핸드오프를 수행할 때 입력 항목을 변경합니다(핸드오프 자체에 이미 정의된 것이 없는 경우).
`inputGuardrails`	`InputGuardrail[]`	초기 사용자 입력에 적용되는 가드레일입니다.
`outputGuardrails`	`OutputGuardrail[]`	최종 출력에 적용되는 가드레일입니다.
`tracingDisabled`	`boolean`	OpenAI Tracing을 완전히 비활성화합니다.
`traceIncludeSensitiveData`	`boolean`	span은 계속 내보내면서 LLM/도구 입력 및 출력을 trace에서 제외합니다.
`workflowName`	`string`	Traces 대시보드에 표시됩니다. 관련 실행을 그룹화하는 데 도움이 됩니다.
`traceId` / `groupId`	`string`	SDK가 생성하도록 두는 대신 trace 또는 그룹 ID를 수동으로 지정합니다.
`traceMetadata`	`Record<string, string>`	모든 span에 연결할 임의의 메타데이터입니다.
`tracing`	`TracingConfig`	실행별 트레이싱 재정의입니다(예: 내보내기 API 키).
`sessionInputCallback`	`SessionInputCallback`	이 runner의 모든 실행에 대한 기본 기록 병합 전략입니다.
`callModelInputFilter`	`CallModelInputFilter`	각 모델 호출 전에 모델 입력을 편집하는 전역 훅입니다.
`toolErrorFormatter`	`ToolErrorFormatter`	모델에 반환되는 도구 승인 거부 메시지를 사용자 지정하는 전역 훅입니다.
`reasoningItemIdPolicy`	`ReasoningItemIdPolicy`	생성된 항목을 이후 모델 호출에 다시 재생할 때 추론 항목 `id`를 보존하거나 생략하는 기본 정책입니다.
`sandbox`	`SandboxRunConfig`	`SandboxAgent` 실행을 위한 기본 샌드박스 런타임 구성입니다.
`toolExecution`	`ToolExecutionConfig`	로컬 도구 호출을 위한 기본 SDK 측 실행 설정입니다. `maxFunctionToolConcurrency`는 각 턴에서 로컬 함수 도구 동시성을 제한합니다. 설정되지 않았거나 `null`이면 한 턴에서 발생한 모든 함수 도구 호출을 시작합니다. `preApprovalInputGuardrails`는 승인 대기 요청 전에 함수 도구 입력 가드레일 실행을 옵트인합니다.

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

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

상태 및 대화 관리

메모리 전략 선택

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

Strategy	Where state lives	Best for	What you pass on the next turn
`result.history`	앱 메모리	작은 채팅 루프, 완전한 수동 제어, 모든 공급자	`result.history`
`session`	사용자 스토리지 + SDK	영속적인 채팅 상태, 재개 가능한 실행, 사용자 지정 스토어	동일한 `session` 인스턴스(또는 스토어 기반 인스턴스)
`conversationId`	OpenAI Conversations API	워커/서비스 간 공유되는 서버 측 상태	동일한 `conversationId`와 새 사용자 턴만
`previousResponseId`	OpenAI 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는 서버 측 상태를 재사용하는 두 가지 방법을 제공합니다.

1. 전체 대화를 위한 `conversationId`

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`

어차피 Responses API만으로 시작하려는 경우, 이전 응답에서 반환된 ID를 사용해 각 요청을 연결할 수 있습니다. 이렇게 하면 전체 대화 리소스를 만들지 않고도 턴 간 컨텍스트를 유지할 수 있습니다.

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도 사용하는 경우 필터링된 복제본이 영속화되므로, 여기서 적용한 수정이나 잘라내기가 저장된 세션 기록에도 반영됩니다.

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.로 폴백합니다.

현재 포매터는 approval_rejected 이벤트에 대해 실행되며 다음을 받습니다.

kind(현재는 항상 'approval_rejected')
toolType('function', 'computer', 'shell', 또는 'apply_patch')
toolName
callId
defaultMessage(SDK 폴백 메시지, 현재 Tool execution was not approved.)
runContext

메시지를 재정의하려면 문자열을 반환하고, SDK 기본값을 유지하려면 undefined를 반환하세요. 포매터가 예외를 던지거나 문자열이 아닌 값을 반환하면 SDK는 경고를 기록하고 기본 승인 거부 메시지로 폴백합니다.

추론 항목 ID 정책

reasoningItemIdPolicy를 사용해 SDK가 이전에 생성된 실행 항목을 이후 모델 입력을 위한 AgentInputItem[]로 다시 변환할 때 추론 항목이 id 필드를 유지할지 제어하세요.

이는 SDK가 생성된 모델 항목을 입력으로 재생하는 위치에 영향을 줍니다. 예를 들면 다음과 같습니다.

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

이 정책이 변경하지 않는 것은 다음과 같습니다.

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

즉, 이 정책은 SDK가 이전 생성 항목에서 다음 입력을 만들 때 적용됩니다.

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

`callModelInputFilter`와의 상호작용

reasoningItemIdPolicy는 callModelInputFilter보다 먼저 적용됩니다. 사용자 지정 동작이 필요하다면 callModelInputFilter가 준비된 입력을 계속 검사하고 모델 호출 전에 추론 ID를 수동으로 다시 도입하거나 제거할 수 있습니다.

`'omit'` 사용 시점

재생된 추론 항목을 ID 없이 정규화하려는 경우(예: 전달/재생되는 모델 입력을 더 단순하게 유지하거나 앱 파이프라인의 통합 요구 사항에 맞추기 위해) 'omit'을 사용하세요.

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

SDK가 재생된 입력을 통해 추론 항목 ID를 전달하기를 원하고 통합이 이를 허용한다면 'preserve'를 유지하세요.

오류 및 복구

오류 핸들러

errorHandlers를 사용해 지원되는 런타임 오류를 발생시키는 대신 최종 출력으로 변환하세요. 지원되는 키는 maxTurns와 modelRefusal입니다.

errorHandlers.maxTurns는 최대 턴 오류만 처리합니다.
errorHandlers.modelRefusal은 ModelRefusalError로 노출되는 모델 거부를 처리합니다.
errorHandlers.default는 지원되는 종류에 대한 폴백으로 사용됩니다.
핸들러는 { error, context, runData }를 받고 { finalOutput, includeInHistory? }를 반환할 수 있습니다.

예외

SDK는 잡아서 처리할 수 있는 작은 오류 집합을 발생시킵니다.

MaxTurnsExceededError – maxTurns에 도달했습니다.
ModelBehaviorError – 모델이 잘못된 출력을 생성했습니다(예: 잘못된 형식의 JSON, 알 수 없는 도구).
ModelRefusalError – 모델이 요청된 출력 생성을 거부했습니다.
InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered – 가드레일 위반입니다.
ToolInputGuardrailTripwireTriggered / ToolOutputGuardrailTripwireTriggered – 도구 가드레일 위반입니다.
GuardrailExecutionError – 가드레일을 완료하지 못했습니다.
ToolTimeoutError – 함수 도구가 timeoutMs를 초과했고 timeoutBehavior: 'raise_exception'을 사용했습니다.
ToolCallError – 타임아웃이 아닌 오류로 함수 도구 실행에 실패했습니다.
UserError – 구성 또는 사용자 입력에 따라 발생한 모든 오류입니다.

모두 기본 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