도구

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

이 페이지는 에이전트를 읽은 뒤, 어떤 에이전트가 작업을 담당해야 하는지 알고 그 에이전트에 기능을 부여하려고 할 때 읽어보세요. 아직 위임 패턴 사이에서 결정 중이라면 에이전트 오케스트레이션을 참고하세요.

Hosted OpenAI tools – OpenAI 서버에서 모델과 함께 실행됩니다. (웹 검색, 파일 검색, 코드 인터프리터, 이미지 생성, 도구 검색)
기본 제공 실행 도구 – 모델 외부에서 실행되는 SDK 제공 도구입니다. (computer use 와 apply_patch 는 로컬에서 실행되고, shell 은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다)
함수 도구 – JSON 스키마로 로컬 함수를 감싸 LLM 이 호출할 수 있게 합니다.
Agents as tools – 전체 에이전트를 호출 가능한 도구로 노출합니다.
MCP 서버 – Model Context Protocol 서버(로컬 또는 원격)를 연결합니다.
실험적 기능: Codex 도구 – Codex SDK 를 함수 도구로 감싸 workspace 인식 작업을 실행합니다.

도구 카테고리

이 가이드의 나머지 부분에서는 먼저 각 도구 카테고리를 설명한 뒤, 공통으로 적용되는 도구 선택 및 프롬프팅 지침을 요약합니다.

1. Hosted tool(OpenAI Responses API)

OpenAIResponsesModel 을 사용할 때 다음과 같은 기본 제공 도구를 추가할 수 있습니다.

Tool	Type string	Purpose
웹 검색	`'web_search'`	인터넷 검색
파일 / 검색 검색	`'file_search'`	OpenAI 에 호스팅된 벡터 스토어를 조회합니다
Code Interpreter	`'code_interpreter'`	샌드박스 환경에서 코드를 실행합니다
이미지 생성	`'image_generation'`	텍스트를 기반으로 이미지를 생성합니다
도구 검색	`'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 는 hosted tool 정의를 반환하는 헬퍼 함수를 제공합니다.

Helper function	Notes
`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 도구와 함께 사용하세요. 기본적으로 hosted execution 을 지원하며, `execution: 'client'` 와 `execute` 를 함께 사용하면 클라이언트 실행도 가능합니다

이 헬퍼들은 JavaScript/TypeScript 친화적인 옵션 이름을 기반 OpenAI Responses API 도구 페이로드로 매핑합니다. 전체 도구 스키마와 ranking options 또는 semantic filters 같은 고급 옵션은 공식 OpenAI tools guide를, 현재 기본 제공 도구 검색 흐름과 모델 지원 범위는 공식 Tool search guide를 참고하세요.

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 인스턴스
실행마다 Computer 를 생성하는 초기화 함수
실행 범위별 설정과 정리가 필요할 때 사용하는 { create, dispose } 형태의 provider 객체

OpenAI 의 현재 컴퓨터 사용 경로를 사용하려면 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 호출에 대해 보고된 보류 중인 safety checks 를 승인하거나 거부하려면 onSafetyCheck 를 사용하세요. 모델 측 지침과 마이그레이션 세부 내용은 공식 OpenAI computer use guide 및 해당 migration note를 참고하세요.

Shell 도구 세부 사항

shellTool() 에는 두 가지 모드가 있습니다.

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

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

호스티드 컨테이너 모드에서는 shellTool({ environment }) 를 다음 중 하나로 설정합니다.

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

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

domainSecrets 를 포함한 허용 목록 설정이 가능한 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.`;
  },
});

옵션 참조

Field	Required	Description
`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` 를 발생시킵니다
`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를 발생시키며, 이를 실행 예외의 일부로 잡을 수 있습니다
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;
  },
});

도구 검색을 통한 지연 도구 로딩

도구 검색을 사용하면 모든 스키마를 미리 보내는 대신, 모델이 런타임에 필요한 도구 정의만 로드할 수 있습니다. SDK 에서는 이를 통해 지연 top-level 함수 도구, toolNamespace() 그룹, 그리고 deferLoading: true 로 설정된 호스티드 MCP 도구를 사용할 수 있습니다.

도구 검색은 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 은 독립적인 검색 가능 기능 하나이므로 top-level 로 유지됩니다
crmTools 는 관련된 CRM 도구들이 하나의 상위 레이블과 설명을 공유하므로 toolNamespace() 를 사용합니다
같은 요청에서 네임스페이스가 있는 지연 도구와 top-level 지연 도구를 함께 사용하는 것이 지원됩니다. 도구 검색은 crm 같은 네임스페이스 경로와 get_shipping_eta 같은 top-level 경로를 모두 로드할 수 있습니다

도구 검색을 사용할 때는 다음을 따르세요.

각 지연 함수 도구에 deferLoading: true 를 설정하세요
여러 관련 도구가 하나의 도메인 설명을 공유하고 그룹으로 로드되어야 한다면 toolNamespace({ name, description, tools }) 를 사용하세요
도구가 하나의 독립 기능이고 도구 이름 자체가 좋은 검색 대상이라면 top-level 로 유지하세요
지연 함수 도구나 호스티드 MCP 도구 중 하나라도 deferLoading: true 를 사용한다면 같은 tools 배열에 toolSearchTool() 을 추가하세요
modelSettings.toolChoice 는 'auto' 로 두세요. SDK 는 기본 제공 tool_search 도구를 강제하거나 지연 함수 도구를 이름으로 강제하는 것을 거부합니다
기본값은 hosted execution 입니다. toolSearchTool({ execution: 'client', execute }) 를 설정한 경우 표준 run() 루프는 기본 제공 { paths: string[] } 클라이언트 쿼리 형태만 지원하며, 사용자 정의 클라이언트 측 스키마는 별도의 Responses 루프가 필요합니다
네임스페이스는 즉시 로드되는 멤버와 지연 멤버를 함께 포함할 수 있습니다. 즉시 멤버는 도구 검색 없이도 계속 호출 가능하고, 같은 네임스페이스의 지연 멤버는 필요 시 로드됩니다
지연 함수 도구와 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 를 설정하여 휴먼 인 더 루프 흐름 및 조건부 도구 가용성과 통합할 수 있습니다.

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() 의 고급 structured-input 옵션:

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

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

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

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 서버

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

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

const server = new MCPServerStdio({
  fullCommand: 'pnpm exec mcp-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 는 모델 도구 호출을 Codex SDK 로 라우팅하는 함수 도구 codexTool() 을 제공합니다. 이를 통해 에이전트가 workspace 범위 작업(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 는 최신 스레드 ID 를 runContext.context 에서 읽고 저장하며, 앱 상태에서 턴 간 재사용에 유용합니다
스레드 ID 우선순위: 도구 호출 threadId(스키마에 포함된 경우)가 가장 우선하고, 그다음 run-context 스레드 ID, 마지막으로 codexTool({ threadId }) 입니다
실행 컨텍스트 키: 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 등)를 제어하는 방법은 에이전트 가이드를 참고하세요.

모범 사례

짧고 명시적인 설명 – 도구가 무엇을 하는지 와 언제 사용해야 하는지 를 설명하세요
입력 검증 – 가능하면 엄격한 JSON 검증을 위해 Zod 스키마를 사용하세요
오류 핸들러에서 부작용 방지 – errorFunction 은 예외를 던지지 말고 도움이 되는 문자열을 반환해야 합니다
도구당 하나의 책임 – 작고 조합 가능한 도구일수록 모델 추론 성능이 좋아집니다

도구