Function calling (also known as tool calling) is a way for models to interface with external systems and access data outside their training data. You describe your functions with a JSON schema, the model decides when to call them, and your code executes them. Spro supports the OpenAI tool-calling format on both the Chat Completions API and the Responses API — and adapts it to each provider's native shape, so the same code works no matter which model serves the request.
How it works
Three key terms:
- Tool — a piece of functionality you tell the model it has access to, defined by a JSON schema. You could give the model tools to get the weather for a location, access account details, or issue refunds.
- Tool call — a special kind of model response. The model examines the prompt and, instead of answering directly, returns a request to call one of your tools — e.g.
get_weatherwithlocation: "Paris". - Tool call output — the response your code generates for a tool call. It's sent back to the model (referenced by the call's ID), and the model produces the final answer — e.g. "The weather in Paris today is 25°C."
The tool calling flow has five steps:
- Make a request to the model with the tools it could call
- Receive a tool call from the model
- Execute the function in your application with the input from the tool call
- Make a second request to the model with the tool output
- Receive a final response from the model (or more tool calls)
Complete example — Chat Completions
An end-to-end flow for a get_weather function:
import jsonfrom openai import OpenAI
client = OpenAI( base_url="https://spro.hridaai.com/v1", api_key="YOUR_SPRO_API_KEY",)
# 1. Define a list of callable tools for the modeltools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current temperature for a given location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City and country, e.g. Bogotá, Colombia", } }, "required": ["location"], "additionalProperties": False, }, }, }]
def get_weather(location: str) -> str: # Replace with a real weather API call return json.dumps({"location": location, "temperature": 25, "unit": "C"})
messages = [{"role": "user", "content": "What's the weather in Paris?"}]
# 2. Prompt the model with tools definedresponse = client.chat.completions.create( model="gpt-oss-20b", messages=messages, tools=tools,)message = response.choices[0].message
# 3. Execute the function logicif message.tool_calls: messages.append(message) for tool_call in message.tool_calls: args = json.loads(tool_call.function.arguments) result = get_weather(**args)
# 4. Provide the function call result to the model messages.append( { "role": "tool", "tool_call_id": tool_call.id, "content": result, } )
# 5. The model produces the final answerfinal = client.chat.completions.create( model="gpt-oss-20b", messages=messages, tools=tools,)print(final.choices[0].message.content)# The weather in Paris today is 25°C.Complete example — Responses API
The same flow on the Responses API. Tool calls come back as function_call output items, and results go back as function_call_output items:
import jsonfrom openai import OpenAI
client = OpenAI( base_url="https://spro.hridaai.com/v1", api_key="YOUR_SPRO_API_KEY",)
tools = [ { "type": "function", "name": "get_weather", "description": "Get current temperature for a given location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City and country, e.g. Bogotá, Colombia", } }, "required": ["location"], "additionalProperties": False, }, "strict": True, }]
def get_weather(location: str) -> str: return json.dumps({"location": location, "temperature": 25, "unit": "C"})
input_list = [{"role": "user", "content": "What's the weather in Paris?"}]
# 1–2. Prompt the model with tools definedresponse = client.responses.create( model="gpt-oss-20b", tools=tools, input=input_list,)
# Save model output for the next turninput_list += response.output
for item in response.output: if item.type == "function_call": # 3. Execute the function logic location = json.loads(item.arguments)["location"] result = get_weather(location)
# 4. Provide the function call result to the model input_list.append( { "type": "function_call_output", "call_id": item.call_id, "output": result, } )
# 5. The model produces the final answerresponse = client.responses.create( model="gpt-oss-20b", tools=tools, input=input_list,)print(response.output_text)# The weather in Paris today is 25°C.Defining functions
Functions are declared in the tools parameter of each request. Each definition has these properties:
| Field | Description |
|---|---|
type | This should always be function |
name | The function's name (e.g. get_weather) |
description | Details on when and how to use the function |
parameters | JSON schema defining the function's input arguments |
strict | Whether to enforce strict mode for the function call |
Because parameters is a JSON schema, you can use property types, enums, descriptions, nested objects, and more:
{ "type": "function", "name": "get_weather", "description": "Retrieves current weather for the given location.", "strict": true, "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City and country e.g. Bogotá, Colombia" }, "units": { "type": ["string", "null"], "enum": ["celsius", "fahrenheit"], "description": "Units the temperature will be returned in." } }, "required": ["location", "units"], "additionalProperties": false }}Note
Write clear, detailed function names and parameter descriptions — the model chooses tools based on them. Explicitly describe what each parameter is for and what the output represents, and keep the number of functions available per request small (under ~20) for the best accuracy. Function definitions are injected into the request, so they count toward the model's context and are billed as input tokens.
Handling function calls
A model response can include zero, one, or multiple tool calls — always assume there may be several. Each call carries a call_id, the function name, and JSON-encoded arguments:
[ { "id": "fc_12345xyz", "call_id": "call_12345xyz", "type": "function_call", "name": "get_weather", "arguments": "{\"location\":\"Paris, France\"}" }, { "id": "fc_67890abc", "call_id": "call_67890abc", "type": "function_call", "name": "get_weather", "arguments": "{\"location\":\"Bogotá, Colombia\"}" }]Loop over every call, execute it, and append one tool result per call_id. The result is typically a string — JSON, plain text, or an error code; the model interprets it. If a function has no return value (e.g. send_email), return a string like "success".
Additional configurations
Tool choice
By default the model decides when and how many tools to use ("auto"). Force specific behavior with tool_choice:
# "auto" (default) — call zero, one, or multiple functionstool_choice="auto"
# "required" — the model must call one or more functionstool_choice="required"
# Forced function — call exactly one specific functiontool_choice={"type": "function", "function": {"name": "get_weather"}}
# "none" — imitate passing no functions at alltool_choice="none"Parallel function calls
The model may call multiple functions in a single turn (the example above shows two get_weather calls in one response). Execute them all and return one tool message each, matched by tool_call_id. To ensure at most one tool is called per turn, set parallel_tool_calls=False.
Strict mode
Setting "strict": true ensures function calls reliably adhere to the schema instead of being best-effort — we recommend always enabling it. Strict mode has two requirements:
additionalPropertiesmust befalsefor each object inparameters- All fields in
propertiesmust be listed inrequired— denote optional fields by addingnullas a type option (e.g."type": ["string", "null"])
Streaming tool calls
With stream=True, tool calls stream like any other response — you see which function is being called and its arguments fill in in real time. On the Responses API, response.function_call_arguments.delta events carry fragments of the arguments string; accumulate them until the done event:
stream = client.responses.create( model="gpt-oss-20b", input=[{"role": "user", "content": "What's the weather in Paris today?"}], tools=tools, stream=True,)
final_tool_calls = {}for event in stream: if event.type == "response.output_item.added": final_tool_calls[event.output_index] = event.item elif event.type == "response.function_call_arguments.delta": if final_tool_calls[event.output_index]: final_tool_calls[event.output_index].arguments += event.deltaOn Chat Completions, accumulate delta.tool_calls fragments the same way, keyed by their index. See Streaming for the general streaming setup.
Cross-provider behavior
You never write provider-specific tool code — Spro adapts your OpenAI-style tools to each upstream's native shape:
- OpenAI-compatible providers (OpenAI, DeepSeek, Z.AI, Mistral, and others): native target —
toolskeeps the OpenAI shape on the wire - Anthropic: OpenAI
toolsare mapped to Anthropic tools withinput_schema, preserving JSON Schemapropertiesandrequired - Google: OpenAI
toolsare mapped tofunctionDeclarations, withname,description, andparameterscarried through
Declare your functions once in the OpenAI format and switch models with a string change. And for multi-step agent loops, the OpenAI Agents SDK runs this whole cycle for you — define a @function_tool and the SDK handles the round trip.
