Tool Calling

Extend ASI:One models with custom functions and real-world actions through intelligent tool selection.

Tool calling in ASI:One allows models to go beyond text generation by invoking external functions with the right parameters. This enables integration with APIs, tools, or your own code to retrieve live data, perform tasks, or trigger actions based on user input.

Overview

Function calling enables you to integrate your custom code with the Chat Completion API in ASI:One. When given access to defined tools, the model can choose to call them based on the conversation context. After the function is called, you execute the corresponding code, return the results, and the model incorporates the output into its final reply. This guide provides instructions for connecting ASI:One models to your custom functions to retrieve data or perform specific actions.

Tool calling is enabled with models : asi1-mini, asi1-fast and asi1-extended.

Here’s a basic example of how tool calling works with ASI:One:

1
import requests
2
import json
3
4
# ASI:One API settings
5
API_KEY = "your_api_key"
6
BASE_URL = "https://api.asi1.ai/v1"
7
8
headers = {
9
"Authorization": f"Bearer {API_KEY}",
10
"Content-Type": "application/json"
11
}
12
13
# Define the get_weather tool
14
get_weather_tool = {
15
"type": "function",
16
"function": {
17
  "name": "get_weather",
18
  "description": "Get current temperature for a given location (latitude and longitude).",
19
  "parameters": {
20
    "type": "object",
21
    "properties": {
22
        "latitude": {"type": "number"},
23
        "longitude": {"type": "number"}
24
      },
25
      "required": ["latitude", "longitude"]
26
    }
27
  }
28
}
29
30
# Initial message setup
31
initial_message = [
32
  {
33
    "role": "system",
34
    "content": "You are a weather assistant. When a user asks for the weather in a location, use the get_weather tool with the appropriate latitude and longitude for that location."
35
  },
36
  {
37
    "role": "user",
38
    "content": "What's the current weather like in New York right now?"
39
  }
40
]
41
42
# First call to model
43
payload = {
44
  "model": "asi1-mini",
45
  "messages": initial_message,
46
  "tools": [get_weather_tool],
47
  "temperature": 0.7,
48
  "max_tokens": 1024
49
}
50
51
response = requests.post(
52
  f"{BASE_URL}/chat/completions",
53
  headers=headers,
54
  json=payload
55
)

Example Response

When you make a tool call request, the model will respond with the tool call details. Here’s an example response:

1
{
2
  "id": "id_t0m4Pzm0KDbMg0WaX",
3
  "model": "asi1-mini",
4
  "executable_data": [],
5
  "conversation_id": null,
6
  "thought": [],
7
  "choices": [
8
    {
9
      "index": 0,
10
      "finish_reason": "tool_calls",
11
      "message": {
12
        "role": "assistant",
13
        "content": "",
14
        "reasoning": null,
15
        "tool_calls": [
16
          {
17
            "id": "call_WzB5g",
18
            "index": 0,
19
            "type": "function",
20
            "function": {
21
              "name": "get_weather",
22
              "arguments": "{\"latitude\":40.7128,\"longitude\":-74.006}"
23
            }
24
          }
25
        ]
26
      }
27
    }
28
  ],
29
  "usage": {
30
    "prompt_tokens": 36,
31
    "completion_tokens": 8,
32
    "total_tokens": 44
33
  }
34
}

Sample Tools

Let’s look at the steps to allow a model to use a real get_weather tool defined below:

Sample get_weather function implemented in your codebase

1
import requests
2
3
def get_weather(latitude, longitude):
4
    response = requests.get(f"https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m,wind_speed_10m&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m")
5
    data = response.json()
6
    return data['current']['temperature_2m']

1
async function getWeather(latitude, longitude) {
2
  const response = await fetch(
3
    `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,wind_speed_10m&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m`
4
  );
5
  const data = await response.json();
6
  return data.current.temperature_2m;
7
}

Complete Tool Execution Cycle

Let’s walk through the complete cycle of executing a tool call with ASI:One, using the weather example:

Step 1: Initial Request with Tools

First, we make a request to the model with the tool definition and user message:

1
# Define the get_weather tool
2
get_weather_tool = {
3
    "type": "function",
4
    "function": {
5
        "name": "get_weather",
6
        "description": "Get current temperature for a given location (latitude and longitude).",
7
        "parameters": {
8
            "type": "object",
9
            "properties": {
10
                "latitude": {"type": "number"},
11
                "longitude": {"type": "number"}
12
            },
13
            "required": ["latitude", "longitude"]
14
        }
15
    }
16
}
17
18
# User's question
19
initial_message = {
20
    "role": "user",
21
    "content": "What's the current weather like in London right now?"
22
}
23
24
# First call to model
25
payload = {
26
    "model": "asi1-mini",
27
    "messages": initial_message,
28
    "tools": [get_weather_tool],
29
    "temperature": 0.7,
30
    "max_tokens": 1024
31
}
32
33
first_response = requests.post(
34
    f"{BASE_URL}/chat/completions",
35
    headers=headers,
36
    json=payload
37
)

Step 2: Parse Tool Calls from Response

The model responds with a tool call that we need to parse:

1
first_response.raise_for_status()
2
first_response_json = first_response.json()
3
4
tool_calls = first_response_json["choices"][0]["message"].get("tool_calls", [])
5
messages_history = [
6
    initial_message,
7
    first_response_json["choices"][0]["message"]
8
]

Step 3: Execute Tools and Format Results

Next, we execute the tool and format the results:

1
# Simulate execution of get_weather tool
2
def get_weather(lat, lon):
3
    response = requests.get(
4
        f"https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current=temperature_2m,wind_speed_10m"
5
    )
6
    data = response.json()
7
    return data['current']['temperature_2m']
8
9
# Process tool call
10
for tool_call in tool_calls:
11
    function_name = tool_call["function"]["name"]
12
    arguments = json.loads(tool_call["function"]["arguments"])
13
14
    if function_name == "get_weather":
15
        latitude = arguments["latitude"]
16
        longitude = arguments["longitude"]
17
        temperature = get_weather(latitude, longitude)
18
        result = {
19
            "temperature_celsius": temperature,
20
            "location": f"lat: {latitude}, lon: {longitude}"
21
        }
22
    else:
23
        result = {"error": f"Unknown tool: {function_name}"}
24
25
    # Tool result message
26
    tool_result_message = {
27
        "role": "tool",
28
        "tool_call_id": tool_call["id"],
29
        "content": json.dumps(result)
30
    }
31
    messages_history.append(tool_result_message)

Step 4: Send Results Back to Model

Now we send the tool results back to the model:

1
# Final call to model with tool results
2
final_payload = {
3
    "model": "asi1-mini",
4
    "messages": messages_history,
5
    "temperature": 0.7,
6
    "max_tokens": 1024
7
}
8
9
final_response = requests.post(
10
    f"{BASE_URL}/chat/completions",
11
    headers=headers,
12
    json=final_payload
13
)

Step 5: Receive Final Answer

Finally, we get the model’s response incorporating the tool results:

1
final_response.raise_for_status()
2
final_response_json = final_response.json()
3
4
# Final result
5
print(final_response_json["choices"][0]["message"]["content"])

Tool Result Handling in ASI:One

Here are key guidelines to ensure correct behavior and prevent common errors.

1
# Correct
2
tool_result_message = {
3
"role": "tool",
4
"tool_call_id": tool_call.id,  # Use the exact ID from the tool call
5
"content": json.dumps(result)
6
}
7
8
# Incorrect - Don't make up IDs
9
tool_result_message = {
10
"role": "tool",
11
"tool_call_id": "my_custom_id",  # This will cause an error
12
"content": json.dumps(result)
13
}

1
# Correct
2
"content": json.dumps({"key": "value"})
3
4
# Incorrect - Don't send raw objects
5
"content": {"key": "value"}  # This will cause an error

1
try:
2
# Execute tool
3
result = execute_tool(function_name, arguments)
4
content_to_send = json.dumps(result)
5
except Exception as e:
6
# Send error as tool result content
7
error_content = {
8
"error": f"Tool execution failed: {str(e)}",
9
"status": "failed"
10
}
11
content_to_send = json.dumps(error_content)
12
13
tool_result_message = {
14
"role": "tool",
15
"tool_call_id": tool_call.id, # Still use the original tool_call.id
16
"content": content_to_send
17
}
18
messages_history.append(tool_result_message)

Tool Definition

Functions are specified using the tools parameter in each API request, where each tool is described as a function object.

Each function is defined using a schema that tells the model what the function does and what input arguments it requires. The schema includes the following key fields:

• name (string) : A unique, descriptive identifier for the tool (e.g., get_weather_forecast, send_email). Use underscores or camelCase formatting. Avoid spaces or special characters.

• description (string) : A detailed explanation of what the tool does and when it should be used. Clear, specific descriptions improve the model’s ability to use the function correctly.

• parameters (object) : Defines the input parameters the tool expects.

  • type (string) : Usually set to "object" to represent input parameters.

  • properties (object) : Lists each input parameter and its details:

  • type (string): The data type (e.g., string, integer, boolean, array).

  • description (string): A clear explanation of the parameter’s purpose and expected format. Example: "City and country, e.g., 'Paris, France'"

  • enum (optional): An array of allowed values, useful when inputs must be restricted. Example: "enum": ["celsius", "fahrenheit"]

  • required (array of strings) : Lists the parameter names that must be included when calling the function.

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "get_weather",
5
    "description": "Retrieves current weather for the given location.",
6
    "parameters": {
7
      "type": "object",
8
      "properties": {
9
        "location": {
10
          "type": "string",
11
          "description": "City and country e.g. Bogotá, Colombia"
12
        },
13
        "units": {
14
          "type": "string",
15
          "enum": ["celsius", "fahrenheit"],
16
          "description": "Units the temperature will be returned in."
17
        }
18
      },
19
      "required": ["location", "units"],
20
      "additionalProperties": false
21
    },
22
    "strict": true
23
  }
24
}

Additional Configurations

ASI:One provides several options to control how and when tools are called, as well as how strictly the model adheres to your function schemas.

Tool Choice

By default, the model determines when and how many tools to use. You can control this behavior with the tool_choice parameter:

• Auto (default): The model may call zero, one, or multiple functions.

1
"tool_choice": "auto"

• Required: The model must call at least one function.

1
"tool_choice": "required"

• Forced Function: Force the model to call a specific function.

1
"tool_choice": {
2
  "type": "function",
3
  "function": { "name": "get_weather" }
4
}

• None: Prevent the model from calling any functions.

1
"tool_choice": "none"

Parallel Tool Calling

By default, the model may call multiple functions in a single turn. To restrict this and ensure only one (or zero) tool is called per turn, set:

1
"parallel_tool_calls": false

Note: If parallel tool calls are enabled, strict mode may be disabled for those calls.

Strict Mode

Setting strict to true ensures the model strictly follows your function schema. This is recommended for most use cases.

Requirements for strict mode:

1. additionalProperties must be set to false for each object in the parameters.
2. All fields in properties must be listed in required.

Example with strict mode enabled:

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "get_weather",
5
    "description": "Retrieves current weather for the given location.",
6
    "strict": true,
7
    "parameters": {
8
      "type": "object",
9
      "properties": {
10
        "location": {
11
          "type": "string",
12
          "description": "City and country e.g. Bogotá, Colombia"
13
        },
14
        "units": {
15
          "type": ["string", "null"],
16
          "enum": ["celsius", "fahrenheit"],
17
          "description": "Units the temperature will be returned in."
18
        }
19
      },
20
      "required": ["location", "units"],
21
      "additionalProperties": false
22
    }
23
  }
24
}

Example with strict mode disabled:

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "get_weather",
5
    "description": "Retrieves current weather for the given location.",
6
    "parameters": {
7
      "type": "object",
8
      "properties": {
9
        "location": {
10
          "type": "string",
11
          "description": "City and country e.g. Bogotá, Colombia"
12
        },
13
        "units": {
14
          "type": "string",
15
          "enum": ["celsius", "fahrenheit"],
16
          "description": "Units the temperature will be returned in."
17
        }
18
      },
19
      "required": ["location"]
20
    }
21
  }
22
}

Tip: We recommend enabling strict mode for reliable tool calling.