HridaSpro Docs

Advanced

Function Calling

Connect models to your tools and functions — the OpenAI tool-calling flow, on every provider through Spro.

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_weather with location: "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:

  1. Make a request to the model with the tools it could call
  2. Receive a tool call from the model
  3. Execute the function in your application with the input from the tool call
  4. Make a second request to the model with the tool output
  5. 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:

FieldDescription
typeThis should always be function
nameThe function's name (e.g. get_weather)
descriptionDetails on when and how to use the function
parametersJSON schema defining the function's input arguments
strictWhether 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:

  1. additionalProperties must be false for each object in parameters
  2. All fields in properties must be listed in required — denote optional fields by adding null as 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.delta

On 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 — tools keeps the OpenAI shape on the wire
  • Anthropic: OpenAI tools are mapped to Anthropic tools with input_schema, preserving JSON Schema properties and required
  • Google: OpenAI tools are mapped to functionDeclarations, with name, description, and parameters carried 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.

What's Next