Function Calling
Function calling lets the model invoke functions you define. The model decides when to call a function and generates the arguments — your code executes it and returns the result.
How it works
- You define functions in the
toolsparameter - The model decides if a function should be called
- The model returns a
tool_callsobject with function name + arguments - You execute the function and send the result back
- The model uses the result to form its final response
Example: Weather lookup
import json
from openai import OpenAI
client = OpenAI(api_key="sk-...", base_url="https://remed-preprod-backend.sovereigneg.com/v1")
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, e.g. Cairo, Riyadh"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit"
}
},
"required": ["city"]
}
}
}
]
response = client.chat.completions.create(
model="gpt-oss-20b",
messages=[{"role": "user", "content": "What's the weather in Cairo?"}],
tools=tools,
tool_choice="auto"
)
message = response.choices[0].message
if message.tool_calls:
messages = [{"role": "user", "content": "What's the weather in Cairo?"}, message]
for call in message.tool_calls:
name = call.function.name
args = json.loads(call.function.arguments)
print(f"Model wants to call: {name}({args})")
# Execute your function
result = get_weather(**args) # your implementation
# One tool message per call, with the matching tool_call_id
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result)
})
# One follow-up, after every call has its result
followup = client.chat.completions.create(
model="gpt-oss-20b",
messages=messages,
tools=tools,
)
print(followup.choices[0].message.content)Tool response format
When the model decides to call a function:
{
"choices": [{
"message": {
"role": "assistant",
"content": null,
"tool_calls": [{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"Cairo\", \"unit\": \"celsius\"}"
}
}]
},
"finish_reason": "tool_calls"
}]
}Multiple tools
You can define multiple functions. The model picks the right one based on the user's request:
tools = [
{"type": "function", "function": {"name": "search_docs", ...}},
{"type": "function", "function": {"name": "create_ticket", ...}},
{"type": "function", "function": {"name": "get_user_info", ...}},
]Tool names
A tool name can be up to 256 characters, so the long <server>_<tool> names that MCP clients such as OpenCode build are accepted as they are. Where a model's provider takes only shorter names (64 characters on OpenAI-compatible hosts, 128 on Anthropic, and no . or : on some of them), SovereignEG sends that provider a short, stable alias instead and gives the tool calls in the response your own names back, streamed or not, so your code reads the names you sent. The alias can still show up where the model writes it itself (its answer, its reasoning or a call's arguments) and in an error message from the provider. A name over 256 characters is refused with a 422 (invalid_request_body).
Controlling which tool is called
tool_choice decides whether — and which — tool the model may call. Four forms are accepted:
| Value | Behaviour |
|---|---|
"auto" | The model decides whether to call a tool. Default when tools is present. |
"none" | Never call a tool. The model answers with text only, even though tools was sent. |
"required" | Must call at least one tool. Use when a plain-text answer is not acceptable. |
{"type": "function", "function": {"name": "get_weather"}} | Must call exactly this tool. |
response = client.chat.completions.create(
model="gpt-oss-20b",
messages=[{"role": "user", "content": "What's the weather in Cairo?"}],
tools=tools,
tool_choice={"type": "function", "function": {"name": "get_weather"}},
)Forcing a specific tool is the reliable way to get structured data out of a model
that would otherwise reply in prose — you define the shape you want as the tool's
parameters schema and read it back from arguments.
Parallel tool calls
A model can request several tools in a single turn. tool_calls is an array, so
always iterate it rather than reading tool_calls[0]:
message = response.choices[0].message
for call in message.tool_calls or []:
result = dispatch(call.function.name, json.loads(call.function.arguments))
followup_messages.append({
"role": "tool",
"tool_call_id": call.id, # ← must match the call you are answering
"content": json.dumps(result),
})Send one role: "tool" message per call, each carrying the matching
tool_call_id, and append them all before your next request. Skipping one leaves
the conversation in a state most models reject.
Set parallel_tool_calls: false to ask for at most one call per turn. Whether it is honoured depends on the model: Claude models served directly by Anthropic ignore it and may still return several calls, so always iterate tool_calls.
Streaming tool calls
With stream: true, tool calls arrive in fragments that you must accumulate.
The name and id come first; arguments then dribbles in as partial JSON, so any
individual chunk is usually invalid JSON on its own:
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_abc","type":"function",
"function":{"name":"get_weather","arguments":""}}]}}]}
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"ci"}}]}}]}
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"ty\":\"Ca"}}]}}]}
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"iro\"}"}}]}}]}
data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}
data: {"choices":[],"usage":{"prompt_tokens":52,"completion_tokens":17,"total_tokens":69}}
data: [DONE]
Accumulate by index — that is what ties fragments to the call they belong to,
and it is how parallel calls stay separated:
calls: dict[int, dict] = {}
for chunk in client.chat.completions.create(..., tools=tools, stream=True):
if not chunk.choices: # usage-only chunk at the end of the stream
continue
for fragment in chunk.choices[0].delta.tool_calls or []:
slot = calls.setdefault(fragment.index, {"id": "", "name": "", "arguments": ""})
if fragment.id:
slot["id"] = fragment.id
if fragment.function.name:
slot["name"] = fragment.function.name
slot["arguments"] += fragment.function.arguments or ""
# Only now is each slot["arguments"] complete, parseable JSON.
for slot in calls.values():
args = json.loads(slot["arguments"])Only call json.loads once the stream ends. Parsing a fragment as it arrives is
the single most common streaming tool-call bug.
Structured output with response_format
response_format constrains the model's text reply — a separate mechanism from
tools, useful when you want JSON back but have no function to call:
response = client.chat.completions.create(
model="gpt-oss-20b",
messages=[{"role": "user", "content": "List 3 cities in Egypt."}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "cities",
"schema": {
"type": "object",
"properties": {"cities": {"type": "array", "items": {"type": "string"}}},
"required": ["cities"],
},
},
},
)Supported values:
{"type": "text"}— the default, ordinary prose.{"type": "json_schema", "json_schema": {...}}— the reply conforms to your schema. Thejson_schemaobject is required; omitting it returns amissing_json_schemaerror.{"type": "json_object"}— valid JSON with no schema. Not available on Anthropic-backed models, which have no equivalent; those return a400naming the parameter rather than silently ignoring it. Usejson_schemainstead, or pick a model from an OpenAI-compatible provider.
Support varies by model. When you need a guarantee on a specific model, forcing a
tool via tool_choice is the more portable route.
Supported models
Function calling needs a model that supports tools, and not every model does.
Look for tools under Supported parameters on the model's page in
Dashboard → Models, or in the supported_parameters list that
GET /v1/models returns for most models. The Tool calling row
(capabilities.supports_tools in the API) shows Yes for chat models unless
the provider reports otherwise, so confirm with the cURL quick-test below before
you rely on a model.
Model IDs change — use GET /v1/models rather than hardcoding names from examples.
cURL quick-test
Confirm tool-calling is wired end-to-end without leaving your shell:
curl https://remed-preprod-backend.sovereigneg.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<your-model-id>",
"messages": [{"role":"user","content":"What is the weather in Cairo? Use the tool."}],
"tools": [{
"type":"function",
"function":{
"name":"get_weather",
"description":"Get the current weather for a city",
"parameters":{
"type":"object",
"properties":{"city":{"type":"string"}},
"required":["city"]
}
}
}],
"tool_choice":"auto"
}' | jq '.choices[0].message.tool_calls'
# expect: a list with one entry whose function.arguments contains {"city":"Cairo"}.If you get tool_calls: null and a free-form text answer, the model may not
support tool calling — try another model from the catalog or contact support.