Function Calling

Overview

Function calling allows Jamba models to intelligently decide when and how to call external functions or tools based on the conversation context. Instead of trying to answer everything directly, the model can request specific function calls with appropriate parameters, enabling integration with APIs, databases, calculators, and other external systems.

Function calling is available for all Jamba models via the Chat Completions API.

How It Works

Define your functions - Provide JSON schemas describing available tools
Jamba decides - The model determines if and when to call functions
Execute functions - Your code runs the requested functions
Get response - Jamba uses the results to generate its final answer

Function Calling Example

Define Your Function

First, define the function you want to make available to the model:

import json
import requests

def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
    """Convert an amount from one currency to another using live exchange rates"""
    # Using exchangerate-api.com (free tier available)
    response = requests.get(
        f"https://api.exchangerate-api.com/v4/latest/{from_currency.upper()}"
    )
    data = response.json()
    
    if to_currency.upper() not in data["rates"]:
        return f"Currency {to_currency} not found"
    
    exchange_rate = data["rates"][to_currency.upper()]
    converted_amount = amount * exchange_rate
    
    result = {
        "original_amount": amount,
        "from_currency": from_currency.upper(),
        "to_currency": to_currency.upper(),
        "exchange_rate": exchange_rate,
        "converted_amount": round(converted_amount, 2)
    }
    
    return json.dumps(result)

# Define the function schema for the model
tools = [
    {
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "Convert an amount from one currency to another using current exchange rates",
            "parameters": {
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "number",
                        "description": "The amount to convert"
                    },
                    "from_currency": {
                        "type": "string",
                        "description": "The source currency code (e.g., USD, EUR, GBP)"
                    },
                    "to_currency": {
                        "type": "string",
                        "description": "The target currency code (e.g., USD, EUR, GBP)"
                    }
                },
                "required": ["amount", "from_currency", "to_currency"]
            }
        }
    }
]

Make the Chat Request

Create a chat request with your tools and user message:

from ai21 import AI21Client
from ai21.models.chat import ChatMessage

client = AI21Client()

messages = [
    ChatMessage(
        role="user", 
        content="How much is 100 USD in euros?"
    )
]

response = client.chat.completions.create(
    model="jamba-large",
    messages=messages,
    tools=tools,
    max_tokens=150
)

print(response.choices[0].message)

Execute Function Calls

Check if the model wants to call a function and execute it:

# Check if the model wants to call a function
message = response.choices[0].message

if message.tool_calls:
    # Execute the requested function
    for tool_call in message.tool_calls:
        function_name = tool_call.function.name
        function_args = json.loads(tool_call.function.arguments)
        
        if function_name == "convert_currency":
            function_result = convert_currency(**function_args)
            
            # Add the function call and result to the conversation
            messages.append(message)  # Assistant's function call
            messages.append(ChatMessage(
                role="tool",
                tool_call_id=tool_call.id,
                content=function_result
            ))

Get Final Response

Send the function results back to the model for the final response:

    # Get the final response with function results
    final_response = client.chat.completions.create(
        model="jamba-large",
        messages=messages,
        tools=tools,
        max_tokens=150
    )
        
    print(final_response.choices[0].message.content)
else:
    # No function call needed, model responded directly
    print(message.content)

Complete Examples

For reference, here are the complete working examples that put all the steps together:

Complete Python Example

import json
import requests
from ai21 import AI21Client
from ai21.models.chat import ChatMessage

def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
    """Convert an amount from one currency to another using live exchange rates"""
    # Using exchangerate-api.com (free tier available)
    response = requests.get(
        f"https://api.exchangerate-api.com/v4/latest/{from_currency.upper()}"
    )
    data = response.json()
    
    if to_currency.upper() not in data["rates"]:
        return f"Currency {to_currency} not found"
    
    exchange_rate = data["rates"][to_currency.upper()]
    converted_amount = amount * exchange_rate
    
    result = {
        "original_amount": amount,
        "from_currency": from_currency.upper(),
        "to_currency": to_currency.upper(),
        "exchange_rate": exchange_rate,
        "converted_amount": round(converted_amount, 2)
    }
    
    return json.dumps(result)

# Define the function schema for the model
tools = [
    {
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "Convert an amount from one currency to another using current exchange rates",
            "parameters": {
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "number",
                        "description": "The amount to convert"
                    },
                    "from_currency": {
                        "type": "string",
                        "description": "The source currency code (e.g., USD, EUR, GBP)"
                    },
                    "to_currency": {
                        "type": "string",
                        "description": "The target currency code (e.g., USD, EUR, GBP)"
                    }
                },
                "required": ["amount", "from_currency", "to_currency"]
            }
        }
    }
]

# Initialize client and create initial message
client = AI21Client()
messages = [
    ChatMessage(
        role="user", 
        content="How much is 100 USD in euros?"
    )
]

# Make initial request
response = client.chat.completions.create(
    model="jamba-large",
    messages=messages,
    tools=tools,
    max_tokens=150
)

message = response.choices[0].message

# Check if the model wants to call a function
if message.tool_calls:
    # Execute the requested function
    for tool_call in message.tool_calls:
        function_name = tool_call.function.name
        function_args = json.loads(tool_call.function.arguments)
        
        if function_name == "convert_currency":
            function_result = convert_currency(**function_args)
            
            # Add the function call and result to the conversation
            messages.append(message)  # Assistant's function call
            messages.append(ChatMessage(
                role="tool",
                tool_call_id=tool_call.id,
                content=function_result
            ))
    
    # Get the final response with function results
    final_response = client.chat.completions.create(
        model="jamba-large",
        messages=messages,
        tools=tools,
        max_tokens=150
    )
    
    print(final_response.choices[0].message.content)
else:
    # No function call needed, model responded directly
    print(message.content)

Complete TypeScript Example

import { AI21Client } from 'ai21-typescript';

async function convertCurrency(amount: number, fromCurrency: string, toCurrency: string): Promise<string> {
  // Convert an amount from one currency to another using live exchange rates
  const response = await fetch(
    `https://api.exchangerate-api.com/v4/latest/${fromCurrency.toUpperCase()}`
  );
  const data = await response.json();
  
  if (!(toCurrency.toUpperCase() in data.rates)) {
    return `Currency ${toCurrency} not found`;
  }
  
  const exchangeRate = data.rates[toCurrency.toUpperCase()];
  const convertedAmount = amount * exchangeRate;
  
  const result = {
    original_amount: amount,
    from_currency: fromCurrency.toUpperCase(),
    to_currency: toCurrency.toUpperCase(),
    exchange_rate: exchangeRate,
    converted_amount: Math.round(convertedAmount * 100) / 100
  };
  
  return JSON.stringify(result);
}

// Define the function schema for the model
const tools = [
  {
    type: "function",
    function: {
      name: "convert_currency",
      description: "Convert an amount from one currency to another using current exchange rates",
      parameters: {
        type: "object",
        properties: {
          amount: {
            type: "number",
            description: "The amount to convert"
          },
          from_currency: {
            type: "string",
            description: "The source currency code (e.g., USD, EUR, GBP)"
          },
          to_currency: {
            type: "string",
            description: "The target currency code (e.g., USD, EUR, GBP)"
          }
        },
        required: ["amount", "from_currency", "to_currency"]
      }
    }
  }
];

async function functionCallingExample() {
  // Initialize client and create initial message
  const client = new AI21Client();
  const messages = [
      {
          role: "user",
          content: "Convert 500 GBP to Japanese yen"
      }
  ];

  // Make initial request
  const response = await client.chat.completions.create({
      model: "jamba-large",
      messages: messages,
      tools: tools,
      max_tokens: 150
  });

  const message = response.choices[0].message;

  // Check if the model wants to call a function
  if (message.tool_calls) {
      // Execute the requested function
      for (const toolCall of message.tool_calls) {
          const functionName = toolCall.function.name;
          const functionArgs = JSON.parse(toolCall.function.arguments);
          
          if (functionName === "convert_currency") {
              const functionResult = await convertCurrency(
                  functionArgs.amount, 
                  functionArgs.from_currency, 
                  functionArgs.to_currency
              );
              
              // Add the function call and result to the conversation
              messages.push(message); // Assistant's function call
              messages.push({
                  role: "tool",
                  tool_call_id: toolCall.id,
                  content: functionResult
              });
          }
      }
      
      // Get the final response with function results
      const finalResponse = await client.chat.completions.create({
          model: "jamba-large",
          messages: messages,
          tools: tools,
          max_tokens: 150
      });
      
      console.log(finalResponse.choices[0].message.content);
  } else {
      // No function call needed, model responded directly
      console.log(message.content);
  }
}

// Run the example
functionCallingExample().catch(console.error);

Getting Started

Foundation Models

AI21 Maestro [Beta]

Private AI

Guides

Usage

AI Ethics & Data Transperancy

Additional Resources

Overview

How It Works

Function Calling Example

Complete Examples

Getting Started

Foundation Models

AI21 Maestro [Beta]

Private AI

Guides

Usage

AI Ethics & Data Transperancy

Additional Resources

​Overview

​How It Works

​Function Calling Example

​Complete Examples

Overview

How It Works

Function Calling Example

Complete Examples