문서 · 모델 기능

도구 호출

Tool calling (function calling) lets the model return structured calls to functions you define. Your code runs them and hands the results back so the model can answer. Works with models that have the Tool calling capability.

본문은 현재 영어로만 제공됩니다.

The full loop

1Describe your functions in tools with JSON Schema.
2The model returns tool_calls (finish_reason is tool_calls).
3Your code runs each function and appends the result as a role: "tool" message with the matching tool_call_id.
4Call the API again; the model answers using the tool results.

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string", "description": "City name, e.g. Tokyo"}},
            "required": ["city"],
        },
    },
}]
messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]

resp = client.chat.completions.create(model="gpt-4.1-mini", messages=messages, tools=tools)
msg = resp.choices[0].message
if msg.tool_calls:
    messages.append(msg)                              # 1. keep the assistant's tool_calls
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)    # 2. run the tool in your code
        result = {"city": args["city"], "temp_c": 22, "sky": "clear"}
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    final = client.chat.completions.create(model="gpt-4.1-mini", messages=messages, tools=tools)
    print(final.choices[0].message.content)           # 3. the model answers using the result

Controlling tool use

tool_choice	Behavior
`"auto"` (default)	The model decides
`"none"`	Never call tools
`"required"`	Call at least one tool
`{"type": "function", "function": {"name": "..."}}`	Force a specific function

Some newer models do not support forced tool use (required or a named function) and return a 400. Use auto and say in the prompt when each tool should be used.

Parallel calls

The model may return several tool_calls at once. Run them all, then send one tool message per result (matched by tool_call_id) in the same request.

Anthropic format

In the native format, tools are described with input_schema, and calls round-trip as tool_use / tool_result content blocks:

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[{
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }],
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
)
# When stop_reason == "tool_use", content holds tool_use blocks; run them and reply with:
# {"role": "user", "content": [{"type": "tool_result", "tool_use_id": block.id, "content": "..."}]}

Tips

Write clear names and descriptions — what the tool does and when to use it. That is what the model chooses by.
Keep schemas strict: use enum and required, avoid vague free-text fields.
Validate arguments before running a tool. Always parse them as JSON, never by string matching.
Return compact tool results with only the fields the model needs; it saves input tokens.

모델 목록과 선택

JSON 출력