Function Calling
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Function calling enables AI models to interact with external tools, APIs, and services by generating structured function calls with validated parameters. This powerful capability transforms language models into intelligent agents that can perform actions, retrieve data, and orchestrate complex workflows.

Overview

When you provide function definitions to a model, it can intelligently decide when and how to call those functions based on the user's request. The model generates structured JSON with function names and parameters, which you can then execute in your application.

How It Works

The Flow:

Define Tools - Provide function schemas with names, descriptions, and parameters
Model Analyzes - AI determines if and which tools to call based on context
Structured Output - Model generates valid JSON with function name and arguments
Execution - Your application executes the function or backend handles it automatically
Result Integration - Function results are fed back to the model
Final Response - Model generates natural language response using the data

Function Types

Aitronos supports two types of function calling:

1. Pass-Through Functions (Client-Side)

Custom functions you define and execute in your application.

When to Use:

Interact with your own APIs or databases
Perform business logic specific to your application
Access resources only available to your backend
Maintain full control over function execution

Example:

{
  "type": "function",
  "name": "get_user_orders",
  "description": "Retrieve order history for a user",
  "parameters": {
    "type": "object",
    "properties": {
      "userId": {
        "type": "string",
        "description": "The unique user identifier"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of orders to return"
      }
    },
    "required": ["userId"]
  }
}

2. Built-In Functions (Server-Side)

Pre-built tools executed automatically by Aitronos backend.

Available Built-In Tools:

Web Search - Real-time internet search and information retrieval
File Search - Search through uploaded documents and files
Code Interpreter - Execute Python code in sandboxed environment
Image Generation - Generate or edit images
Computer Use - Interact with virtual desktop environments

Example:

{
  "type": "webSearch",
  "searchContextSize": "medium"
}

Agentic Tool Calling

New in 2025: Aitronos now supports fully automatic agentic tool calling where the backend manages the entire multi-step execution loop.

What is Agentic Tool Calling?

Traditional function calling requires your application to:

Make initial request
Receive tool call from model
Execute the tool
Send results back to model
Repeat until model is satisfied

Agentic tool calling automates this entirely. Make a single API request, and the backend:

Executes tools automatically (for built-in tools)
Feeds results back to the model
Allows model to make additional tool calls
Returns only the final, complete answer

Benefits

✅ Simplified Integration - Single API call instead of multi-turn loop
✅ Automatic Orchestration - No manual tool result handling
✅ Built-In Execution - Common tools executed server-side
✅ Conversation History - Full context preserved automatically
✅ Multi-Step Workflows - Model can chain multiple tool calls intelligently

Supported Models

Model	Execution Style	Best For
`gpt-5`	Sequential (one at a time)	Complex reasoning, step-by-step tasks
`gpt-4o`	Sequential	Balanced performance
`claude-sonnet-4-20250514`	Parallel (simultaneous)	Fast multi-tool execution
`claude-3-5-sonnet-20241022`	Parallel	Efficient batch operations

Example: Weather Report Workflow

Single API Call:

import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "organizationId": "org_abc123",
        "model": "gpt-5",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Give me a weather report for major Asian cities"}]
            }
        ],
        "functions": [
            {
                "type": "function",
                "name": "get_cities",
                "description": "Get a list of 5 cities for a region",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "region": {
                            "type": "string",
                            "enum": ["asia", "europe", "americas"]
                        }
                    },
                    "required": ["region"]
                }
            },
            {
                "type": "function",
                "name": "get_temperature",
                "description": "Get current temperature for a city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string"}
                    },
                    "required": ["city"]
                }
            }
        ],
        "parallelToolCalls": False  # Sequential for GPT-5
    }
)

result = response.json()
print(result['response'])

What Happens Automatically:

Model calls get_cities(region="asia")
Backend executes → Returns ["Tokyo", "Singapore", "Seoul", "Bangkok", "Mumbai"]
Model calls get_temperature(city="Tokyo")
Backend executes → Returns {"temperature": 28}
Model calls get_temperature for remaining 4 cities
Backend executes all calls
Model generates comprehensive report:
"Here's the weather report for major Asian cities: Tokyo is 28°C, Singapore is 31°C..."

Function Schema Definition

Functions must be defined using JSON Schema format:

Required Fields

type - Always set to "function"

name - Unique identifier for the function

Must be alphanumeric with underscores
Example: get_current_weather, create_order, send_email

description - Clear explanation of what the function does

Be specific and descriptive
Include when the function should be called
Mention any important constraints

parameters - JSON Schema defining input parameters

Use type, properties, required
Add descriptions for each parameter
Specify enums for restricted values

Example Schema

{
  "type": "function",
  "name": "book_flight",
  "description": "Book a flight ticket for a passenger. Use this when the user wants to purchase airline tickets.",
  "parameters": {
    "type": "object",
    "properties": {
      "departure": {
        "type": "string",
        "description": "Departure airport code (e.g., 'JFK', 'LAX')"
      },
      "arrival": {
        "type": "string",
        "description": "Arrival airport code"
      },
      "date": {
        "type": "string",
        "format": "date",
        "description": "Flight date in YYYY-MM-DD format"
      },
      "passengers": {
        "type": "integer",
        "minimum": 1,
        "maximum": 9,
        "description": "Number of passengers"
      },
      "class": {
        "type": "string",
        "enum": ["economy", "business", "first"],
        "description": "Ticket class"
      }
    },
    "required": ["departure", "arrival", "date", "passengers"]
  },
  "strict": true
}

Tool Choice Control

Control how and when the model uses tools with the toolChoice parameter:

Options

auto (default) - Model decides whether to use tools

{
  "toolChoice": "auto"
}

none - Disable all tool usage

{
  "toolChoice": "none"
}

required - Force the model to use at least one tool

{
  "toolChoice": "required"
}

Specific Tool - Force the model to use a particular tool

{
  "toolChoice": {
    "type": "function",
    "function": {
      "name": "get_current_weather"
    }
  }
}

Parallel vs Sequential Execution

Control whether multiple tools can be called simultaneously:

Parallel Execution

Enable with parallelToolCalls: true

Benefits:

Faster execution for independent operations
Efficient for batch operations
Ideal for Claude models

Example Use Case: User asks: "Get weather for NYC, LA, and Chicago"

Model calls all three simultaneously:

[
  {"function": "get_weather", "arguments": {"city": "NYC"}},
  {"function": "get_weather", "arguments": {"city": "LA"}},
  {"function": "get_weather", "arguments": {"city": "Chicago"}}
]

Sequential Execution

Enable with parallelToolCalls: false

Benefits:

Ensures proper ordering
Each call can use results from previous calls
Ideal for GPT models

Example Use Case: User asks: "Book a flight and then reserve a hotel"

Model calls sequentially:

book_flight() → Returns confirmation number
reserve_hotel(confirmation_number) → Uses flight details

Best Practices

1. Clear Function Descriptions

❌ Bad:

{
  "name": "get_data",
  "description": "Gets data"
}

✅ Good:

{
  "name": "get_user_profile",
  "description": "Retrieve detailed user profile information including name, email, preferences, and account status. Use this when you need to access user data for personalization or account management."
}

2. Validate Function Results

Always validate and sanitize data returned from functions before passing to the model:

def execute_function(name, args):
    try:
        result = call_function(name, args)
        
        # Validate result
        if not result:
            return {"error": "Function returned no data"}
        
        # Sanitize sensitive data
        if 'password' in result:
            del result['password']
        
        return result
    except Exception as e:
        return {"error": f"Function failed: {str(e)}"}

3. Use Enums for Fixed Options

Restrict parameters to known values:

{
  "parameters": {
    "properties": {
      "priority": {
        "type": "string",
        "enum": ["low", "medium", "high", "urgent"],
        "description": "Task priority level"
      }
    }
  }
}

4. Set Reasonable Limits

Prevent excessive tool calls:

{
  "maxToolCalls": 10  // Limit total tool calls per request
}

5. Handle Errors Gracefully

Return structured error messages:

{
  "success": false,
  "error": "User not found",
  "errorCode": "USER_NOT_FOUND",
  "suggestion": "Try searching by email instead"
}

Common Patterns

Pattern 1: Data Retrieval

Use Case: Fetch information from external systems

{
  "type": "function",
  "name": "get_customer_info",
  "description": "Retrieve customer information from CRM",
  "parameters": {
    "type": "object",
    "properties": {
      "customerId": {"type": "string"}
    },
    "required": ["customerId"]
  }
}

Pattern 2: Data Modification

Use Case: Create, update, or delete records

{
  "type": "function",
  "name": "update_order_status",
  "description": "Update the status of an existing order",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {"type": "string"},
      "newStatus": {
        "type": "string",
        "enum": ["pending", "processing", "shipped", "delivered", "cancelled"]
      },
      "reason": {"type": "string"}
    },
    "required": ["orderId", "newStatus"]
  }
}

Pattern 3: Multi-Step Workflows

Use Case: Chain multiple operations

# User: "Find available hotels in Paris and book the cheapest one"

# Step 1: Model calls search_hotels
{
  "function": "search_hotels",
  "arguments": {"city": "Paris", "checkIn": "2025-06-01"}
}

# Step 2: Backend executes and returns results
# Step 3: Model analyzes results and calls booking
{
  "function": "book_hotel",
  "arguments": {"hotelId": "hotel_123", "price": 89}
}

# Step 4: Model generates confirmation message

Pattern 4: Conditional Logic

Use Case: Different actions based on data

# User: "Check my account balance and transfer $100 if I have enough"

# Step 1: Check balance
result = get_account_balance(accountId="acc_123")
# Returns: {"balance": 500}

# Step 2: Model decides to proceed with transfer
transfer_funds(from="acc_123", to="acc_456", amount=100)

Error Handling

Common Errors

Invalid Function Definition:

{
  "error": {
    "message": "Invalid function schema",
    "code": "invalid_function_schema",
    "details": "Missing required field: 'parameters'"
  }
}

Function Execution Failed:

{
  "error": {
    "message": "Function execution failed",
    "code": "function_execution_error",
    "function": "get_weather",
    "details": "API timeout after 30s"
  }
}

Max Tool Calls Exceeded:

{
  "error": {
    "message": "Maximum tool calls exceeded",
    "code": "max_tool_calls_exceeded",
    "limit": 10,
    "actual": 11
  }
}

Advanced Topics

Function Call Logs

Enable detailed logging with include:

{
  "include": ["function_calls.logs", "function_calls.sources"]
}

Returns:

{
  "functionCalls": [
    {
      "name": "get_weather",
      "arguments": {"city": "Paris"},
      "executionTime": 234,
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ]
}

Strict Mode

Enforce exact schema compliance:

{
  "strict": true  // Model guarantees parameters match schema exactly
}

Combining Tools

Mix built-in and custom functions:

{
  "tools": [
    {"type": "webSearch"},              // Built-in
    {"type": "fileSearch"},             // Built-in
    {                                    // Custom
      "type": "function",
      "name": "save_to_database",
      "parameters": {...}
    }
  ]
}

Agentic Workflows Guide - Deep dive into multi-step automation
Web Search Tool - Built-in internet search
Code Interpreter - Python execution environment
Structured Output - JSON response formatting
API Reference: Create Response - Full API documentation

Examples

See complete working examples:

Function CallingCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude