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

  1. You define functions in the tools parameter
  2. The model decides if a function should be called
  3. The model returns a tool_calls object with function name + arguments
  4. You execute the function and send the result back
  5. 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:

ValueBehaviour
"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. The json_schema object is required; omitting it returns a missing_json_schema error.
  • {"type": "json_object"} — valid JSON with no schema. Not available on Anthropic-backed models, which have no equivalent; those return a 400 naming the parameter rather than silently ignoring it. Use json_schema instead, 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.

Function Calling | SovereignEG Docs