Tools (also known as function calling) allow your AI agents to interact with external systems, APIs, and services, greatly expanding their capabilities beyond simple text generation.

​
Tool Configuration

Tools in LarAgent can be configured using these properties in your Agent class:

/** @var bool - Controls whether tools can be executed in parallel */
protected $parallelToolCalls;

/** @var array - List of tool classes to be registered with the agent */
protected $tools = [];

You can set $parallelToolCalls to null if you want to remove it from the request, as some models (o1) do not support parallel tool calls.

​
Creating Tools

There are three ways to create and register tools in your agent:

#[Tool] Attribute

Best for service-based or static tools specific to a single agent.

registerTools Method

Ideal for dynamically creating tools based on runtime conditions or user state.

Tool Classes

Perfect for complex tools that may be reused across multiple agents or require extensive logic.

​
1. Using the Tool Attribute

The simplest approach is using the #[Tool] attribute to transform your agent’s methods into tools:

use LarAgent\Attributes\Tool;

#[Tool('Get the current weather in a given location')]
public function weatherTool($location, $unit = 'celsius')
{
    return 'The weather in '.$location.' is '.'20'.' degrees '.$unit;
}

The agent will automatically register the tool with the given description and extract method information, including parameter names and types.

​
Using Enum Types with Tools

You can use PHP Enums to provide the AI with a specific set of options to choose from, as well as provide separate descriptions for each property (argument):

// app/Enums/Unit.php
namespace App\Enums;

enum Unit: string
{
    case CELSIUS = 'celsius';
    case FAHRENHEIT = 'fahrenheit';
}

// app/AiAgents/WeatherAgent.php
use LarAgent\Attributes\Tool;
use App\Enums\Unit;

// ...

#[Tool(
    'Get the current weather in a given location',
    [
        'unit' => 'Unit of temperature', 
        'location' => 'The city and state, e.g. San Francisco, CA'
    ]
)]
public static function weatherToolForNewYork(Unit $unit, $location = 'New York')
{
    return WeatherService::getWeather($location, $unit->value);
}

It’s recommended to use the #[Tool] attribute with static methods if there’s no need for the agent instance ($this).

​
2. Using the registerTools Method

This method allows you to programmatically create and register tools using the LarAgent\Tool class:

use LarAgent\Tool;

public function registerTools() 
{
    $user = auth()->user();
    return [
        Tool::create("user_location", "Returns user's current location")
             ->setCallback(function () use ($user) {
                  return $user->location()->city;
             }),
        Tool::create("get_current_weather", "Returns the current weather in a given location")
             ->addProperty("location", "string", "The city and state, e.g. San Francisco, CA")
             ->setCallback("getWeather"),
    ];
}

setCallback method accepts any php callable, such as a function name, a closure, or a class method.

​
3. Using Tool Classes

For complex tools, you can create dedicated tool classes and add them to the $tools property:

protected $tools = [
    WeatherTool::class,
    LocationTool::class
];

​
Example Tool Class

Tool creation artisan command is comming soon…

class WeatherTool extends LarAgent\Tool
{
    protected string $name = 'get_current_weather';

    protected string $description = 'Get the current weather in a given location';

    protected array $properties = [
        'location' => [
            'type' => 'string',
            'description' => 'The city and state, e.g. San Francisco, CA',
        ],
        'unit' => [
            'type' => 'string',
            'description' => 'The unit of temperature',
            'enum' => ['celsius', 'fahrenheit'],
        ],
    ];

    protected array $required = ['location'];

    protected array $metaData = ['sent_at' => '2024-01-01'];

    public function execute(array $input): mixed
    {
        // Call the weather API
        return 'The weather in '.$input['location'].' is '.rand(10, 60).' degrees '.$input['unit'];
    }
}

​
Chainable Tool Methods

You can dynamically add or remove tools during runtime using these methods:

// Add a tool for this specific call
$agent->withTool(new WeatherTool());

// Remove a tool for this specific call (use tool name or getName() method)
$agent->removeTool('get_current_weather');

​
Best Practices

Do create separate tool classes for complex functionality that might be reused

Do provide clear, descriptive names and parameter descriptions

Do use Enums when you need to restrict the AI to specific options

Don’t create tools with ambiguous functionality or unclear parameter requirements

Don’t expose sensitive operations without proper validation and security checks