Skip to content

Tool Use Agent

The ToolUseAgent is a built-in utility agent in the AI Refinery SDK designed to interact with external tools to perform specific tasks as instructed by the user. It selects predefined tools to execute commands and provide results seamlessly. For instance, if asked "Generate a random password of length 16.", the ToolUseAgent will:

  • Select the appropriate tool(s) needed for the task,
  • Execute the tool with the necessary parameters,
  • Retrieve and present the results to the user.

This documentation outlines the workflow and configurations needed to use the ToolUseAgent.

Workflow Overview

The workflow of the ToolUseAgent consists of six components:

  1. Initialization:

    • The agent is initialized with the provided configuration.
    • Built-in and custom tools are loaded based on the configuration.
    • If add_interpreter is true, an instance of the Interpreter Agent is also initialized.

  2. Receiving a Query:

    • The agent receives a user query through the run method.
    • The query is processed to determine if it requires a function call.

  3. Determining Function Calls:

    • The agent uses the LLM to analyze the query and decide whether to call a function.
    • If no function call is needed, the LLM's response is returned directly to the user.

  4. Executing Functions:

    • If a function call is required, the agent extracts the function name and arguments.
    • Built-in Functions:
      • The agent verifies if the function is a built-in tool.
      • If so, it calls the function directly with the extracted arguments.
      • Currently, only calculate_expression is provided. We will provide more in the future.
    • Custom Functions:
      • For custom tools, the agent utilizes the custom_agent_gallery mapping.
      • The agent sends a request to the appropriate custom agent or function.
      • It waits for the response within the specified wait_time.
      • You can find a tutorial on how to create custom functions here.

  5. Processing Output:

    • If add_interpreter is enabled, the Interpreter Agent processes the function output to generate a user-friendly response.
    • If not, the raw function output is returned.

  6. Returning Response:

    • The agent constructs a Message object with the response content.
    • The response is returned to the user.

Usage

As a built-in utility agent in the AI Refinery SDK, ToolUseAgent can be easily integrated into your project by adding the necessary configurations to your project YAML file. Specifically, ensure the following configurations are included:

  • Add a utility agent with agent_class: ToolUseAgent under utility_agents.
  • Ensure the agent_name you chose for your ToolUseAgent is listed in the agent_list under orchestrator.

Quickstart

To quickly set up a project with a ToolUseAgent, use the following YAML configuration. This setup includes one built-in tool (calculate_expression) and a custom tool (generate_password). You can add more tools as needed. Refer to the next section for a detailed overview of configurable options for the ToolUseAgent. For detailed instructions on creating custom functions, see the tutorial.

utility_agents:  
  - agent_class: ToolUseAgent  
    agent_name: "Tool Use Agent"  # A name that you choose for your ToolUseAgent. This needs to be listed under orchestrator.  
    agent_description: "An agent that performs function calling using provided tools."  
    config:  
      wait_time: 120  # Optional: Maximum time (in seconds) the agent will wait for tool execution.  
      enable_interpreter: true  # Optional: Enable the use of an interpreter for code execution.  
      builtin_tools:  
        - "calculate_expression"  # Use the built-in tool for calculating mathematical expressions.  
      custom_tools:
        - |
          {
            "type": "function",  # Indicates that this is a function tool; it could only be "function"
            "function": {
              "name": "generate_password",  # Name of the function
              "description": "Generate a random password of specified length.",  # What the function does
              "parameters": {
                "type": "object",  # Parameters are defined as an object
                "properties": {
                  "length": {
                    "type": "integer",  # Data type of 'length' parameter
                    "description": "Length of the password to generate. Default is 12.",  # Explanation of 'length'
                    "default": 12  # Default value if 'length' is not provided
                  }
                },
                "required": []  # No required parameters; 'length' is optional
              }
            }
          }


orchestrator:  
  agent_list:  
    - agent_name: "Tool Use Agent"  # The name you chose for your ToolUseAgent above.

In this configuration:

  • builtin_tools includes "calculate_expression", a built-in tool for evaluating mathematical expressions.
  • custom_tools includes two custom tools defined in JSON format.
  • generate_password: Generates a random password of specified length.
  • convert_temperature: Converts temperatures between Celsius and Fahrenheit.

Template YAML Configuration of ToolUseAgent

In addition to the configurations mentioned in the example above, the ToolUseAgent supports several other configurable options. See the template YAML configuration below for all available settings. 

agent_class: ToolUseAgent  
agent_name: <name of the agent>  # A name that you choose for your ToolUseAgent  
agent_description: <description of the agent>  # Optional  
config:  
  wait_time: <seconds>  # Optional: Maximum time (in seconds) the agent will wait for tool execution.  
  enable_interpreter: <true or false>  # Optional: Enable or disable the use of an interpreter for code execution.  

  builtin_tools:  
    - <builtin_tool_name>  # Currently, only 'calculate_expression' is provided.

  custom_tools:  
    - |  
      <custom_tool_json_definition>  
    # Add more custom tools as needed.