> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai21.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Function Calling

> Learn how to extend Jamba's capabilities by giving it access to custom functions and external tools

## 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.

<Note>
  Function calling is available for all Jamba models via the Chat Completions API.
</Note>

## How It Works

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

## Function Calling Example

<Steps>
  <Step title="Define Your Function">
    First, define the function you want to make available to the model:

    <CodeGroup>
      ```python Python theme={"system"}
      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"]
                  }
              }
          }
      ]
      ```

      ```typescript TypeScript theme={"system"}
      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"]
            }
          }
        }
      ];
      ```
    </CodeGroup>
  </Step>

  <Step title="Make the Chat Request">
    Create a chat request with your tools and user message:

    <CodeGroup>
      ```python Python theme={"system"}
      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)
      ```

      ```typescript TypeScript theme={"system"}
      import { AI21Client } from 'ai21-typescript';

      const client = new AI21Client();

      const messages = [
          {
              role: "user",
              content: "Convert 500 GBP to Japanese yen"
          }
      ];

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

      console.log(response.choices[0].message);
      ```
    </CodeGroup>
  </Step>

  <Step title="Execute Function Calls">
    Check if the model wants to call a function and execute it:

    <CodeGroup>
      ```python Python theme={"system"}
      # 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
                  ))
      ```

      ```typescript TypeScript theme={"system"}
      // Check if the model wants to call a function
      const message = response.choices[0].message;

      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
                  });
              }
          }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Get Final Response">
    Send the function results back to the model for the final response:

    <CodeGroup>
      ```python Python theme={"system"}
          # 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)
      ```

      ```typescript TypeScript theme={"system"}
          // 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);
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Complete Examples

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

<Accordion title="Complete Python Example">
  ```python theme={"system"}
  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)
  ```
</Accordion>

<Accordion title="Complete TypeScript Example">
  ```typescript theme={"system"}
  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);
  ```
</Accordion>