Copy to clipboard

# Connect models to external systems with tool calling Tool calling allows you to connect models to external tools and systems, which can help you add more capabilities to AI assistants and build deep integrations between your applications and the models. The `chat` method of the Imagine Client supports tool calling as a function. You describe the functions and arguments that you want to make available to the LLM model. The model outputs a JSON object containing arguments to call one or many functions. After calling any invoked functions, you can provide those results back to the model in subsequent `chat` calls. AI Appliance To use tool calling when using the Qualcomm AI On-Prem Appliance Solution, make sure that the appliance box can communicate with the relevant external APIs to achieve tool calling.

Helper utilities for the examples

Some of the following examples use some of the code from the funcs.py file. This code is shown here to help you better understand these examples.

# funcs.py

import json
import random

from datetime import datetime
from typing import Literal

import pytz
import requests

from langchain_core.utils.function_calling import convert_to_openai_tool

def get_current_weather(location, unit="fahrenheit"):
    """Get the weather for some location"""
    if "chicago" in location.lower():
        return json.dumps({"location": "Chicago", "temperature": "13", "unit": unit})
    elif "san francisco" in location.lower():
        return json.dumps(
            {"location": "San Francisco", "temperature": "55", "unit": unit}
        )
    elif "new york" in location.lower():
        return json.dumps({"location": "New York", "temperature": "11", "unit": unit})
    else:
        return json.dumps({"location": location, "temperature": "unknown"})

def get_weather_forecast(location: str) -> dict[str, str]:
    """Retrieves a simple weather forecast for a given location"""
    url = f"https://wttr.in/{location}?format=%C,%t"
    response = requests.get(url)
    if response.status_code == 200:
        result = response.text.strip().split(",")
        return {
            "location": location,
            "forecast": " ".join(result[:-1]),
            "temperature": result[-1],
        }
    else:
        return {"error": "Unable to fetch weather data"}

def get_stock_price(symbol: str) -> float:
    """Retrieves the stock price for a given symbol"""
    api_key = "your_stock_api_key"
    url = f"https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol={symbol}&apikey={api_key}"
    response = requests.get(url)
    data = response.json()

    if "Global Quote" not in data:
        return 100.0

    return float(data["Global Quote"]["05. price"])

def get_random_number(min_value: int, max_value: int) -> int:
    """Returns a random number between min_value and max_value"""
    return random.randint(min_value, max_value)

def get_current_time(time_zone: str | None = None) -> str:
    """Returns the current time in the specified time zone"""

    if time_zone is None or time_zone not in pytz.all_timezones:
        time_zone = "US/Pacific"

    format = "%Y-%m-%d %H:%M:%S"

    tz = pytz.timezone(time_zone)
    current_time = datetime.now(tz)
    return current_time.strftime(format)

def get_random_city() -> str:
    """Retrieves a random city from a list of cities"""
    cities = [
        "Groningen",
        "Enschede",
        "Amsterdam",
        "Istanbul",
        "Baghdad",
        "Rio de Janeiro",
        "Tokyo",
        "Kampala",
    ]
    return random.choice(cities)

def get_user_location(accuracy: int) -> str:
    """
    Returns the user's location based on the public IP address and accuracy level.

    Parameters:
    accuracy (int): The level of detail for the location information.
        1 - Country only
        2 - City and country
        3 - City, region, and country

    Returns:
    str: The location information based on the specified accuracy level or an error message.
    """
    # return json.dumps({"location":"Las Vegas, Nevada, United States"})
    return json.dumps({"location": "San Diego, California, United States"})

    try:
        # Retrieve public IP address
        ip_response = requests.get("https://api.ipify.org?format=json")
        ip_response.raise_for_status()
        ip_address = ip_response.json().get("ip")

        # Use public IP to get location data
        location_url = f"http://ip-api.com/json/{ip_address}"
        location_response = requests.get(location_url)
        location_response.raise_for_status()
        data = location_response.json()

        if data["status"] == "fail":
            return f"Error in get_user_location: {data.get('message', 'Unknown error')}"

        if accuracy == 1:
            return data.get("country", "Unknown country")
        elif accuracy == 2:
            return f"{data.get('city', 'Unknown city')}, {data.get('country', 'Unknown country')}"
        elif accuracy == 3:
            return f"{data.get('city', 'Unknown city')}, {data.get('regionName', 'Unknown region')}, {data.get('country', 'Unknown country')}"
        else:
            return "Invalid accuracy level. Please specify 1 (Country), 2 (City and Country), or 3 (City, Region, and Country)."
    except requests.RequestException as e:
        return f"Error: {e}"

TOOL_MAPPING = {
    f.__name__: f
    for f in (
        get_current_weather,
        get_weather_forecast,
        get_stock_price,
        get_random_number,
        get_current_time,
        get_random_city,
        get_user_location,
    )
}

def get_tools_map(
    names: list[
        Literal[
            "get_current_weather",
            "get_weather_forecast",
            "get_stock_price",
            "get_random_number",
            "get_current_time",
            "get_user_location",
            "get_random_city",
        ]
    ],
):
    # dict[str, Tuple[Callable | list[Callable], dict[str, Any] | list[dict[str, Any]]]]:

    tools_map = {}

    for name in names:
        tool = TOOL_MAPPING[name]
        tools_map[name] = {}
        tools_map[name]["call"] = tool
        tools_map[name]["schema"] = convert_to_openai_tool(tool)

    all_tools = []
    all_specs = []
    for v in tools_map.values():
        all_tools.append(v["call"])
        all_specs.append(v["schema"])

    tools_map["__all__"] = {}
    tools_map["__all__"]["call"] = all_tools
    tools_map["__all__"]["schema"] = all_specs

    return tools_map
Copy to clipboard

## Call a single tool The following example shows how to use tool calling capabilities of the `chat` method. It defines a function for a hypothetical `get_current_weather` tool, sends a message to the model, then prints the response. from rich.pretty import pprint import imagine client = imagine.ImagineClient(max_retries=1, debug=True) tools = [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, }, }, }, } ] messages = [ { "role": "system", "content": "You are a helpful assistant that can access external functions. The responses from these function calls will be appended to this dialogue. Please provide responses based on the information from these function calls.", }, {"role": "user", "content": "What is the current temperature of New York?"}, ] response = client.chat( model="Llama-3.1-8B", messages=messages, tools=tools, ) pprint(response) Copy to clipboard ## Call a single tool with helper functions The following example shows how to use tool calling capabilities of the `chat` method using helper functions to create the schema instead of explicitly defining it as in the previous example. from langchain_core.utils.function_calling import convert_to_openai_tool from rich.pretty import pprint import imagine client = imagine.ImagineClient(max_retries=1, debug=True) def get_current_weather(location: str) -> dict[str, str]: """Retrieves current weather based on the location""" return {"location": location, "forecast": "Sunny", "temperature": "35.5"} messages = [ { "role": "system", "content": "You are a helpful assistant that can access external functions. The responses from these function calls will be appended to this dialogue. Please provide responses based on the information from these function calls.", }, {"role": "user", "content": "What is the current temperature of New York?"}, ] functions = [get_current_weather] tools = [convert_to_openai_tool(t) for t in functions] response = client.chat(model="Llama-3.1-8B", messages=messages, tools=tools) pprint(response, expand_all=True) Copy to clipboard ## Call a tool with multi-turn interactions This example shows multi-turn interactions for tool calling. Based on the first `response`, the model decides if it can provide an answer without calling a tool or if any of the provided tools are needed before providing an answer. import json import funcs from rich.pretty import pprint import imagine # ------------------------------------------------------------------------------------- client = imagine.ImagineClient(max_retries=1, debug=True) messages = [ { "role": "system", "content": "You are a helpful assistant that can access external functions. The responses from these function calls will be appended to this dialogue. Please provide responses based on the information from these function calls.", }, { "role": "user", "content": "What is the current temperature of New York, San Francisco and Chicago?", }, ] tools_map = funcs.get_tools_map(["get_current_weather"]) MODEL = "Llama-3.1-8B" # -------------------------------------------------------------------------------------- tools_spec = tools_map["__all__"]["schema"] response = client.chat( model=MODEL, messages=messages, tools=tools_spec, ) messages.append(response.choices[0].message) pprint(response, expand_all=True) tool_calls = response.choices[0].message.tool_calls if tool_calls: for tool_call in tool_calls: function_call = tool_call.function name = function_call.name arguments = json.loads(function_call.arguments) for function in tools_map["__all__"]["call"]: if function.__name__ == name: print(f"Invoking tool call: {name} with args :: {arguments}") function_response = function(**arguments) print(f"Result of invocation {function_response}") messages.append( { "tool_call_id": tool_call.id, "role": "tool", "name": name, "content": function_response, } ) pprint(messages) function_enriched_response = client.chat( model=MODEL, messages=messages, ) pprint(function_enriched_response) Copy to clipboard ## Call multiple tools This is a tool calling example where multiple tools are listed in a `tools_map` for potential use by the LLM. import json import funcs from rich.pretty import pprint import imagine # -------------------------------------------------------------------------------------- client = imagine.ImagineClient(max_retries=1, debug=True) messages = [ { "role": "system", "content": "You are a helpful assistant that can access external functions. The responses from these function calls will be appended to this dialogue. Please provide responses based on the information from these function calls.", }, {"role": "user", "content": "Get the stock price of AAPL and GOOG"}, ] tools_map = funcs.get_tools_map( ["get_current_weather", "get_stock_price", "get_user_location", "get_random_city"] ) MODEL = "Llama-3.1-8B" # -------------------------------------------------------------------------------------- tools_spec = tools_map["__all__"]["schema"] response = client.chat( model=MODEL, messages=messages, tools=tools_spec, ) messages.append(response.choices[0].message) pprint(response, expand_all=True) tool_calls = response.choices[0].message.tool_calls if tool_calls: for tool_call in tool_calls: function_call = tool_call.function name = function_call.name arguments = json.loads(function_call.arguments) for function in tools_map["__all__"]["call"]: # type: ignore if function.__name__ == name: print(f"Invoking tool call: {name} with args :: {arguments}") function_response = function(**arguments) print(f"Result of invocation {function_response}") messages.append( { "tool_call_id": tool_call.id, "role": "tool", "name": name, "content": str(function_response), } ) pprint(messages) function_enriched_response = client.chat( model=MODEL, messages=messages, # type: ignore ) pprint(function_enriched_response) Copy to clipboard ## Call multiple tools recursively This example adds to the functionality of the previous example by looping through the tool calling until the model can provide a response. import json import funcs from loguru import logger from rich.pretty import pprint import imagine # -------------------------------------------------------------------------------------- client = imagine.ImagineClient(max_retries=1, debug=True) messages = [ { "role": "user", "content": "Get the user's location first. Get weather forecast at that location user's location. Call the functions one at a time sequentially without commenting or asking for confirmation", } ] tools_map = funcs.get_tools_map( ["get_weather_forecast", "get_user_location", "get_current_time"] ) MODEL = "Llama-3.1-8B" # -------------------------------------------------------------------------------------- tools_spec = tools_map["__all__"]["schema"] def run_inference(messages, tools): response = client.chat(model=MODEL, messages=messages, tools=tools, temperature=0.8) return response def recursive_tool_calling(): while True: response = run_inference(messages, tools_spec) assistant_message = response.choices[0].message messages.append(assistant_message) logger.debug(f"Assistant Message: {assistant_message}") if not assistant_message.tool_calls: break for tool_call in assistant_message.tool_calls: function_call = tool_call.function name = function_call.name arguments = json.loads(function_call.arguments) for function in tools_map["__all__"]["call"]: if function.__name__ == name: logger.debug(f"Invoking tool call: {name}") function_result = function(**arguments) logger.debug(f"Result of invocation {function_result}") if not isinstance(function_result, str): function_result = json.dumps(function_result) messages.append( { "name": name, "role": "tool", "content": function_result, "tool_call_id": tool_call.id, } ) logger.debug(f"Tool Call Result: {function_result}") break return messages messages = [ { "role": "user", "content": "Get the user's location first. Get weather forecast at that location user's location. Call the functions one at a time sequentially without commenting or asking for confirmation", } ] messages = recursive_tool_calling() pprint(messages) Copy to clipboard ## Next steps - [Connect to external functions using LangChain tools](https://docs.qualcomm.com/doc/80-88545-1/topic/3_1_langchain_tools.html). - Review how to [add guardrails to an LLM](https://docs.qualcomm.com/doc/80-88545-1/topic/guarded_llm_example.html). - [Create custom agents](https://docs.qualcomm.com/doc/80-88545-1/topic/autogen.html) with AutoGen. Last Published: Apr 17, 2026 [Previous Topic Basic usage](https://docs.qualcomm.com/bundle/publicresource/80-88545-1/topics/1_0_basic_usage.md) [Next Topic Use LangChain with the Qualcomm AI Inference Suite SDK](https://docs.qualcomm.com/bundle/publicresource/80-88545-1/topics/3_0_langchain.md)