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
1
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"]
}
}
}
]
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"]
}
}
}
];
2
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)
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);
3
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
))
// 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
});
}
}
}
4
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)
// 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);
}
Complete Examples
For reference, here are the complete working examples that put all the steps together:Complete Python Example
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
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);