콘텐츠로 이동

도구

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

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

  1. OpenAI 호스티드 툴 – OpenAI 서버에서 모델과 함께 실행됩니다. (웹 검색, 파일 검색, code interpreter, 이미지 생성, 도구 검색)
  2. 기본 제공 실행 도구 – 모델 외부에서 실행되는 SDK 제공 도구입니다. (컴퓨터 사용과 apply_patch는 로컬에서 실행되며, 셸은 로컬 또는 호스티드 컨테이너에서 실행할 수 있습니다)
  3. 함수 도구 – 로컬 함수를 JSON 스키마로 감싸 LLM이 호출할 수 있도록 합니다.
  4. Agents as tools – 에이전트 전체를 호출 가능한 도구로 노출합니다.
  5. MCP 서버 – Model Context Protocol 서버(로컬 또는 원격)를 연결합니다.
  6. 샌드박스 기능 – 워크스페이스 범위의 셸, 파일 시스템, 스킬, 메모리 또는 컴팩션 도구를 SandboxAgent에 연결합니다.
  7. 실험적 기능: Codex 도구 – Codex SDK를 함수 도구로 감싸 워크스페이스를 인식하는 작업을 실행합니다.

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

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

섹션 제목: “1. 호스티드 툴 (OpenAI Responses API)”

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

도구유형 문자열용도
웹 검색'web_search'인터넷 검색입니다.
파일 / 검색 기반 조회'file_search'OpenAI에서 호스팅하는 벡터 스토어를 쿼리합니다.
Code Interpreter'code_interpreter'샌드박스 환경에서 코드를 실행합니다.
이미지 생성'image_generation'텍스트를 기반으로 이미지를 생성합니다.
도구 검색'tool_search'지연 로딩되는 함수 도구, 네임스페이스 또는 검색 가능한 MCP 도구를 런타임에 로드합니다.
프로그래밍 방식 도구 호출'programmatic_tool_calling'사용 가능한 도구들을 조율하는 모델 생성 JavaScript를 실행합니다.
호스티드 툴
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, searchContentTypes, imageSettings 등 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를 사용하면 클라이언트 실행을 지원합니다.
programmaticToolCallingTool()프로그래밍 방식 도구 호출을 활성화합니다. allowedCallers에 'programmatic'이 포함된 도구와 함께 사용하세요.

이 헬퍼들은 JavaScript/TypeScript 친화적인 옵션 이름을 내부 OpenAI Responses API 도구 페이로드로 매핑합니다. 이미지 검색 결과를 요청하려면 webSearchTool({ searchContentTypes })에 'image'를 포함하세요. imageSettings.maxResults를 사용하여 양수 개수의 이미지를 요청하고, imageSettings.caption을 사용하여 사용 가능한 경우 캡션을 요청하세요. SDK는 searchContentTypes에 'image'가 포함될 때마다 원문 웹 검색 결과를 요청하며, 반환된 이미지 URL과 메타데이터를 웹 검색 호출 항목의 providerData.results에 노출합니다.

전체 도구 스키마와 순위 지정 옵션 또는 시맨틱 필터 같은 고급 옵션은 공식 OpenAI 도구 가이드를, 이미지 결과 필드는 공식 웹 검색 가이드를, 현재 기본 제공 도구 검색 흐름과 사용 가능한 모델은 공식 도구 검색 가이드를, 모델 지원 및 통신 수준 동작은 공식 프로그래밍 방식 도구 호출 가이드를 참고하세요.


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

  • 컴퓨터 사용 – Computer 인터페이스를 구현하고 computerTool()에 전달합니다. 항상 개발자가 제공하는 로컬 Computer 구현을 대상으로 실행됩니다.
  • 셸 – 로컬 Shell 구현을 제공하거나, shellTool({ environment })로 호스티드 컨테이너 환경을 설정합니다.
  • 패치 적용 – Editor 인터페이스를 구현하고 applyPatchTool()에 전달합니다. 항상 개발자가 제공하는 로컬 Editor 구현을 대상으로 실행됩니다.
  • 샌드박스 셸 및 파일 시스템 도구 – 해당 작업을 샌드박스 워크스페이스 내부에서 실행해야 할 때 SandboxAgent에서 shell(), filesystem(), skills(), memory() 또는 compaction()을 사용합니다.

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

샌드박스 기능 도구는 프로세스 전역의 기본 제공 도구와 다릅니다. 현재 SandboxAgent 실행의 활성 샌드박스 세션에 바인딩됩니다. 도구가 애플리케이션 프로세스 대신 에이전트의 격리된 워크스페이스에서 작동해야 한다면 빠른 시작을 참고하세요.

기본 제공 실행 도구
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 }),
],
});

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

  • 구체적인 Computer 인스턴스
  • 실행마다 Computer를 생성하는 초기화 함수
  • 실행 범위의 설정 및 정리가 필요한 경우 { create, dispose }를 포함하는 제공자 객체

OpenAI의 현재 컴퓨터 사용 경로를 사용하려면 gpt-5.4처럼 컴퓨터 사용을 지원하는 모델을 설정하세요. 요청 모델을 명시하면 SDK는 정식 출시(GA)된 기본 제공 computer 도구 형식을 전송합니다. 실제 적용되는 모델이 여전히 저장된 프롬프트나 이전 통합에서 결정되는 경우, modelSettings.toolChoice: 'computer'로 GA 경로를 명시적으로 선택하지 않는 한 SDK는 호환성을 위해 기존 computer_use_preview 통신 형식을 유지합니다.

GA 컴퓨터 호출은 단일 computer_call에 여러 작업을 묶은 actions[]를 포함할 수 있습니다. SDK는 이를 순서대로 실행하고, 각 작업에 대해 needsApproval을 평가한 후, 최종 스크린샷을 도구 출력으로 반환합니다. interruption.rawItem을 기반으로 승인 UI를 구축하는 경우 actions가 있으면 이를 읽고, 기존 프리뷰 항목에서는 action을 사용하세요.

영향이 큰 컴퓨터 작업을 사용자 검토를 위해 일시 중지해야 할 때는 needsApproval을 사용하고, 컴퓨터 호출에 대해 보고된 대기 중 안전 검사를 확인하거나 거부하려면 onSafetyCheck를 사용하세요. 모델 측 지침과 마이그레이션 세부 사항은 공식 OpenAI 컴퓨터 사용 가이드와 해당 가이드의 마이그레이션 참고 사항을 참고하세요.

Responses API는 애플리케이션에서 검토할 우려 사항을 알리기 위해 computer_call에 pending_safety_checks를 포함할 수 있습니다. 각 검사에는 id와 선택적 code, message 필드가 있으며, 우려 사항의 유형과 세부 정보를 제공합니다. 이 검사는 API에서 제공됩니다. pending_safety_checks와 acknowledged_safety_checks는 Responses API 레퍼런스를, 애플리케이션 수준의 예방 조치는 컴퓨터 사용 안전 지침을 참고하세요.

문제가 표시된 컴퓨터 호출을 계속 진행할지 결정하려면 computerTool({ onSafetyCheck })를 설정하세요. JavaScript SDK는 id와 code 값이 모두 비어 있지 않은 검사를 이 콜백에 전달하며, 둘 중 하나라도 없는 검사는 무시합니다. SDK는 이러한 요구 사항을 충족하는 검사가 하나 이상 있을 때만 호출의 작업을 실행하기 전에 콜백을 호출합니다.

콜백은 { runContext, pendingSafetyChecks, toolCall }을 받고 pendingSafetyChecks로 전달된 검사를 처리합니다.

  • true를 반환하면 콜백에 전달된 모든 검사를 확인 처리하고 실행을 허용합니다.
  • false를 반환하면 작업이나 스크린샷 캡처가 실행되기 전에 호출을 거부합니다. SDK는 거부 결과를 반환하고 에이전트 실행을 계속합니다.
  • acknowledgedSafetyChecks(또는 acknowledged_safety_checks)를 포함하는 객체를 반환하면 제공된 검사를 확인 처리하고 실행을 허용합니다. 일부만 포함하거나 비어 있는 목록을 반환해도 호출이 거부되지는 않습니다.
  • undefined를 반환하거나 값을 반환하지 않으면 확인 처리 없이 실행을 허용합니다.

onSafetyCheck를 생략하면 SDK는 실행을 계속하고 검사를 확인 처리하지 않은 상태로 둡니다. SDK는 자동으로 사람에게 확인을 요청하지 않습니다. 애플리케이션에서 SDK가 전달하는 검사를 검토해야 한다면 콜백을 명시적으로 설정하세요. 예를 들어, 다음의 보수적인 정책은 콜백에 전달된 모든 호출을 거부합니다.

문제가 표시된 컴퓨터 호출 거부
import { computerTool, type Computer, type ComputerTool } from '@openai/agents';
export function computerToolWithSafetyChecks(computer: Computer): ComputerTool {
return computerTool({
computer,
// Reject every flagged call until the application implements a review flow.
onSafetyCheck: async () => false,
});
}

검토한 호출을 허용하려면 예제 콜백을 애플리케이션의 검토자에게 pendingSafetyChecks와 제안된 toolCall을 제시하고, 결정을 기다린 뒤 그 결정을 반환하는 콜백으로 교체하세요. 알 수 없는 검사 코드도 검토가 필요한 것으로 취급하세요.

대기 중인 검사가 없는 컴퓨터 호출은 이 콜백을 호출하지 않습니다. 사람의 결정을 받으려면 콜백에서 해당 상호작용을 마련하고 결정을 반환해야 합니다. onSafetyCheck는 휴먼 인 더 루프 (HITL)에 설명된 일시 중지 및 재개 흐름을 사용하지 않습니다. onSafetyCheck를 호출하지 않는 경우를 포함하여 애플리케이션에서 컴퓨터 작업에 이 승인 흐름이 필요하다면 needsApproval을 사용하세요.

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

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

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

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

  • type: 'container_auto'로 실행에 사용할 관리형 컨테이너를 생성합니다.
  • type: 'container_reference'로 containerId를 사용해 기존 컨테이너를 재사용합니다.

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

  • domainSecrets가 포함된 허용 목록 등을 지원하는 networkPolicy
  • 업로드된 파일을 마운트하기 위한 fileIds
  • 컨테이너 크기 설정을 위한 memoryLimit
  • skill_reference 또는 인라인 zip 번들로 제공하는 skills

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

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

applyPatchTool()은 shellTool()과 동일한 로컬 승인 흐름을 따릅니다. 파일 편집 전에 일시 중지하려면 needsApproval을 사용하고, 애플리케이션 수준의 콜백으로 자동 승인하거나 거부하려면 onApproval을 사용하세요.


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

Zod 매개변수를 사용하는 함수 도구
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 스키마, 지원되는 Standard Schema 값 또는 원문 JSON Schema 객체입니다. 검증 스키마는 자동으로 strict 모드를 활성화합니다.
strict아니요true(기본값)인 경우 인수가 검증을 통과하지 못하면 SDK가 모델에 오류를 반환합니다. 유연한 매칭을 사용하려면 false로 설정하세요.
execute예(args, context, details) => string | unknown | Promise<...> – 비즈니스 로직입니다. 문자열이 아닌 출력은 모델을 위해 직렬화됩니다. context는 선택적 RunContext이며, details에는 toolCall, resumeState, signal 같은 메타데이터가 포함됩니다.
allowedCallers아니요도구를 직접 호출할 수 있는지, 프로그래밍 방식으로 호출할 수 있는지, 또는 두 방식 모두 가능한지 제어하는 비어 있지 않은 목록이며 Responses 전용입니다. 'direct', 'programmatic' 또는 두 값을 모두 사용하세요.
outputSchema아니요도구 결과에 대한 Responses 전용 스키마입니다. Zod 스키마는 execute 반환 타입을 제한하고 런타임 결과를 검증/변환합니다. 원문 JSON 스키마는 통신 규약만 기술합니다.
errorFunction아니요내부 오류를 모델에 표시되는 결과로 변환하는 사용자 정의 핸들러 (context, error, details) => result입니다. outputSchema가 설정된 경우 결과는 해당 스키마를 충족해야 합니다. 기본 핸들러는 비활성화되므로 원래 오류가 다시 발생합니다.
timeoutMs아니요호출별 타임아웃(밀리초)입니다. 0보다 크고 2147483647 이하여야 합니다.
timeoutBehavior아니요타임아웃 모드입니다. error_as_result는 모델에 표시되는 결과를 반환하고, raise_exception은 ToolTimeoutError를 발생시킵니다. 기본값은 outputSchema가 없으면 error_as_result, 있으면 raise_exception입니다.
timeoutErrorFunction아니요error_as_result를 위한 사용자 정의 핸들러 (context, timeoutError, details) => result입니다. outputSchema가 설정된 경우 이 핸들러가 필수이며, 결과는 해당 스키마를 충족해야 합니다.
customDataExtractor아니요생성된 RunToolCallOutputItem.customData에 SDK 전용 메타데이터를 첨부하는 콜백 (context) => Record<string, unknown> | null | undefined입니다. 이 데이터는 모델에 다시 전송되지 않습니다.
needsApproval아니요실행 전에 사람의 승인을 요구합니다. 휴먼 인 더 루프 (HITL)를 참고하세요.
isEnabled아니요실행별로 조건에 따라 도구를 노출합니다. 불리언 또는 조건 함수를 받습니다.
inputGuardrails아니요도구 실행 전에 동작하는 가드레일입니다. 거부하거나 예외를 발생시킬 수 있습니다. 가드레일을 참고하세요.
outputGuardrails아니요도구 실행 후에 동작하는 가드레일입니다. 거부하거나 예외를 발생시킬 수 있습니다. 가드레일을 참고하세요.

요청 범위의 기능 노출, 환경별 가용성, 기능 플래그 또는 실험에는 isEnabled를 사용하세요. 러너는 현재 턴에서 모델에 노출할 도구 집합을 준비하면서 조건 함수를 평가합니다.

isEnabled는 도구 인수나 접근 대상 리소스에 따라 달라지는 권한 부여를 대체하지 않습니다. 조건 함수는 모델이 해당 인수를 생성하기 전에 실행되기 때문입니다. 인수 및 리소스 수준의 권한 부여는 execute 내부에서 적용하거나, 적절한 경우 도구 입력 가드레일과 휴먼 인 더 루프 (HITL)를 통한 승인을 추가하세요. MCP 서버는 자체적으로 보호된 작업에 대한 권한을 부여해야 합니다. 하나의 애플리케이션 정책을 함수 도구, 로컬 MCP 도구, 핸드오프에 걸쳐 적용하는 패턴은 컨텍스트 관리를 참고하세요.

지원되는 Standard Schema 매개변수는 모델을 위해 JSON Schema로 변환되며, execute가 실행되기 전에 로컬에서 검증됩니다. 라이브러리 변환과 기본값을 포함한 검증 출력 타입이 execute 인수의 추론된 타입이 됩니다. Valibot 예제와 현재 제한 사항은 스키마 검증을 참고하세요.

애플리케이션에서 도구 결과와 함께 렌더러 힌트, 내부 ID 또는 기타 JSON 호환 메타데이터가 필요할 때 customDataExtractor를 사용하세요. 콜백은 실행 컨텍스트, 도구 정의, 모델 도구 호출, 파싱된 입력, 출력, 복제된 원문 출력 항목을 받습니다. 반환된 데이터는 RunToolCallOutputItem.customData와 RunState에 저장되지만, history와 모델 재생에서는 제외됩니다.

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

  • timeoutBehavior: 'error_as_result'는 모델에 Tool '<name>' timed out after <timeoutMs>ms.를 반환합니다. outputSchema가 설정되지 않은 경우의 기본값입니다.
  • timeoutBehavior: 'raise_exception'은 ToolTimeoutError를 발생시키며, 에이전트 실행의 예외 처리 과정에서 이를 잡을 수 있습니다.
  • timeoutErrorFunction을 사용하면 error_as_result 모드에서 타임아웃 텍스트를 사용자 정의할 수 있습니다.
  • outputSchema가 설정되면 기본값이 raise_exception으로 바뀝니다. error_as_result를 사용하려면 스키마와 호환되는 값을 반환하는 timeoutErrorFunction이 필요합니다.
  • 타임아웃은 details.signal을 중단하므로, 오래 실행되는 도구가 취소 신호를 수신하면 즉시 중지할 수 있습니다.

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

모델이 유효하지 않거나 불완전한 입력을 추측하도록 해야 한다면, 원문 JSON 스키마를 사용할 때 strict 모드를 비활성화할 수 있습니다.

비엄격 JSON 스키마 도구
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에서는 이 방식으로 지연 로딩되는 최상위 함수 도구, 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은 검색 가능한 독립 기능 하나이므로 최상위 수준에 둡니다.
  • crmTools는 관련 CRM 도구가 하나의 상위 레이블과 설명을 공유하므로 toolNamespace()를 사용합니다.
  • 같은 요청에서 네임스페이스에 속한 도구와 최상위 지연 로딩 도구를 함께 사용할 수 있습니다. 도구 검색은 crm 같은 네임스페이스 경로와 get_shipping_eta 같은 최상위 경로를 모두 로드할 수 있습니다.

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

  • 각 지연 로딩 함수 도구에 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 루프가 필요합니다.
  • 하나의 네임스페이스에 즉시 사용 가능한 멤버와 지연 로딩 멤버를 함께 둘 수 있습니다. 즉시 사용 가능한 멤버는 도구 검색 없이 호출할 수 있고, 같은 네임스페이스의 지연 로딩 멤버는 필요할 때 로드됩니다.
  • 도구 검색 결과는 검색을 수행한 에이전트에 속하며 핸드오프를 통해 이전되지 않습니다. 해당 에이전트의 이름이 실행 그래프에서 고유하면, SDK는 기록 또는 세션 재생 시 논리적으로 동일한 에이전트의 검색 결과를 유지합니다. 소유 주체가 없거나 모호하면 다시 검색해야 하므로, 재구성 후에도 저장된 검색 결과를 유지해야 한다면 에이전트에 고유한 이름을 지정하세요.
  • 지연 로딩 함수 도구와 toolNamespace()는 Responses 전용입니다. Chat Completions는 이를 거부하며, AI SDK 어댑터는 Responses의 지연 도구 로딩 흐름을 지원하지 않습니다.

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

아직 agent.asTool()과 handoff() 중 무엇을 사용할지 결정하는 중이라면 에이전트와 에이전트 오케스트레이션에서 패턴을 비교해 보세요.

Agents as tools
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를 생성하고, 해당 러너를 사용하여 함수 도구 호출 내에서 에이전트를 실행합니다. 중첩된 러너를 설정하려면 runConfig를, 중첩된 실행을 설정하려면 runOptions를 전달하세요.

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

customOutputExtractor 내부에서는 result.agentToolInvocation을 사용하여 현재 Agent.asTool() 호출을 검사하세요. 이 콜백의 결과는 항상 Agent.asTool()에서 오므로, agentToolInvocation은 항상 정의되어 있으며 toolName, toolCallId, toolArguments를 노출합니다. 애플리케이션 컨텍스트에는 result.runContext.context를 사용하세요. 기본 단일 input 스키마를 사용하면 result.runContext.toolInput은 undefined입니다. 대신 result.agentToolInvocation.toolArguments를 사용하여 호출 인수를 읽으세요. 사용자 정의 parameters 또는 inputBuilder를 설정하면 result.runContext.toolInput에 캡처된 구조화 인수가 포함됩니다. agentToolInvocation 메타데이터는 현재 중첩 호출 범위에 한정되며 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()의 고급 구조화 입력 옵션은 다음과 같습니다.

  • parameters: 기본 { input: string } 형식을 Zod 스키마, 지원되는 Standard Schema 값 또는 원문 JSON Schema로 대체합니다.
  • 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은 가장 간단한 “전체 수신” 방식이며, 도구를 인라인으로 선언할 때(tools: [agent.asTool({ onStream })]) 잘 작동합니다. 이벤트별 라우팅이 필요하지 않다면 사용하세요.
  • on(eventName, handler)를 사용하면 선택적으로(또는 '*'로) 구독할 수 있으며, 더 세밀한 처리가 필요하거나 생성 후 리스너를 연결하려는 경우에 가장 적합합니다.
  • onStream 또는 on(...) 핸들러를 하나라도 제공하면 도구로 사용되는 에이전트가 자동으로 스트리밍 모드에서 실행됩니다. 없으면 비스트리밍 경로를 유지합니다.
  • 핸들러는 병렬로 호출되므로 느린 onStream 콜백이 on(...) 핸들러를 차단하지 않으며, 그 반대도 마찬가지입니다.
  • 모델 도구 호출을 통해 도구가 호출되면 toolCallId가 제공됩니다. 직접 invoke()를 호출하거나 제공자별 특성이 있는 경우에는 생략될 수 있습니다.

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

로컬 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)의 수명 주기 지침을 사용하세요.


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

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

터미널 창
npm install @openai/agents-extensions @openai/codex-sdk

빠른 시작:

실험적 Codex 도구
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를 전달하세요.
  • 입력: 엄격한 스키마를 사용합니다. inputs에는 { type: 'text', text } 또는 { type: 'local_image', path }가 하나 이상 포함되어야 합니다.
  • 안전: sandboxMode를 workingDirectory와 함께 사용하세요. 디렉터리가 Git 저장소가 아니라면 skipGitRepoCheck를 설정하세요.
  • 스레드 처리: useRunContextThreadId: true는 runContext.context에서 최신 스레드 ID를 읽고 저장하므로, 앱 상태에서 여러 턴에 걸쳐 재사용할 때 유용합니다.
  • 스레드 ID 우선순위: 도구 호출의 threadId(스키마에 포함된 경우)가 가장 우선하며, 그다음 실행 컨텍스트의 스레드 ID, 마지막으로 codexTool({ threadId })가 적용됩니다.
  • 실행 컨텍스트 키: 기본값은 name: 'codex'의 경우 codexThreadId이며, name: 'engineer' 같은 이름의 경우 codexThreadId_<suffix>입니다(정규화 후 codex_engineer).
  • 변경 가능한 컨텍스트 요구 사항: useRunContextThreadId가 활성화된 경우 run(..., { context })에 변경 가능한 객체 또는 Map을 전달하세요.
  • 이름 지정: 도구 이름은 codex 네임스페이스로 정규화되며(engineer는 codex_engineer가 됨), 에이전트 내에서 중복된 Codex 도구 이름은 거부됩니다.
  • 스트리밍: onStream은 Codex 이벤트(추론, 명령 실행, MCP 도구 호출, 파일 변경, 웹 검색)를 그대로 전달하므로 진행 상황을 로깅하거나 트레이싱할 수 있습니다.
  • 출력: 도구 결과에는 response, usage, threadId가 포함되며, Codex 토큰 사용량은 RunContext에 기록됩니다.
  • 구조: outputSchema는 디스크립터, JSON 스키마 객체 또는 Zod 객체일 수 있습니다. JSON 객체 스키마의 경우 additionalProperties는 false여야 합니다.

실행 컨텍스트 스레드 재사용 예제:

Codex 실행 컨텍스트 스레드 재사용
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;

프로그래밍 방식 도구 호출을 사용하면 이를 지원하는 Responses 모델이 호스티드 실행 환경 내에서 여러 도구 호출을 조율하는 JavaScript를 생성할 수 있습니다. 클라이언트 소유 도구는 여전히 애플리케이션에서 실행하므로 기존 검증, 권한, 승인, 가드레일 및 부수 효과가 계속 적용됩니다.

프로그래밍 방식 도구 호출
import { Agent, programmaticToolCallingTool, tool } from '@openai/agents';
import { z } from 'zod';
const getInventory = tool({
name: 'get_inventory',
description: 'Return inventory for a SKU.',
parameters: z.object({ sku: z.string() }),
allowedCallers: ['programmatic'],
outputSchema: z.object({
sku: z.string(),
availableUnits: z.number(),
}),
async execute({ sku }) {
return { sku, availableUnits: 42 };
},
});
const getDemand = tool({
name: 'get_demand',
description: 'Return requested units for a SKU.',
parameters: z.object({ sku: z.string() }),
allowedCallers: ['programmatic'],
outputSchema: z.object({
sku: z.string(),
requestedUnits: z.number(),
}),
async execute({ sku }) {
return { sku, requestedUnits: 31 };
},
});
const agent = new Agent({
name: 'Inventory planner',
model: 'gpt-5.6',
instructions: `
Use Programmatic Tool Calling to fetch inventory and demand concurrently.
Return the source values and the calculated shortage in the final answer.
`.trim(),
tools: [getInventory, getDemand, programmaticToolCallingTool()],
});

설정은 두 부분으로 이루어집니다.

  1. 에이전트에 programmaticToolCallingTool()을 추가합니다.
  2. 생성된 프로그램이 호출할 수 있는 각 도구에 allowedCallers를 설정합니다.
allowedCallers동작
생략 또는 ['direct']모델이 도구를 직접 호출할 수 있습니다.
['programmatic']생성된 프로그램만 도구를 호출할 수 있습니다.
['direct', 'programmatic']모델 또는 생성된 프로그램이 도구를 호출할 수 있습니다.

SDK는 tool(), 로컬 또는 호스티드 shellTool(), applyPatchTool(), hostedMcpTool(), codeInterpreterTool()로 생성한 도구에 대해 프로그래밍 방식 호출자를 지원합니다.

SDK는 요청을 전송하기 전에 설정을 검증합니다. 프로그래밍 방식으로만 호출할 수 있는 도구에는 programmaticToolCallingTool()이 필요합니다. 이 헬퍼 역시 사용 가능한 도구를 하나 이상 필요로 합니다. 단, 요청에 해당 도구를 제공할 수 있는 도구 검색 또는 저장된 프롬프트가 포함된 경우는 예외입니다.

함수 도구가 구조화된 데이터를 반환해야 할 때는 outputSchema를 사용하세요. Zod 스키마는 execute 반환 타입을 제한하고 런타임 결과를 검증 및 변환합니다. 원문 JSON 스키마는 통신 규약을 기술하지만 SDK 측 결과 검증을 추가하지는 않습니다. Zod 결과가 유효하지 않으면 InvalidToolOutputError가 발생합니다.

Structured outputs는 실패 처리도 변경합니다.

  • 기본 errorFunction이 비활성화되므로 실행 오류가 다시 발생합니다. 사용자 정의 핸들러는 outputSchema와 호환되는 값을 반환해야 합니다.
  • 기본 타임아웃 동작이 'raise_exception'으로 바뀝니다.
  • 'error_as_result'를 사용하려면 반환값이 outputSchema를 충족하는 timeoutErrorFunction을 제공하세요.
  • 출력 가드레일로 대체된 값도 outputSchema를 충족해야 합니다.

프로그래밍 방식 도구 호출은 Responses 전용입니다. Chat Completions, 음성 에이전트 및 AI SDK 모델 어댑터는 이 옵션들을 거부합니다. 사용 가능한 도구가 지연 로딩되는 경우, 나중에 생성된 프로그램에서 호출할 수 있으려면 도구 검색이 먼저 해당 도구를 로드해야 합니다.

전체 예제는 examples/tools/programmatic-tool-calling.ts를 참고하세요.


모델이 도구를 사용해야 하는 시점과 방식을 제어하려면(modelSettings.toolChoice, toolUseBehavior 등) 에이전트를 참고하세요.


  • 짧고 명확한 설명 – 도구가 무엇을 하는지와 언제 사용해야 하는지 설명하세요.
  • 입력 검증 – 가능하면 Zod 또는 지원되는 Standard Schema 값을 사용하여 엄격한 JSON 검증을 수행하세요.
  • 오류 핸들러의 부수 효과 방지 – errorFunction은 예외를 발생시키지 말고 유용한 문자열을 반환해야 합니다.
  • 도구별 단일 책임 – 작고 조합 가능한 도구를 사용하면 모델의 추론이 향상됩니다.

  • 도구를 갖춘 에이전트를 정의하고 toolUseBehavior를 제어하는 방법은 에이전트를 참고하세요.
  • 에이전트를 도구로 사용할지 핸드오프를 사용할지 결정하려면 에이전트 오케스트레이션을 참고하세요.
  • 실행 흐름, 스트리밍, 대화 상태는 에이전트 실행을 참고하세요.
  • 호스티드 OpenAI 모델 설정 및 Responses 전송 방식 선택은 모델을 참고하세요.
  • 도구 입력이나 출력을 검증하려면 가드레일을 참고하세요.
  • tool()과 다양한 호스티드 툴 유형에 대한 TypeDoc 레퍼런스를 자세히 살펴보세요.