도구 사용하기

도구 사용하기 (Using tools)

모델 응답을 생성하거나 에이전트를 만들 때, 내장 도구·함수 호출·Programmatic Tool Calling·tool search·원격 MCP 서버로 기능을 확장할 수 있어요. 이 도구들로 모델이 웹을 검색하고, 파일에서 검색하고, 런타임에 지연된 도구 정의를 로드하고, 자신의 함수를 호출하고, JavaScript로 도구 호출을 구성하고, 서드파티 서비스에 접근할 수 있게 해요. tool_search는 gpt-5.4 이후 모델만 지원해요.

출처: 문서

본문

러닝타임에 맞는 통합을 선택하세요. Responses API 요청의 도구를 구성하거나, Agents API 에이전트에 구성하거나, Agents SDK 정의에 구성해요. 도구 가용성·구성·호출 처리는 통합에 따라 달라요. 아래 예시는 Responses API를 사용해요.

웹 검색

모델 응답에 웹 검색 결과를 포함하려면 tools에 web_search 도구를 지정해요.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    tools=[{"type": "web_search"}],
    input="What was a positive news story from today?",
)

print(response.output_text)

파일 검색

응답에서 파일을 검색하려면 file_search 도구와 vector_store_ids를 지정해요.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="What is deep research by OpenAI?",
    tools=[{"type": "file_search", "vector_store_ids": ["<vector_store_id>"]}],
)
print(response)

사용 가능한 도구

OpenAI 플랫폼에서 사용할 수 있는 도구의 개요예요.

함수 호출 — 커스텀 코드를 호출해 모델에 추가 데이터·기능을 제공.
웹 검색 — 모델 응답 생성에 인터넷 데이터 포함.
원격 MCP 서버 — Model Context Protocol(MCP) 서버로 모델에 새 기능 제공.
Skills — 호스팅 셸 환경에서 버전 관리된 스킬 번들을 업로드·재사용.
Shell — 호스팅 컨테이너나 자체 로컬 런타임에서 셸 명령 실행.
Computer use — 모델이 컴퓨터 인터페이스를 제어하게 하는 에이전트 워크플로 생성.
이미지 생성 — GPT Image로 이미지 생성·편집.
파일 검색 — 응답 생성 시 컨텍스트용으로 업로드된 파일 내용 검색.
Tool search — 관련 도구를 모델 컨텍스트에 동적으로 로드해 토큰 사용 최적화.
Programmatic Tool Calling — 모델이 도구 호출을 오케스트레이션하는 JavaScript를 구성·실행.

API에서 사용하기

모델 응답을 생성하라는 요청을 할 때 보통 tools 파라미터에 구성을 지정해 도구 접근을 활성화해요. 각 도구는 고유한 구성 요구사항이 있어요. 자세한 지시는 사용 가능한 도구 섹션을 참고하세요.

제공된 프롬프트를 바탕으로 모델이 구성된 도구를 쓸지 자동으로 결정해요. 예를 들어 프롬프트가 모델 훈련 데이터 이후의 정보를 요청하고 웹 검색이 활성화되어 있으면, 모델이 보통 웹 검색 도구를 호출해 관련·최신 정보를 가져와요. 일부 고급 워크플로는 상호작용 중에 더 많은 도구 정의를 로드할 수도 있어요. 예를 들어 tool search는 모델이 필요하다고 판단할 때까지 함수 정의를 지연할 수 있어요. API 요청에서 tool_choice 파라미터를 설정해 이 동작을 명시적으로 제어·안내할 수 있어요.

Agents API

Agents API는 에이전트 루프를 대신 실행해 줘요. agent.tools에 도구를 구성하고, 앱에서 함수 호출을 처리하며, 도구가 실행 환경을 필요로 하면 샌드박스를 연결해요. 함수로 앱 코드를, MCP 연결로 도구 서버를 호출하고, 실행 환경이 필요한 도구는 샌드박스 구성을 참고하세요. Programmatic Tool Calling이 기본으로 활성화돼 있어요. Skills은 샌드박스의 기능 디렉터리를 통해 발견돼요.

Agents SDK에서 사용하기

Agents SDK에서는 도구 의미론은 같지만, 배선이 단일 Responses API 요청이 아니라 에이전트 정의와 워크플로 설계로 옮겨져요.

하나의 전문가가 스스로 호출해야 하는 도구는 호스팅 도구·함수 도구·호스팅 MCP 도구를 에이전트에 직접 붙이세요.
매니저가 사용자 대면 응답을 계속 제어해야 할 때는 전문가를 도구로 노출하세요.
SDK가 도구 결정을 모델링해도 shell·apply patch·computer-use 하네스는 러닝타임에 유지하세요.

로컬 로직을 함수 도구로 감싸고:

from agents import function_tool


@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    return f"The weather in {city} is sunny."

전문가를 도구로 노출하고:

from agents import Agent

summarizer = Agent(
    name="Summarizer",
    instructions="Generate a concise summary of the supplied text.",
)

main_agent = Agent(
    name="Research assistant",
    tools=[
        summarizer.as_tool(
            tool_name="summarize_text",
            tool_description="Generate a concise summary of the supplied text.",
        )
    ],
)

단일 전문가를 설계할 때는 Agent 정의를, 도구가 소유권에 영향을 주면 Orchestration and handoffs를, 도구가 승인에 영향을 주면 Guardrails and human review를, 기능이 MCP에서 오면 Integrations and observability를 참고하세요.

도구 사용하기