Tool Calling

The Responses API supports tool calling to give models access to external functions. Define tools in your request with a name, description, and JSON schema for parameters. When the model determines it needs a tool to answer the user’s question, it returns a function_call output with the tool name and arguments for you to execute.

The Responses API is best supported on the Enterprise plan. Use https://enterprise.blackbox.ai as the base URL for full model availability and production reliability. The API is also available on standard plans at https://api.blackbox.ai, where it is currently experimental.

Basic Tool Calling

const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.3-codex',
    input: [
      {
        type: 'message',
        role: 'user',
        content: 'What is the weather like in New York?',
      },
    ],
    tools: [
      {
        type: 'function',
        name: 'get_weather',
        description: 'Get the current weather in a location',
        parameters: {
          type: 'object',
          properties: {
            location: {
              type: 'string',
              description: 'The city and state, e.g. San Francisco, CA',
            },
          },
          required: ['location'],
        },
      },
    ],
    tool_choice: 'auto',
  }),
});

const data = await response.json();
console.log(data);

Tool Call Response

When the model decides to call a tool, the response includes a function_call output:

{
  "output": [
    {
      "type": "function_call",
      "name": "get_weather",
      "arguments": "{\"location\": \"New York, NY\"}",
      "call_id": "call_abc123"
    }
  ]
}

Parse the arguments and execute your function, then send the result back in a follow-up request:

// Parse and execute the function call
const functionCall = data.output[0];
const args = JSON.parse(functionCall.arguments);
const weatherResult = await getWeather(args.location);

// Send the result back
const followUp = await fetch('https://enterprise.blackbox.ai/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.3-codex',
    input: [
      {
        type: 'message',
        role: 'user',
        content: 'What is the weather like in New York?',
      },
      {
        type: 'function_call',
        call_id: functionCall.call_id,
        name: functionCall.name,
        arguments: functionCall.arguments,
      },
      {
        type: 'function_call_output',
        call_id: functionCall.call_id,
        output: JSON.stringify(weatherResult),
      },
    ],
    tools: [
      {
        type: 'function',
        name: 'get_weather',
        description: 'Get the current weather in a location',
        parameters: {
          type: 'object',
          properties: {
            location: { type: 'string', description: 'The city and state' },
          },
          required: ['location'],
        },
      },
    ],
  }),
});

const finalData = await followUp.json();
console.log(finalData.output[0].content[0].text);

Tool Choice Options

Control how the model uses tools with the tool_choice parameter:

Value	Behavior
`"auto"`	The model decides whether to call a tool
`"required"`	The model must call at least one tool
`"none"`	The model cannot call any tools

Request Parameters

tools

array

required

Array of tool definitions. Each tool object contains:

type: Always "function"
name: The function name the model will use
description: Describes when and how to use this tool
parameters: JSON Schema object defining the function’s parameters

tool_choice

string | object

Controls tool usage. Set to "auto" (default), "required", or "none". To force a specific tool, pass {"type": "function", "name": "tool_name"}.

parallel_tool_calls

boolean

When true, the model may call multiple tools simultaneously. Default: true

Use Case: Coding Agent

A coding agent gives the model a set of file system and terminal tools and runs an agentic loop — calling the API, executing whatever tools the model requests, and feeding the results back — until the model returns a plain text response with no further tool calls. Define seven SWE tools:

Python

TOOLS = [
    {
        "type": "function",
        "name": "read_file",
        "description": "Read the full contents of a file at the given path.",
        "parameters": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path to read"},
            },
            "required": ["path"],
        },
    },
    {
        "type": "function",
        "name": "write_file",
        "description": "Write content to a file, creating it if it doesn't exist.",
        "parameters": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path to write to"},
                "content": {"type": "string", "description": "Full content to write"},
            },
            "required": ["path", "content"],
        },
    },
    {
        "type": "function",
        "name": "edit_file",
        "description": "Replace the first occurrence of old_string with new_string in a file.",
        "parameters": {
            "type": "object",
            "properties": {
                "path": {"type": "string"},
                "old_string": {"type": "string", "description": "Exact string to find"},
                "new_string": {"type": "string", "description": "Replacement string"},
            },
            "required": ["path", "old_string", "new_string"],
        },
    },
    {
        "type": "function",
        "name": "search_file",
        "description": "Search for a regex pattern in a file and return matching lines with line numbers.",
        "parameters": {
            "type": "object",
            "properties": {
                "path": {"type": "string"},
                "pattern": {"type": "string", "description": "Regex pattern to search for"},
            },
            "required": ["path", "pattern"],
        },
    },
    {
        "type": "function",
        "name": "execute_command",
        "description": (
            "Run a shell command and return its output. Use this to execute scripts, "
            "run tests, install packages, compile code, or inspect the environment."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "Shell command to execute"},
                "working_directory": {
                    "type": "string",
                    "description": "Directory to run the command in (default: current directory)",
                },
            },
            "required": ["command"],
        },
    },
    {
        "type": "function",
        "name": "list_directory",
        "description": "List the files and subdirectories in a directory.",
        "parameters": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Directory path to list (default: current directory)"},
            },
            "required": [],
        },
    },
    {
        "type": "function",
        "name": "glob_files",
        "description": "Find files matching a glob pattern, e.g. '**/*.py' or 'src/**/*.ts'.",
        "parameters": {
            "type": "object",
            "properties": {
                "pattern": {"type": "string", "description": "Glob pattern to match files against"},
                "directory": {"type": "string", "description": "Root directory for the search (default: current directory)"},
            },
            "required": ["pattern"],
        },
    },
]

Then run the agentic loop:

Python

import os, json, requests

API_KEY = os.environ["BLACKBOX_API_KEY"]
BASE_URL = "https://enterprise.blackbox.ai/v1/responses"
MODEL = "openai/gpt-5.3-codex"

def run_agent(task: str, max_iterations: int = 10) -> str:
    messages = [
        {
            "type": "message",
            "role": "system",
            "content": (
                "You are a coding assistant with access to file system and terminal tools. "
                "Use the tools to read, write, edit, search files, run terminal commands, "
                "list directories, and find files to complete the task. "
                "When done, summarize what you did."
            ),
        },
        {"type": "message", "role": "user", "content": task},
    ]

    for _ in range(max_iterations):
        data = requests.post(
            BASE_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"model": MODEL, "input": messages, "tools": TOOLS, "tool_choice": "auto"},
            timeout=60,
        ).json()

        outputs = data.get("output", [])
        function_calls = [o for o in outputs if o.get("type") == "function_call"]

        if not function_calls:
            # No more tool calls — agent is done
            for out in outputs:
                for part in out.get("content", []):
                    if isinstance(part, dict) and part.get("type") == "output_text":
                        return part["text"]

        # Append model outputs to conversation
        messages.extend(outputs)

        # Execute each tool call and return results
        for fc in function_calls:
            args = json.loads(fc.get("arguments", "{}"))
            result = execute_tool(fc["name"], args)          # your dispatch function
            messages.append({
                "type": "function_call_output",
                "call_id": fc["call_id"],
                "output": result,
            })

    return "Max iterations reached."

The agent loop continues until the model returns a response with no function_call outputs. Always set a max_iterations guard to prevent runaway loops.

Example tasks this agent handles:

"Read main.py and tell me what the entry point function does."
"Write a file /tmp/utils.py with a helper function for parsing JSON, then read it back to confirm."
"Search app.py for all lines containing 'TODO' and list their line numbers."
"Edit config.py: replace DEBUG = False with DEBUG = True, then verify the change."
"Run python3 tests/test_api.py and report any failures."
"List the project root and find all TypeScript files under src/."

Endpoints

Basic Tool Calling

Tool Call Response

Tool Choice Options

Request Parameters

Use Case: Coding Agent

Next Steps

Text Generation

Streaming

Endpoints

​Basic Tool Calling

​Tool Call Response

​Tool Choice Options

​Request Parameters

​Use Case: Coding Agent

​Next Steps

Text Generation

Streaming

Basic Tool Calling

Tool Call Response

Tool Choice Options

Request Parameters

Use Case: Coding Agent

Next Steps