Tools & Function Calls

Give Agents the ability to interact with your application context and services.

Tools enable LLMs to go beyond generating text by facilitating interaction with your application services, or external APIs.

Think of Tools as special functions that your AI agent can use when it needs to perform specific tasks. They let you extend your Agent's capabilities by giving it access to specific functions it can call.

In the SEO agent we are implementing, we need to retrieve the content of the article we want to analyze, and pass it as a message to the agent.

Instead, we can make a tool available to our assistant and let it free to decide if it's the case to use the tool to grab relevant information he need to complete the task:

Let me show how it works:

use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class SEOAgent extends Agent
{
    public function __construct(
        protected object $user
    ) {}

    public function provider(): AIProviderInterface
    {
        // return an AI provider instance (Anthropic, OpenAI, Mistral, etc.)
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    public function instructions() 
    {
        return "Act as an expert of SEO (Search Engine Optimization) specialized in the {$this->user->industry} industry. ".
            "Your role is to analyze a text and provide suggestions on how the content can be improved to be SEO relevant for the specified market sector.";
    }
    
    public function tools(): array
    {
        return [
            Tool::make(
                "get_file_content", 
                "Use the url to get the content in plain text."
            )->addProperty(
                new ToolProperty(
                    name: 'url',
                    type: 'string',
                    description: 'The URL of the article you want to analyze.',
                    required: true
                )
            )->setCallable(function (string $url) {
                return file_get_contents($url);
            })
        ];
    }
}

OK! Now we provided the agent with a tool to make it able to retrieve the content of the file if it think it's needed.

Since we incapsulated this feature into the agent the interaction can be simplified:

use NeuronAI\Chat\Messages\UserMessage;

$response = SEOAgent::make($user)
    ->chat(
        new UserMessage('What do you think about this article? https://www.website.com/article')
    );
    
echo $response->getContent();

// It seems like a good job has been done on the article, 
// however I can give you some tips to improve SEO:...

How it works

Let me explain how it works behind the scenes.

Function detection and selection

The LLM processes the input message and determines if a function call is necessary. If so, it identifies the correct function from the provided list (tools) and generates a JSON dictionary that includes the selected function's name and the required input arguments:

{
    "function": "get_file_content", 
    "url": "https://inspector.dev/article"
}

Execution

Neuron AI Agent parses the JSON response and invokes the identified function of the tool you provide, either sequentially, or in parallel, with other functions, depending on the requirements.

After executing the function(s) and retrieving the required data, the output is fed back into the LLM. The LLM then integrates this information into its response, generating a message that’s not only more accurate – because it’s based on the data provided by the external function – but also freer of hallucinations.

Extend the Framework

Thanks to the Neuron AI modular architecture, Tools are just a component of the toolkit that rely on the ToolInterface interface. So you are free to create pre-packaged tool classes that implements common functionalities, and release them as external composer packages or submit a PR to our repository to have them integrated into the core toolkit.

Once you identify a common use case, pre-packaged Tools can internally define the execute method, the properties needed by the callback, description, etc.

To create a new Tool you must implement the following interface. Also take a look at the default Tool class to get some inspiration.

namespace NeuronAI\Tools;

interface ToolInterface extends \JsonSerializable
{
    /**
     * Get the unique name of the tool.
     */
    public function getName(): string;

    /**
     * Get a description of the tool's functionality.
     */
    public function getDescription(): string;

    /**
     * Add a Property with a name, type, description, and optional required constraint.
     */
    public function addProperty(ToolProperty $property): self;
    public function getProperties(): array;

    /**
     * Array of names of the required properties.
     *
     * @return array<string>
     */
    public function getRequiredProperties(): array;

    /**
     * Define the code to be executed.
     *
     * @param callable $callback
     * @return mixed
     */
    public function setCallable(callable $callback): self;

    /**
     * Get the input arguments of the function call.
     */
    public function getInputs(): array;
    public function setInputs(array $inputs): self;

    /**
     * The call identifier generated by the LLM.
     * @return string
     */
    public function getCallId(): string;
    public function setCallId(string $callId): self;


    public function getResult(): mixed;

    /**
     * Execute the tool's logic with input parameters.
     */
    public function execute(): void;
}