Tool Calling

Give the model access to external functions and build agentic loops

Declare functions in the tools array and the model can call them. When the model decides to use a tool, it returns a function_call step and sets status: "requires_action". You run the function, feed the result back, and the model produces its final answer. Chaining multiple tool calls builds an agentic loop.

The Interactions API is best supported on the Enterprise plan. Use https://enterprise.blackbox.ai as the base URL.

Declaring Tools

import os
import requests

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }
]

response = requests.post(
    'https://enterprise.blackbox.ai/v1/interactions',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
    },
    json={
        'model': 'gemini-3.8-flash',
        'store': False,
        'tools': tools,
        'input': 'What is the weather in Paris? Use the tool.',
    },
)
print(response.json())

curl https://enterprise.blackbox.ai/v1/interactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": false,
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    ],
    "input": "What is the weather in Paris? Use the tool."
  }'

Tool-Call Response

The model returns a function_call step and status: "requires_action". The call carries an id, the name, and an arguments object:

{
  "status": "requires_action",
  "steps": [
    { "type": "thought", "signature": "AY89a1+..." },
    {
      "id": "call_152900",
      "type": "function_call",
      "name": "get_weather",
      "arguments": { "city": "Paris" }
    }
  ],
  "usage": { "total_input_tokens": 33, "total_output_tokens": 16, "total_thought_tokens": 46 }
}

Returning the Result (Nested Tool Calls)

Execute the function, then make a second request. Pass back all steps the model returned (including the thought and function_call steps) and append a function_result step containing the output. The model then produces its final answer.

You must echo the model's returned steps verbatim — the thought step carries a signature that links the tool call to the model's reasoning. Dropping it will cause an invalid_request error. The function_result step takes name and result (no id).

import os
import requests

URL = 'https://enterprise.blackbox.ai/v1/interactions'
HEADERS = {
    'Content-Type': 'application/json',
    'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
}
tools = [{
    "type": "function", "name": "get_weather",
    "parameters": {"type": "object",
                   "properties": {"city": {"type": "string"}},
                   "required": ["city"]},
}]

# 1) First call — model requests the tool
first = requests.post(URL, headers=HEADERS, json={
    'model': 'gemini-3.8-flash', 'store': False, 'tools': tools,
    'input': 'What is the weather in Paris? Then state the temperature in Celsius.',
}).json()

steps = first['steps']
fc = next(s for s in steps if s['type'] == 'function_call')

# 2) Run your function, then feed the result back with the returned steps
weather = {"tempC": 19, "sky": "sunny"}
second = requests.post(URL, headers=HEADERS, json={
    'model': 'gemini-3.8-flash', 'store': False, 'tools': tools,
    'input': steps + [
        {'type': 'function_result', 'name': fc['name'], 'result': weather},
    ],
}).json()

print(second['status'])  # "completed"

The final response completes with the tool output folded into the answer:

{
  "status": "completed",
  "steps": [
    { "type": "model_output",
      "content": [{ "type": "text", "text": "The weather in Paris is sunny, 19°C." }] }
  ]
}

Request Parameters

toolsarray

Function definitions. Each is { "type": "function", "name", "description", "parameters" }, where parameters is a JSON Schema object.

inputarray

To continue after a tool call, pass the returned steps plus a function_result step: { "type": "function_result", "name": "...", "result": { ... } }.

Response Fields

statusstring

requires_action when a tool must be run; completed once the model answers.

steps[].function_callobject

The requested call: id, name, and an arguments object.

Next Steps

Reasoning

Combine tool use with chain-of-thought

Streaming

Stream agentic loops