Tool calling

Let a model call your functions, and feed the results back into the conversation.

Tool calling uses the OpenAI shape: you send tools, the model answers with tool_calls, you run them and send the results back as tool messages.

Whether a given model calls tools well is the provider’s business, not warpllm’s. warpllm forwards tools and tool_choice and returns whatever comes back. Check the provider’s own docs before assuming a model supports them.

The exchange

1. Send tool definitions with the request

   {
     "model": "openai/gpt-5-nano",
     "messages": [{ "role": "user", "content": "What's the weather in Oslo?" }],
     "tools": [
       {
         "type": "function",
         "function": {
           "name": "get_weather",
           "description": "Current weather for a city.",
           "parameters": {
             "type": "object",
             "properties": { "city": { "type": "string" } },
             "required": ["city"]
           },
           "strict": true
         }
       }
     ]
   }
   
2. The model answers with tool_calls

   finish_reason is tool_calls, and message.content is null.

   {
     "choices": [
       {
         "finish_reason": "tool_calls",
         "message": {
           "role": "assistant",
           "content": null,
           "tool_calls": [
             {
               "id": "call_abc",
               "type": "function",
               "function": {
                 "name": "get_weather",
                 "arguments": "{\"city\":\"Oslo\"}"
               }
             }
           ]
         }
       }
     ]
   }
   

   arguments is a JSON string, not an object. Parse it, and treat a parse failure as a normal outcome — models emit malformed JSON.

3. Append the assistant turn and one tool message per call

   Each tool message carries the tool_call_id it answers.

   { "role": "tool", "tool_call_id": "call_abc", "content": "{\"tempC\": 4}" }
   
4. Call again with the extended message list

   The model now has the results and produces its final answer. Loop until finish_reason is no longer tool_calls.

A complete loop

Python

import json

from warpllm import WarpLLM

client = WarpLLM()

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }
]

IMPLEMENTATIONS = {"get_weather": lambda city: {"tempC": 4, "city": city}}

messages = [{"role": "user", "content": "What's the weather in Oslo?"}]

while True:
    completion = client.chat_completions({
        "model": "openai/gpt-5-nano",
        "messages": messages,
        "tools": TOOLS,
    })
    message = completion["choices"][0]["message"]
    messages.append(message)

    calls = message.get("tool_calls")
    if not calls:
        print(message["content"])
        break

    for call in calls:
        fn = call["function"]
        result = IMPLEMENTATIONS[fn["name"]](**json.loads(fn["arguments"]))
        messages.append({
            "role": "tool",
            "tool_call_id": call["id"],
            "content": json.dumps(result),
        })

Forcing a tool

tool_choice controls whether the model may, must, or must not call one.

Value	Effect
"auto"	The model decides. The default when tools is present
"none"	No tool calls; answer in text
"required"	The model must call some tool
{ "type": "function", "function": { "name": "get_weather" } }	It must call that one

Tool calls in a stream

Streamed tool calls arrive as fragments, and arguments is built up across chunks. Reassemble by index.

calls: dict[int, dict] = {}

for chunk in stream:
    for fragment in chunk["choices"][0]["delta"].get("tool_calls", []):
        call = calls.setdefault(
            fragment["index"], {"id": "", "name": "", "arguments": ""}
        )
        call["id"] += fragment.get("id", "")
        call["name"] += fragment.get("function", {}).get("name", "")
        call["arguments"] += fragment.get("function", {}).get("arguments", "")

# Only now is each `arguments` a complete JSON string.

Do not parse arguments until the stream ends. A fragment is a slice of a JSON string, and a slice of valid JSON is rarely valid JSON.

Custom tool calls

Alongside type: "function", the response types model type: "custom" calls, which carry custom: { name, input } — a raw string rather than JSON arguments. Branch on type before reaching for function.

Next

Structured outputs

When you want a shaped answer rather than a function call.

Streaming

The chunk shape these fragments arrive in.