도구 호출 (Tool Calls)

도구 호출(Tool Calls)은 모델이 외부 도구를 호출해 능력을 확장하는 기능이에요. 예를 들어 사용자의 위치에 따른 현재 날씨를 모델이 직접 가져오도록 만들 수 있어요. 모델이 함수를 실제로 실행하는 게 아니라, 호출할 함수와 인자를 JSON으로 생성해서 돌려주는 방식이에요.

출처: https://api-docs.deepseek.com/guides/tool_calls

일반 모드 (Non-thinking)

Tools 파라미터를 정의하고 대화에 섞으면, 모델이 적절한 시점에 함수 호출을 생성해요. 흐름은 이렇게 네 단계로 진행돼요.

사용자가 현재 날씨를 물어봐요.
모델이 get_weather({location: 'Hangzhou'}) 함수 호출을 돌려줘요.
사용자(코드)가 그 함수를 실행하고 결과를 모델에 넘겨줘요.
모델이 자연어로 "현재 항저우 기온은 24℃입니다" 같은 최종 답을 내놓아요.

from openai import OpenAI

def send_messages(messages):
    response = client.chat.completions.create(
        model="deepseek-v4-pro",
        messages=messages,
        tools=tools,
    )
    return response.choices[0].message

client = OpenAI(
    api_key="<your api key>",
    base_url="https://api.deepseek.com",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather of a location, the user should supply a location first.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                },
                "required": ["location"],
            },
        },
    },
]

messages = [{"role": "user", "content": "How's the weather in Hangzhou, Zhejiang?"}]
message = send_messages(messages)
print(f"User>\t{messages[0]['content']}")

tool = message.tool_calls[0]
messages.append(message)

messages.append({"role": "tool", "tool_call_id": tool.id, "content": "24℃"})
message = send_messages(messages)
print(f"Model>\t{message.content}")

여기서 get_weather 함수의 실제 기능은 사용자가 제공해야 해요. 모델이 함수를 직접 실행하는 게 아니라요.

Thinking 모드에서의 도구 호출

DeepSeek-V3.2부터는 thinking 모드에서도 도구 사용을 지원해요. 상세한 내용은 Thinking 모드 문서를 참고하세요.

strict 모드 (Beta)

strict 모드에서는 모델이 도구 호출을 출력할 때 함수의 JSON Schema 형식 요구 사항을 엄격히 지켜요. 그래서 모델 출력이 사용자가 정의한 형식을 항상 따르게 돼요. thinking 모드와 일반 모드 모두에서 지원돼요. strict 모드를 쓰려면 세 가지를 준비해야 해요.

base_url="https://api.deepseek.com/beta"로 Beta 기능을 켜요.
tools 파라미터의 모든 function에 strict 속성을 true로 설정해요.
서버가 사용자가 제공한 함수의 JSON Schema를 검증해요. 스키마가 규격을 안 지키거나 서버가 지원하지 않는 JSON Schema 타입이 있으면 오류 메시지를 돌려줘요.

{
    "type": "function",
    "function": {
        "name": "get_weather",
        "strict": true,
        "description": "Get weather of a location, the user should supply a location first.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
            },
            "required": ["location"],
            "additionalProperties": false,
        },
    },
}

strict 모드에서 지원하는 JSON Schema 타입

object, string, number, integer, boolean, array, enum, anyOf가 지원돼요.

object — 키-값 쌍으로 이뤄진 중첩 구조를 정의해요. properties가 각 키(속성)의 스키마를 지정해요. 모든 object의 모든 속성은 required로 설정해야 하고, additionalProperties는 false로 설정해야 해요. 예를 들어 이름과 나이를 받는 객체라면 이렇게 쓰면 돼요.

{
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "age": { "type": "integer" },
    },
    "required": ["name", "age"],
    "additionalProperties": false,
}

string — 지원 파라미터로는 정규식으로 형식을 제한하는 pattern, 미리 정의된 공통 형식을 검증하는 format이 있어요. format은 현재 email, hostname, ipv4, ipv6, uuid를 지원해요.

$ref와 $def도 사용할 수 있어요. 예를 들어 저자 정보를 재사용하려면 스키마에서 정의해 두고 참조하는 식이에요.

더 알아보기

도구 호출의 구체적인 API 포맷은 «채팅 완성 API» 문서를 봐요.
thinking 모드에서 도구 호출이 이어지는 흐름은 «Thinking 모드» 문서를 봐요.
모델이 구조화된 JSON을 내도록 하는 법은 «JSON 출력» 문서를 봐요.