도구

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

호스티드 툴 – OpenAI 서버에서 모델과 함께 실행됩니다. (웹 검색, 파일 검색, 컴퓨터 사용, Code Interpreter, 이미지 생성)
함수 도구 – 로컬 함수를 JSON 스키마로 감싸 LLM이 호출할 수 있게 합니다.
에이전트를 도구로 – 전체 에이전트를 호출 가능한 도구로 노출합니다.
로컬 MCP 서버 – 로컬에서 실행되는 Model context protocol 서버를 연결합니다.

1. 호스티드 툴

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

Tool	Type string	Purpose
Web search	`'web_search'`	인터넷 검색
File / retrieval search	`'file_search'`	OpenAI에서 호스팅되는 벡터 스토어 쿼리
Computer use	`'computer'`	GUI 상호작용 자동화
Shell	`'shell'`	호스트에서 셸 명령 실행
Apply patch	`'apply_patch'`	로컬 파일에 V4A diff 적용
Code Interpreter	`'code_interpreter'`	샌드박스 환경에서 코드 실행
Image generation	`'image_generation'`	텍스트 기반 이미지 생성

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

const agent = new Agent({
  name: 'Travel assistant',
  tools: [webSearchTool(), fileSearchTool('VS_ID')],
});

정확한 매개변수 세트는 OpenAI Responses API와 일치합니다. rankingOptions나 의미론적 필터와 같은 고급 옵션은 공식 문서를 참고하세요.

2. 함수 도구

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`	No	기본값은 함수 이름입니다(예: `get_weather`)
`description`	Yes	LLM에 표시되는 명확하고 사람이 읽기 쉬운 설명
`parameters`	Yes	Zod 스키마 또는 원문 JSON 스키마 객체 중 하나. Zod parameters를 사용하면 자동으로 strict 모드가 활성화됩니다
`strict`	No	`true`(기본값)일 때, 인수가 검증에 실패하면 SDK가 모델 오류를 반환합니다. 퍼지 매칭이 필요하면 `false`로 설정하세요
`execute`	Yes	`(args, context) => string \| Promise<string>`– 비즈니스 로직. 두 번째 선택적 매개변수는 `RunContext`입니다
`errorFunction`	No	내부 오류를 사용자에게 보이는 문자열로 변환하는 커스텀 핸들러 `(context, error) => string`

비‑strict JSON‑스키마 도구

유효하지 않거나 일부만 제공된 입력을 모델이 추론하도록 하려면 원문 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;
  },
});

3. 에이전트를 도구로

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

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 동작을 커스터마이즈할 수 있습니다.

4. MCP 서버

Model Context Protocol (MCP) 서버를 통해 도구를 노출하고 에이전트에 연결할 수 있습니다. 예를 들어 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 guide를 참조하세요.

도구 사용 동작

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

모범 사례

짧고 명확한 설명 – 도구가 무엇을 하는지 그리고 언제 사용하는지를 설명하세요.
입력 검증 – 가능하면 Zod 스키마로 엄격한 JSON 검증을 수행하세요.
에러 핸들러에서 부작용 회피 – errorFunction은 유용한 문자열을 반환해야 하며, 예외를 던지지 마세요.
도구당 하나의 책임 – 작고 컴포저블한 도구가 더 나은 모델 추론으로 이어집니다.

다음 단계

도구 사용 강제에 대해 알아보세요.
도구 입력 또는 출력을 검증하기 위해 가드레일을 추가하세요.
tool() 및 다양한 호스티드 툴 타입에 대한 TypeDoc 레퍼런스를 살펴보세요.