도구

도구를 사용하면 에이전트가 작업을 수행할 수 있습니다. 데이터를 가져오고, 외부 API를 호출하고, 코드를 실행하고, 심지어 컴퓨터를 사용할 수도 있습니다. JavaScript/TypeScript SDK는 6가지 카테고리를 지원합니다.

어떤 에이전트가 작업을 담당해야 하는지 알고 있고 해당 에이전트에 기능을 부여하려는 단계라면 에이전트 다음으로 이 페이지를 읽어보세요. 위임 패턴을 아직 결정 중이라면 에이전트 오케스트레이션을 참고하세요.

OpenAI 호스트하는 도구 – OpenAI 서버에서 모델과 함께 실행됩니다. (웹 검색, 파일 검색, Code Interpreter, 이미지 생성, tool search)
내장 실행 도구 – 모델 외부에서 실행되는 SDK 제공 도구입니다. (computer use와 apply_patch는 로컬에서 실행, shell은 로컬 또는 호스팅 컨테이너에서 실행 가능)
함수 도구 – JSON 스키마와 함께 로컬 함수를 감싸 LLM이 호출할 수 있게 합니다.
Agents as tools – 전체 에이전트를 호출 가능한 도구로 노출합니다.
MCP 서버 – Model Context Protocol 서버(로컬 또는 원격)를 연결합니다.
실험적 기능: Codex 도구 – Codex SDK를 함수 도구로 감싸 워크스페이스 인지 작업을 실행합니다.

도구 카테고리

이 가이드의 나머지 부분에서는 먼저 각 도구 카테고리를 설명하고, 이후 도구 선택 및 프롬프팅에 대한 공통 가이드를 요약합니다.

1. 호스티드 툴 (OpenAI Responses API)

OpenAIResponsesModel을 사용할 때 다음 내장 도구를 추가할 수 있습니다.

도구	타입 문자열	목적
웹 검색	`'web_search'`	인터넷 검색
파일 / 검색 검색	`'file_search'`	OpenAI에 호스팅된 벡터 스토어 조회
Code Interpreter	`'code_interpreter'`	샌드박스 환경에서 코드 실행
이미지 생성	`'image_generation'`	텍스트 기반 이미지 생성
Tool search	`'tool_search'`	지연 로드 함수 도구, 네임스페이스, 또는 검색 가능한 MCP 도구를 런타임에 로드

import {
  Agent,
  codeInterpreterTool,
  fileSearchTool,
  imageGenerationTool,
  webSearchTool,
} from '@openai/agents';

const agent = new Agent({
  name: 'Travel assistant',
  tools: [
    webSearchTool({ searchContextSize: 'medium' }),
    fileSearchTool('VS_ID', { maxNumResults: 3 }),
    codeInterpreterTool(),
    imageGenerationTool({ size: '1024x1024' }),
  ],
});

SDK는 호스티드 툴 정의를 반환하는 헬퍼 함수를 제공합니다.

헬퍼 함수	참고
`webSearchTool(options?)`	`searchContextSize`, `userLocation`, `filters.allowedDomains` 같은 JS 친화적 옵션
`fileSearchTool(ids, options?)`	첫 번째 인수로 하나 이상의 벡터 스토어 ID를 받고, `maxNumResults`, `includeSearchResults`, `rankingOptions`, 필터 등의 옵션 지원
`codeInterpreterTool(options?)`	`container`를 지정하지 않으면 자동 관리 컨테이너를 기본값으로 사용
`imageGenerationTool(options?)`	`model`, `size`, `quality`, `background`, `inputFidelity`, `inputImageMask`, `moderation`, `outputCompression`, `partialImages`, 출력 형식 등 이미지 생성 설정 지원
`toolSearchTool(options?)`	내장 `tool_search` 헬퍼 추가. `deferLoading: true`를 설정한 지연 로드 함수 도구 또는 호스티드 MCP 도구와 함께 사용. 기본적으로 호스티드 실행을 지원하며, `execution: 'client'`와 `execute`를 통해 클라이언트 실행도 지원

이 헬퍼들은 JavaScript/TypeScript 친화적인 옵션 이름을 OpenAI Responses API의 실제 툴 페이로드로 매핑합니다. 전체 툴 스키마와 ranking options, semantic filters 같은 고급 옵션은 공식 OpenAI 도구 가이드를 참고하세요. 현재 내장 tool-search 흐름과 모델 가용성은 공식 Tool search 가이드를 참고하세요.

2. 내장 실행 도구

이 도구들은 SDK에 내장되어 있지만, 실행은 모델 응답 자체 외부에서 이뤄집니다.

컴퓨터 사용 – Computer 인터페이스를 구현해 computerTool()에 전달합니다. 이는 항상 사용자가 제공한 로컬 Computer 구현에서 실행됩니다.
Shell – 로컬 Shell 구현을 제공하거나 shellTool({ environment })로 호스팅 컨테이너 환경을 구성할 수 있습니다.
Apply patch – Editor 인터페이스를 구현해 applyPatchTool()에 전달합니다. 이는 항상 사용자가 제공한 로컬 Editor 구현에서 실행됩니다.

도구 호출은 여전히 모델이 요청하지만, 실제 작업은 애플리케이션 또는 구성한 실행 환경이 수행합니다.

import {
  Agent,
  applyPatchTool,
  computerTool,
  shellTool,
  Computer,
  Editor,
  Shell,
} from '@openai/agents';

const computer: Computer = {
  environment: 'browser',
  dimensions: [1024, 768],
  screenshot: async () => '',
  click: async () => {},
  doubleClick: async () => {},
  scroll: async () => {},
  type: async () => {},
  wait: async () => {},
  move: async () => {},
  keypress: async () => {},
  drag: async () => {},
};

const shell: Shell = {
  run: async () => ({
    output: [
      {
        stdout: '',
        stderr: '',
        outcome: { type: 'exit', exitCode: 0 },
      },
    ],
  }),
};

const editor: Editor = {
  createFile: async () => ({ status: 'completed' }),
  updateFile: async () => ({ status: 'completed' }),
  deleteFile: async () => ({ status: 'completed' }),
};

const agent = new Agent({
  name: 'Local tools agent',
  model: 'gpt-5.4',
  tools: [
    computerTool({ computer }),
    shellTool({ shell, needsApproval: true }),
    applyPatchTool({ editor, needsApproval: true }),
  ],
});

Computer 도구 세부 사항

computerTool()은 다음 중 하나를 받습니다.

구체적인 Computer 인스턴스
실행(run)마다 Computer를 생성하는 초기화 함수
실행 범위 설정/정리가 필요한 경우 { create, dispose } 형태의 provider 객체

OpenAI의 최신 computer-use 경로를 사용하려면 gpt-5.4 같은 컴퓨터 사용 가능 모델을 설정하세요. 요청 모델이 명시적이면 SDK는 GA 내장 computer 도구 형태를 전송합니다. 유효 모델이 저장된 프롬프트나 이전 통합에서 계속 오면, 명시적으로 modelSettings.toolChoice: 'computer'로 GA 경로를 선택하지 않는 한 호환성을 위해 레거시 computer_use_preview wire 형태를 유지합니다.

GA computer 호출은 단일 computer_call에 배치된 actions[]를 포함할 수 있습니다. SDK는 이를 순서대로 실행하고 각 액션에 대해 needsApproval을 평가한 뒤 최종 스크린샷을 도구 출력으로 반환합니다. interruption.rawItem으로 승인 UI를 만든다면, actions가 있으면 이를 읽고 레거시 preview 항목에서는 action으로 폴백하세요.

영향이 큰 컴퓨터 작업을 사용자 검토를 위해 일시 중지하려면 needsApproval을 사용하고, computer 호출에 대해 보고된 보류 안전성 검사를 승인 또는 거부하려면 onSafetyCheck를 사용하세요. 모델 측 가이드와 마이그레이션 세부 사항은 공식 OpenAI computer use 가이드 및 마이그레이션 노트를 참고하세요.

Shell 도구 세부 사항

shellTool()은 두 가지 모드를 가집니다.

로컬 모드: shell을 제공하고, 필요 시 environment: { type: 'local', skills }와 자동 승인 처리를 위한 needsApproval, onApproval 제공
호스티드 컨테이너 모드: type: 'container_auto' 또는 type: 'container_reference'를 포함한 environment 제공

로컬 모드에서 environment.skills를 사용하면 name, description, 파일시스템 path로 로컬 skills를 마운트할 수 있습니다.

호스티드 컨테이너 모드에서는 shellTool({ environment })를 다음과 같이 구성합니다.

type: 'container_auto': 실행을 위한 관리형 컨테이너 생성
type: 'container_reference': containerId로 기존 컨테이너 재사용

호스티드 container_auto 환경은 다음을 지원합니다.

domainSecrets allowlist를 포함한 networkPolicy
업로드한 파일 마운트를 위한 fileIds
컨테이너 크기 조정을 위한 memoryLimit
skill_reference 또는 인라인 zip 번들 방식의 skills

호스티드 shell 환경은 실행이 로컬 프로세스가 아닌 호스티드 컨테이너 환경에서 이뤄지므로 shell, needsApproval, onApproval을 받지 않습니다.

전체 사용 예시는 examples/tools/local-shell.ts, examples/tools/container-shell-skill-ref.ts, examples/tools/container-shell-inline-skill.ts를 참고하세요.

Apply-patch 도구 세부 사항

applyPatchTool()은 shellTool()의 로컬 승인 흐름을 그대로 따릅니다. 파일 편집 전에 중지하려면 needsApproval을, 앱 레벨 콜백으로 자동 승인/거부하려면 onApproval을 사용하세요.

3. 함수 도구

tool() 헬퍼를 사용하면 어떤 함수든 도구로 바꿀 수 있습니다.

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

const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the weather for a given city',
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

옵션 참조

필드	필수 여부	설명
`name`	아니요	기본값은 함수 이름(예: `get_weather`)
`description`	예	LLM에 표시되는 명확하고 사람이 읽기 쉬운 설명
`parameters`	예	Zod 스키마 또는 원문 JSON 스키마 객체. Zod 매개변수는 자동으로 strict 모드를 활성화
`strict`	아니요	`true`(기본값)면 인수가 검증에 실패할 때 SDK가 모델 오류를 반환. 유사 매칭을 원하면 `false` 설정
`execute`	예	`(args, context, details) => string \| unknown \| Promise<...>` – 비즈니스 로직. 문자열이 아닌 출력은 모델용으로 직렬화됩니다. `context`는 선택적 `RunContext`, `details`에는 `toolCall`, `resumeState`, `signal` 같은 메타데이터 포함
`errorFunction`	아니요	내부 오류를 사용자에게 보이는 문자열로 변환하는 커스텀 핸들러 `(context, error) => string`
`timeoutMs`	아니요	호출당 타임아웃(밀리초). 0보다 크고 `2147483647` 이하여야 함
`timeoutBehavior`	아니요	타임아웃 모드: `error_as_result`(기본값)는 모델에 보이는 타임아웃 메시지를 반환, `raise_exception`은 `ToolTimeoutError`를 throw
`timeoutErrorFunction`	아니요	`timeoutBehavior`가 `error_as_result`일 때 타임아웃 출력을 위한 커스텀 핸들러 `(context, timeoutError) => string`
`needsApproval`	아니요	실행 전 사람의 승인 요구. 휴먼 인 더 루프 (HITL) 가이드 참고
`isEnabled`	아니요	실행별 조건부 도구 노출. boolean 또는 predicate 허용
`inputGuardrails`	아니요	도구 실행 전 동작하는 가드레일, 거부 또는 예외 가능. 가드레일 참고
`outputGuardrails`	아니요	도구 실행 후 동작하는 가드레일, 거부 또는 예외 가능. 가드레일 참고

함수 도구 타임아웃

각 함수 도구 호출의 상한 시간을 설정하려면 timeoutMs를 사용하세요.

timeoutBehavior: 'error_as_result'(기본값)은 Tool '<name>' timed out after <timeoutMs>ms.를 모델에 반환합니다
timeoutBehavior: 'raise_exception'은 ToolTimeoutError를 throw하며, 에이전트 실행의 실행 예외로 처리할 수 있습니다
timeoutErrorFunction을 사용하면 error_as_result 모드의 타임아웃 메시지를 커스터마이즈할 수 있습니다
타임아웃은 details.signal을 중단하므로, 장시간 실행 도구는 취소 신호를 수신할 때 빠르게 멈출 수 있습니다

함수 도구를 직접 호출한다면 invokeFunctionTool을 사용해 일반 에이전트 실행과 동일한 타임아웃 동작을 적용하세요.

Non‑strict JSON‑schema 도구

모델이 잘못되거나 부분적인 입력을 추정하도록 해야 한다면 원문 JSON 스키마 사용 시 strict 모드를 비활성화할 수 있습니다.

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

interface LooseToolInput {
  text: string;
}

const looseTool = tool({
  description: 'Echo input; be forgiving about typos',
  strict: false,
  parameters: {
    type: 'object',
    properties: { text: { type: 'string' } },
    required: ['text'],
    additionalProperties: true,
  },
  execute: async (input) => {
    // because strict is false we need to do our own verification
    if (typeof input !== 'object' || input === null || !('text' in input)) {
      return 'Invalid input. Please try again';
    }
    return (input as LooseToolInput).text;
  },
});

tool search를 통한 지연 도구 로딩

Tool search를 사용하면 모든 스키마를 미리 보내는 대신 런타임에 필요한 도구 정의만 모델이 로드할 수 있습니다. SDK에서는 지연 로드 최상위 함수 도구, toolNamespace() 그룹, deferLoading: true로 구성된 호스티드 MCP 도구를 이 방식으로 처리합니다.

Tool search는 Responses API에서 이를 지원하는 GPT-5.4 이상 모델 릴리스에서만 사용하세요.

import { Agent, tool, toolNamespace, toolSearchTool } from '@openai/agents';
import { z } from 'zod';

const customerIdParams = z.object({
  customerId: z.string().describe('The customer identifier to look up.'),
});

// Keep a standalone deferred tool at the top level when it represents a
// single searchable capability that does not need a shared namespace.
const shippingLookup = tool({
  name: 'get_shipping_eta',
  description: 'Look up a shipment ETA by customer identifier.',
  parameters: customerIdParams,
  deferLoading: true,
  async execute({ customerId }) {
    return {
      customerId,
      eta: '2026-03-07',
      carrier: 'Priority Express',
    };
  },
});

// Group related tools into a namespace when one domain description should
// cover several deferred tools and let tool search load them together.
const crmTools = toolNamespace({
  name: 'crm',
  description: 'CRM tools for customer profile lookups.',
  tools: [
    tool({
      name: 'get_customer_profile',
      description: 'Fetch a basic customer profile.',
      parameters: customerIdParams,
      deferLoading: true,
      async execute({ customerId }) {
        return {
          customerId,
          tier: 'enterprise',
        };
      },
    }),
  ],
});

const agent = new Agent({
  name: 'Operations assistant',
  model: 'gpt-5.4',
  // Mixing namespaced and top-level deferred tools in one request is supported.
  tools: [shippingLookup, ...crmTools, toolSearchTool()],
});

이 예시는 의도적으로 두 스타일을 함께 사용합니다.

shippingLookup은 독립적인 검색 가능 기능 하나이므로 최상위로 유지
crmTools는 관련 CRM 도구가 하나의 상위 레이블과 설명을 공유하므로 toolNamespace() 사용
같은 요청에서 네임스페이스 도구와 최상위 지연 도구를 함께 사용하는 것이 지원되며, tool search는 crm 같은 네임스페이스 경로와 get_shipping_eta 같은 최상위 경로를 모두 로드할 수 있음

tool search를 사용할 때는 다음을 따르세요.

각 지연 함수 도구에 deferLoading: true를 설정
관련 도구 여러 개가 하나의 도메인 설명을 공유하며 그룹으로 로드되어야 하면 toolNamespace({ name, description, tools }) 사용
단일 독립 기능이고 도구 이름 자체가 좋은 검색 대상이면 최상위 도구로 유지
지연 함수 도구 또는 호스티드 MCP 도구가 deferLoading: true를 사용할 때마다 같은 tools 배열에 toolSearchTool() 추가
modelSettings.toolChoice는 'auto'로 유지. SDK는 내장 tool_search 도구나 지연 함수 도구를 이름으로 강제하는 설정을 거부
기본값은 호스티드 실행. toolSearchTool({ execution: 'client', execute })를 설정하면 표준 run() 루프는 내장 { paths: string[] } 클라이언트 질의 형태만 지원하며, 커스텀 클라이언트 스키마는 자체 Responses 루프 필요
하나의 네임스페이스에 즉시 로드 멤버와 지연 로드 멤버를 혼합 가능. 즉시 멤버는 tool search 없이 호출 가능하고, 같은 네임스페이스의 지연 멤버는 필요 시 로드
지연 함수 도구와 toolNamespace()는 Responses 전용. Chat Completions는 이를 거부하며 AI SDK 어댑터도 지연 Responses 도구 로딩 흐름을 지원하지 않음

4. Agents as tools

대화를 완전히 핸드오프하지 않고 한 에이전트가 다른 에이전트를 보조하게 하고 싶을 때가 있습니다. 이때 agent.asTool()을 사용하세요.

agent.asTool()과 handoff() 사이에서 아직 선택 중이라면 에이전트와 에이전트 오케스트레이션에서 패턴을 비교해 보세요.

import { Agent } from '@openai/agents';

const summarizer = new Agent({
  name: 'Summarizer',
  instructions: 'Generate a concise summary of the supplied text.',
});

const summarizerTool = summarizer.asTool({
  toolName: 'summarize_text',
  toolDescription: 'Generate a concise summary of the supplied text.',
});

const mainAgent = new Agent({
  name: 'Research assistant',
  tools: [summarizerTool],
});

내부적으로 SDK는 다음을 수행합니다.

단일 input 매개변수를 가진 함수 도구를 생성
도구가 호출되면 해당 입력으로 하위 에이전트를 실행
마지막 메시지 또는 customOutputExtractor가 추출한 출력을 반환

에이전트를 도구로 실행할 때 Agents SDK는 기본 설정으로 runner를 만들고 함수 실행 내부에서 그 runner로 에이전트를 실행합니다. runConfig나 runOptions의 속성을 제공하고 싶다면 asTool() 메서드에 전달해 runner 동작을 커스터마이즈할 수 있습니다.

또한 asTool() 옵션으로 에이전트 도구에 needsApproval과 isEnabled를 설정해 휴먼인더루프 (HITL) 흐름 및 조건부 도구 가용성과 통합할 수 있습니다.

customOutputExtractor 내부에서는 result.agentToolInvocation으로 현재 Agent.asTool() 호출을 확인하세요. 이 콜백에서 결과는 항상 Agent.asTool()에서 오므로 agentToolInvocation은 항상 정의되며 toolName, toolCallId, toolArguments를 제공합니다. 일반 앱 컨텍스트와 toolInput은 result.runContext를 사용하세요. 이 메타데이터는 현재 중첩 호출 범위로 한정되며 RunState에 직렬화되지 않습니다.

import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: 'Handle billing questions and subscription changes.',
});

const billingTool = billingAgent.asTool({
  toolName: 'billing_agent',
  toolDescription: 'Handles customer billing questions.',
  customOutputExtractor(result) {
    console.log('tool', result.agentToolInvocation.toolName);
    // Direct invoke() calls may not have a model-generated tool call id.
    console.log('call', result.agentToolInvocation.toolCallId);
    console.log('args', result.agentToolInvocation.toolArguments);

    return String(result.finalOutput ?? '');
  },
});

const orchestrator = new Agent({
  name: 'Support Orchestrator',
  instructions: 'Delegate billing questions to the billing agent tool.',
  tools: [billingTool],
});

agent.asTool()의 고급 구조화 입력 옵션:

inputBuilder: 구조화된 도구 인수를 중첩 에이전트 입력 페이로드로 매핑
includeInputSchema: 더 강한 스키마 인지 동작을 위해 중첩 실행에 입력 JSON 스키마 포함
resumeState: 중첩 직렬화 RunState 재개 시 컨텍스트 조정 전략 제어. 'merge'(기본값)는 라이브 승인/컨텍스트 상태를 직렬화 상태에 병합, 'replace'는 현재 실행 컨텍스트 사용, 'preferSerialized'는 직렬화된 컨텍스트를 변경 없이 사용해 재개

에이전트 도구의 스트리밍 이벤트

에이전트 도구는 모든 중첩 실행 이벤트를 앱으로 스트리밍할 수 있습니다. 도구 구성 방식에 맞는 훅 스타일을 선택하세요.

import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: 'Answer billing questions and compute simple charges.',
});

const billingTool = billingAgent.asTool({
  toolName: 'billing_agent',
  toolDescription: 'Handles customer billing questions.',
  // onStream: simplest catch-all when you define the tool inline.
  onStream: (event) => {
    console.log(`[onStream] ${event.event.type}`, event);
  },
});

// on(eventName) lets you subscribe selectively (or use '*' for all).
billingTool.on('run_item_stream_event', (event) => {
  console.log('[on run_item_stream_event]', event);
});
billingTool.on('raw_model_stream_event', (event) => {
  console.log('[on raw_model_stream_event]', event);
});

const orchestrator = new Agent({
  name: 'Support Orchestrator',
  instructions: 'Delegate billing questions to the billing agent tool.',
  tools: [billingTool],
});

이벤트 타입은 RunStreamEvent['type']와 일치: raw_model_stream_event, run_item_stream_event, agent_updated_stream_event
onStream은 가장 단순한 “catch-all” 방식이며 도구를 인라인으로 선언할 때(tools: [agent.asTool({ onStream })]) 잘 맞습니다. 이벤트별 분기가 필요 없을 때 사용하세요
on(eventName, handler)는 선택적 구독(또는 '*')이 가능하며, 더 세밀한 처리나 생성 후 리스너 부착이 필요할 때 적합합니다
onStream 또는 하나 이상의 on(...) 핸들러를 제공하면 agent-as-tool은 자동으로 스트리밍 모드로 실행되며, 없으면 비스트리밍 경로를 사용합니다
핸들러는 병렬로 호출되므로 느린 onStream 콜백이 on(...) 핸들러를 막지 않습니다(반대도 동일)
toolCallId는 모델 도구 호출을 통해 호출된 경우 제공되며, 직접 invoke() 호출이나 provider 특성에 따라 생략될 수 있습니다

5. MCP 서버

MCP (Model Context Protocol) 서버를 통해 도구를 노출하고 에이전트에 연결할 수 있습니다. 예를 들어 MCPServerStdio를 사용해 stdio MCP 서버를 실행하고 연결할 수 있습니다.

import { Agent, MCPServerStdio } from '@openai/agents';

const server = new MCPServerStdio({
  fullCommand: 'npx -y @modelcontextprotocol/server-filesystem ./sample_files',
});

await server.connect();

const agent = new Agent({
  name: 'Assistant',
  mcpServers: [server],
});

전체 예시는 filesystem-example.ts를 참고하세요. 또한 MCP 서버 도구 통합에 대한 포괄적인 가이드는 모델 컨텍스트 프로토콜 (MCP)에서 확인할 수 있습니다. 여러 서버(또는 부분 실패)를 관리할 때는 connectMcpServers와 모델 컨텍스트 프로토콜 (MCP)의 라이프사이클 가이드를 사용하세요.

6. 실험적 기능: Codex 도구

@openai/agents-extensions/experimental/codex는 codexTool()을 제공합니다. 이는 모델 도구 호출을 Codex SDK로 라우팅하는 함수 도구로, 에이전트가 워크스페이스 범위 작업(shell, 파일 편집, MCP 도구)을 자율적으로 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다.

먼저 의존성을 설치하세요.

npm install @openai/agents-extensions @openai/codex-sdk

빠른 시작:

import { Agent } from '@openai/agents';
import { codexTool } from '@openai/agents-extensions/experimental/codex';

export const codexAgent = new Agent({
  name: 'Codex Agent',
  instructions:
    'Use the codex tool to inspect the workspace and answer the question. When skill names, which usually start with `$`, are mentioned, you must rely on the codex tool to use the skill and answer the question.',
  tools: [
    codexTool({
      sandboxMode: 'workspace-write',
      workingDirectory: '/path/to/repo',
      defaultThreadOptions: {
        model: 'gpt-5.4',
        networkAccessEnabled: true,
        webSearchEnabled: false,
      },
    }),
  ],
});

알아두어야 할 점:

인증: CODEX_API_KEY(권장) 또는 OPENAI_API_KEY를 제공하거나 codexOptions.apiKey 전달
입력: strict 스키마—inputs에는 최소 하나의 { type: 'text', text } 또는 { type: 'local_image', path }가 포함되어야 함
안전성: sandboxMode를 workingDirectory와 함께 사용하고, 디렉터리가 Git 저장소가 아니면 skipGitRepoCheck 설정
스레딩: useRunContextThreadId: true는 최신 thread id를 runContext.context에서 읽고 저장하며, 앱 상태에서 턴 간 재사용에 유용
Thread ID 우선순위: 도구 호출 threadId(스키마에 포함된 경우) > run-context thread id > codexTool({ threadId })
Run context 키: name: 'codex'면 기본값 codexThreadId, name: 'engineer' 같은 이름이면 codexThreadId_<suffix>(codex_engineer로 정규화 후)
변경 가능한 컨텍스트 요구사항: useRunContextThreadId 활성화 시 run(..., { context })에 변경 가능한 객체 또는 Map 전달
네이밍: 도구 이름은 codex 네임스페이스로 정규화됨(engineer → codex_engineer), 동일 에이전트 내 중복 Codex 도구 이름은 거부됨
스트리밍: onStream은 Codex 이벤트(reasoning, 명령 실행, MCP 도구 호출, 파일 변경, 웹 검색)를 미러링하므로 진행 상황 로깅/트레이싱 가능
출력: 도구 결과에는 response, usage, threadId가 포함되며 Codex 토큰 사용량은 RunContext에 기록됨
구조: outputSchema는 descriptor, JSON 스키마 객체 또는 Zod 객체 가능. JSON 객체 스키마에서는 additionalProperties가 false여야 함

run-context 스레드 재사용 예시:

import { Agent, run } from '@openai/agents';
import { codexTool } from '@openai/agents-extensions/experimental/codex';

// Derived from codexTool({ name: 'engineer' }) when runContextThreadIdKey is omitted.
type ExampleContext = {
  codexThreadId_engineer?: string;
};

const agent = new Agent<ExampleContext>({
  name: 'Codex assistant',
  instructions: 'Use the codex tool for workspace tasks.',
  tools: [
    codexTool({
      // `name` is optional for a single Codex tool.
      // We set it so the run-context key is tool-specific and to avoid collisions when adding more Codex tools.
      name: 'engineer',
      // Reuse the same Codex thread across runs that share this context object.
      useRunContextThreadId: true,
      sandboxMode: 'workspace-write',
      workingDirectory: '/path/to/repo',
      defaultThreadOptions: {
        model: 'gpt-5.4',
        approvalPolicy: 'never',
      },
    }),
  ],
});

// The default key for useRunContextThreadId with name=engineer is codexThreadId_engineer.
const context: ExampleContext = {};

// First turn creates (or resumes) a Codex thread and stores the thread ID in context.
await run(agent, 'Inspect src/tool.ts and summarize it.', { context });
// Second turn reuses the same thread because it shares the same context object.
await run(agent, 'Now list refactoring opportunities.', { context });

const threadId = context.codexThreadId_engineer;

도구 전략 및 모범 사례

도구 사용 동작

모델이 도구를 언제/어떻게 반드시 사용해야 하는지(modelSettings.toolChoice, toolUseBehavior 등) 제어하려면 에이전트를 참고하세요.

모범 사례

짧고 명확한 설명 – 도구가 무엇을 하는지 와 언제 사용해야 하는지 를 설명하세요
입력 검증 – 가능하면 strict JSON 검증을 위해 Zod 스키마를 사용하세요
오류 핸들러에서 부작용 피하기 – errorFunction은 throw하지 말고 유용한 문자열을 반환해야 합니다
도구당 단일 책임 – 작고 조합 가능한 도구가 모델의 추론 품질을 높입니다

도구