Skip to main content

Tools

info

To see the basic usage of tools, refer to Using Tools page.

In Ailoy, a tool allows an agent to access functionality beyond what the base language model can offer, such as real-time data or domain-specific APIs.

How to add tools​

The following example shows how to explicitly define a REST API tool for Frankfurter API that provides real-time currency exchange rate information.

rt = Runtime()
agent = Agent(rt, model_name="Qwen/Qwen3-8B")

frankfurter = {
    "type": "restapi",
    "description": {
        "name": "frankfurter",
        "description": "Get the latest currency exchange rates of target currencies based on the 'base' currency",
        "parameters": {
            "type": "object",
            "properties": {
                "base": {
                    "type": "string",
                    "description": "The ISO 4217 currency code to be the divider of the currency rate to be got."
                },
                "symbols": {
                    "type": "string",
                    "description": "The target ISO 4217 currency codes separated by comma."
                }
            },
        }
    },
    "behavior": {
        "baseURL": "https://api.frankfurter.dev/v1/latest",
        "method": "GET",
        "headers": {
            "accept": "application/json"
        },
        "outputPath": "rates"
    },
}
agent.add_restapi_tool(frankfurter)

You can see that a tool is considered as a Tool Definition document in the code. And the explanation of it is continued below.

Tool Definition​

Each tool is defined using two components:

Description​

The description field defines how the AI understands and uses the tool. It follows the standard described in tool definitions of Transformers, which is the format widely used for defining tools in LLM. That is a JSON Schema explaining a function signature including details such as the tool's name, purpose, input parameters, return value and example usage. This helps the LLM decide when and how to use the tool.

Behavior​

The behavior field defines how the tool actually behaves when invoked. This varies depending on the tool type. For example, a REST API tool includes the endpoint URL, HTTP method, and headers. A native tool may define a Python or Node.js function, while a built-in tool delegates the behavior to a pre-defined module.

To see the examples of tools, take a look at the Out-of-the-box tools section.

Types​

There are three types of tools in Ailoy. While they all share a common description format, each type defines behavior differently.

REST API tools​

REST API tools allow the AI to access external APIs over HTTP. This is ideal for retrieving real-time or third-party information.

Behavior​

REST API tools basically send requests to get their results.

The behavior object of a REST API tool definition can contain:

  • URL(baseURL), HTTP method(method) and headers(headers) to define the REST API request to send.

  • Authentication method(authentication) to apply pre-defined authentication injection. If the API does not require authentication or needs custom one, the authentication field might not be contained.

  • Body content(body) to be the requests body of POST or PUT requests.

  • A JMESPath query string(outputPath) to process the raw results of the REST API into useful data.

The parameters that the LLM decided to put into the REST API tool can become:

  • Path parameters: Ones included as {param_name} in the baseUrl field
  • Body parameters: Ones included as {param_name} in the body field
  • Query parameters: Ones other than path parameters or body parameters

Tool definition for a REST API tool finally looks like:

{
  "type": "restapi",
  "description": {...},
  "behavior": {
    "baseURL": "https://api.themoviedb.org/3/movie/${movie_id}/recommendations",
    "method": "GET",
    "authentication": "bearer",
    "headers": {
      "accept": "application/json"
    },
    "outputPath": "results[:5].{id: id, title: title, overview: overview, original_language: original_language, genre_ids: genre_ids, release_date: release_date, vote_average: vote_average, adult:adult}"
  }
}

How to add your own tools​

You can make your Agent call any REST API you want by adding a REST API tool through:

  • agent.add_restapi_tool() (for Python)
  • agent.addRESTAPITool() (for Node.js).

These functions get a tool definition, and an authenticator optionally as their parameters.

  • Tool definition: Object including type, description, and behavior of the tool
  • Authenticator(optional): Callable object that injects authentication to the REST API calls
with Agent(...) as agent:
    bearer_api_key = ...;

    agent.add_restapi_tool(
        tool_def={...},      # Tool definition
        authenticator=BearerAuthenticator(bearer_api_key),
    )

Built-in tools​

Built-in tools uses the function of Ailoy’s internal module system. It work across all the environments supported. These tools are pre-registered and can be referenced by name.

Behavior​

Defined by preset behavior implemented inside Ailoy. The only thing defined outside of Ailoy is the JMESPath query string(outputPath) to process the raw results of the function into useful data.

Tool definition for a built-in tool looks like:

{
  "type": "builtin",
  "description": {...},
  "behavior": {
    "outputPath": "value"
  }
}

Built-in tools are not designed to be added at runtime.

Native tools​

Native tools allow developers to define custom Python functions that will be executed when the AI requests a tool call. This is useful for logic that lives inside your application.

Behavior​

A Python or Node.js function or coroutine that will be called with arguments from the AI.

How to add your own tools​

You can write your own tool as a native function and add it to the Agent through:

  • agent.add_py_function_tool() (for Python)
  • agent.addJsFunctionTool() (for Node.js).

These functions get a custom native function and its tool description as their parameters.

def a_useful_function_impl(arg0, arg1):
    a_useful_value = 0
    ...              # Your own codes
    return a_useful_value

with Agent(...) as agent:
    agent.add_py_function_tool(
        f=a_useful_function_impl,
        desc={...},  # Tool description, if you want to override
    )

In Python, the tool description can be automatically generated from the google-style docstring of the function.
In that case, you don't have to give the tool description as the parameter.
Even if your function have proper docstring, you can override the tool description by passing your own tool description as above.

Check this example code(Python) with the generated tool description(Json):

def get_current_temperature(location: str, unit: str):
    """
    Get the current temperature at a location.

    Args:
        location: The location to get the temperature for, in the format "City, Country"
        unit: The unit to return the temperature in. (choices: ["celsius", "fahrenheit"])
    Returns:
        The current temperature at the specified location in the specified units, as a float.
    """
    if unit == "celsius":
        return 25
    elif unit == "fahrenheit":
        return 77
    return

with Agent(...) as agent:
    agent.add_py_function_tool(get_current_temperature)  # Just pass the function!

Out-of-the-box tools​

These are the preset tools in Ailoy that you can use.

Calculator​

A calculator that evaluates a mathatical expression as a floating-point number.

The expression string can include floating-point numbers, arithmetic operators (+, -, *, /, %, ^), parentheses, and the mathematical constants and functions listed below.

For example,

  • "sqrt(3^2 + 4^2)" evaluates to 5.0
  • "6/2*(1+2)" evaluates to 9.0
  • "sin(pi/2)" evaluates to 1.0.

Mathematical Constants and Functions​

Behaviors of these are same as ones in cmath.

SymbolsDescriptions
e, piMathematical constants
abs(x), round(x), trunc(x), floor(x), ceil(x)Common value adjustment functions
sqrt(x), cbrt(x)Root of the value functions
ln(x), log(x), log10(x)Logarithms
sin(x), cos(x), tan(x)Trigonometric functions
asin(x), acos(x), atan(x), atan2(y,x)Inverse trigonometric functions
sinh(x), cosh(x), tanh(x)Hyperbolic functions
fac(n), ncr(n,r), npr(n,r)Combinatorial functions

Code to apply this tool​

with Agent(...) as agent:
    agent.add_tools_from_preset("calculator")
    agent.query("Evaluate sin(pi/2).")

Example message to use this tool​

Evaluate sin(pi/2).
I want to know the value of sqrt(3^2 + 4^2).
Calculate "6/2*(1+2)"

Frankfurter (Currency exchange rates)​

A public API provided by the European Central Bank that provides currency exchange rate information.

You can get exchange rates for one currency against another.

Code to apply this tool​

with Agent(...) as agent:
    agent.add_tools_from_preset("frankfurter")
    agent.query("I want to buy 100 U.S. Dollar with my Korean Won. How much do I need to take?")

Example message to use this tool​

I want to buy 100 U.S. Dollar with my Korean Won. How much do I need to take?
Please summarize the current exchange rate situation of major currencies.
I have 3000 yen, how much is this in USD?

TMDB​

The API provided by TMDB, the fully open source movie database service.

Tools​

  • tmdb_trending_movies: Get the trending movies on TMDB.
  • tmdb_movie_search: Search for movies by their original, translated and alternative titles.
  • tmdb_movie_reviews: Get the user reviews for a movie.
  • tmdb_movie_recommendations: Recommend movies based on the movie ID.
  • tmdb_movie_watch_providers: Get the list of streaming providers we have for a movie in some coutries.
  • tmdb_movie_genre_names: Get the list of genre names with their ids.

API key​

You can get a TMDB API key here: link

Code to apply this tool with API key​

tmdb_api_key = ...

with Agent(...) as agent:
    agent.add_tools_from_preset(
        "tmdb",
        authenticator=BearerAuthenticator(tmdb_api_key),
    )
    agent.query("Show me some famous movies recently.")

Example message to use this tool​

Show me some famous movies recently.
Can you find me every Iron Man movies?
Recommend me some movies similar to Inception of Christopher Nolan.

New York Times​

The API provided by New York Times, a famous American daily newspaper based in New York City.

Tools​

  • nytimes_article_search: Search New York Times articles by keyword

API key​

You can get a New York Times API key here: link

When you add tool to your agent, the API key can be provided. NY Times API requires to put API key in the query parameter, so you can add it to the query parameter as below.

This is an example of applying authentication in the way you want.

Code to apply this tool with API key​

nytimes_api_key = ...

with Agent(...) as agent:

    def nytimes_authenticator(request):
        from urllib.parse import parse_qsl, urlencode, urlparse

        parts = urlparse(request.get("url", ""))
        qs = {**dict(parse_qsl(parts.query)), "api_key": nytimes_api_key}
        parts = parts._replace(query=urlencode(qs))
        return {**request, "url": parts.geturl()}

    agent.add_tools_from_preset(
        "nytimes",
        authenticator=nytimes_authenticator,
    )
    for resp in agent.query("Find me some articles about 'Agentic AI'."):
        agent.print(resp)

Example message to use this tool​

Find me some articles about 'Agentic AI'.
News on financial market trends, please.
Search for the latest scientific research results.