Herramientas y kits de herramientas

Dale a los agentes la capacidad de interactuar con el contexto y los servicios de tu aplicación.

El ciclo principal del agente consiste en llamar a un modelo, permitirle elegir qué herramientas ejecutar y luego finalizar cuando ya no se necesitan más herramientas para proporcionar una respuesta:

Qué es una herramienta

Las herramientas permiten a los Agentes ir más allá de generar texto al facilitar la interacción con los servicios de tu aplicación o con APIs externas.

Piensa en las herramientas como funciones especiales que tu agente de IA puede usar cuando necesita realizar tareas específicas. Le permiten ampliar las capacidades de tu Agente dándole acceso a funciones concretas que puede invocar dentro de tu código.

En el YouTubeAgent ejemplo podemos definir una herramienta para hacer que el Agente pueda recuperar la transcripción del video de YouTube, para así crear un resumen breve:

namespace App\Neuron;

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

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // devuelve una instancia de un proveedor de IA (Anthropic, OpenAI, Ollama, Gemini, etc.)
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    protected function instructions(): string 
    {
        return (string) new SystemPrompt(
            background: ["Eres un Agente de IA especializado en escribir resúmenes de videos de YouTube."],
            steps: [
                "Obtén la URL de un video de YouTube, o pide al usuario que proporcione una.",
                "Usa las herramientas que tienes disponibles para recuperar la transcripción del video.",
                "Escribe el resumen.",
            ],
            output: [
                "Escribe un resumen en un párrafo sin usar listas. Usa solo texto fluido.",
                "Después del resumen añade una lista de tres frases como las tres conclusiones más importantes del video.",
            ]
        );
    }
    
    protected function tools(): array
    {
        return [
            Tool::make(
                'get_transcription',
                'Recuperar la transcripción de un video de YouTube.',
             )->addProperty(
                new ToolProperty(
                    name: 'video_url',
                    type: PropertyType::STRING,
                    description: 'La URL del video de YouTube.',
                    required: true
                )
             )->setCallable(function (string $video_url) {
                return "Transcripción del video...";
            })
        ];
    }
}

Desglosemos el código.

Introdujimos el nuevo método tools() en la clase Agent. Se espera que este método devuelva un array de objetos Tool que la IA podrá usar si es necesario.

En este ejemplo devolvemos un array de solo una herramienta, llamada get_transcription.

Observa que la ToolProperty que definimos debe coincidir con la firma de la función que uses como callable. La callable recibe los argumentos $video_url y el nombre de la propiedad es exactamente "video_url".

Lo más importante son el nombre y la descripción que le das a la herramienta y a sus propiedades. Toda esta información se enviará al LLM en lenguaje natural. Cuanto más explícito y claro seas, más probable será que el LLM entienda cuándo, si y por qué conviene usar la herramienta.

Una vez que el Agente decide usar una herramienta, se ejecuta la función callable. Aquí podemos implementar la lógica para recuperar la transcripción del video y devolver la información al LLM.

Neuron te ofrece estas APIs claras y sencillas y automatiza todas las interacciones subyacentes con el LLM. Una vez que entiendes el concepto, inmediatamente se abre la posibilidad de conectar prácticamente cualquier cosa que quieras al Agente. Poder ejecutar funciones locales te permite invocar cualquier API externa o componente de la aplicación.

Herramientas personalizadas

Gracias a la arquitectura modular de Neuron, las herramientas son componentes que implementan ToolInterface . Eres libre de crear clases de herramientas empaquetadas previamente para que el agente pueda realizar acciones específicas, y publicarlas como paquetes composer externos o enviar un PR a nuestro repositorio para que se integren en el framework principal.

Para crear una nueva herramienta ejecuta el siguiente comando de consola:

Unix

vendor/bin/neuron make:tool App\\Neuron\\GetTranscriptionTool

Windows

.\vendor\bin\neuron make:tool App\Neuron\GetTranscriptionTool

Puedes personalizar la estructura de la herramienta con el siguiente código:

<?php

namespace App\Neuron\Tools;

use GuzzleHttp\Client;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class GetTranscriptionTool extends Tool
{
    protected Client $client;
    
    public function __construct(protected string $key)
    {
        // Define el nombre y la descripción de la herramienta
        parent::__construct(
            'get_transcription',
            'Recuperar la transcripción de un video de YouTube.',
        );
    }
    
    /**
     * Devuelve la lista de propiedades.
     */
    protected function properties(): array
    {
        return [
            new ToolProperty(
                name: 'video_url',
                type: PropertyType::STRING,
                description: 'La URL del video de YouTube.',
                required: true
            )
        ];
    }
    
    /**
     * Implementa la lógica de la herramienta
     */
    public function __invoke(string $video_url): string
    {
        $response = $this->getClient()
            ->get('transcript?url=' . $video_url.'&text=true')
            ->getBody()
            ->getContents();

        $response = json_decode($response, true);

        return $response['content'];
    }
    
    protected function getClient(): Client
    {
        return $this->client ??= new Client([
            'base_uri' => 'https://api.supadata.ai/v1/youtube/',
            'headers' => [
                'x-api-key' => $this->key,
            ]
        ]);
    }
}

Nombre y descripción de la herramienta: Define el nombre y la descripción de la herramienta en el constructor de la herramienta. Invierte en ingeniería de prompts para ayudar al modelo a tomar mejores decisiones.

El método properties: Implementa este método para devolver la lista de propiedades que espera la herramienta.

El __invoke método: Aquí necesitas implementar la lógica de la herramienta y devolver un resultado que será enviado de vuelta al modelo. El método mágico de PHP __invoke se usa por defecto.

Observa cómo el __invoke() método acepta los mismos argumentos definidos por la ToolProperty . En este ejemplo estoy usando un servicio externo para recuperar la transcripción del video de YouTube llamado Supadata.ai.

Puedes adjuntar la herramienta en la clase del agente como de costumbre:

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;
use App\Neuron\Tools\GetTranscriptionTool;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {...}
    
    protected function instructions(): string
    {...}
    
    protected function tools(): array
    {
        return [
            GetTranscriptionTool::make('API_KEY'),
        ];
    }
}

GetTranscriptions es solo un ejemplo. Eventualmente puedes implementar otras herramientas para hacer que el Agente pueda recuperar otros metadatos del video y mejorar sus capacidades de análisis de video.

Finalmente puedes hablar con el agente pidiéndole el resumen de un video de YouTube.

use NeuronAI\Chat\Messages\UserMessage;

$message = YouTubeAgent::make($user)->chat(
    new UserMessage('¿Qué pasa con este video: https://www.youtube.com/watch?v=WmVLcj-XKnM')
)->getMessage();
    
echo $message->getContent();

/**

Basándome en la transcripción, proporcionaré un resumen de este potente mensaje 
ambiental de "Madre Naturaleza":
Este video presenta ...

Tres conclusiones más importantes:

1. La naturaleza ha existido ...

2. El bienestar de la humanidad es ...

3. Cómo los humanos eligen actuar hacia la Naturaleza determina ...

*/

Máximo de ejecuciones

Los agentes cuentan con un mecanismo de seguridad que rastrea el número de veces que se invoca una herramienta durante una sesión de ejecución. Si el agente supera este límite, la ejecución se interrumpe y se lanza ToolRunsExceededException . Por defecto el límite es de 10 llamadas, y se cuenta para cada herramienta de forma individual.

Puedes personalizar este valor con el método toolMaxRuns() a nivel de agente, o usar setMaxRuns() a nivel de la herramienta. Establecer el máximo de intentos en una sola herramienta tiene prioridad sobre la configuración global.

try {

    $response = YouTubeAgent::make()
        ->toolMaxRuns(5) // Número máximo de llamadas para cada herramienta
        ->addTool(
            // La configuración a nivel de herramienta tiene prioridad sobre la configuración global
            CustomTool::make()->setMaxRuns(2)
        )
        ->chat(...)
        ->getMessage();
        
} catch (ToolMaxTriesException $exception) {
    // hacer algo
}

Visibilidad

Puedes condicionar la disponibilidad de las herramientas según reglas personalizadas. La clase Tool te proporciona el método visible para determinar si el agente debería siquiera saber que esta herramienta existe:

class YouTubeAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            GetTranscriptionTool::make('API_KEY')->visible(
                auth()->user()->can(...)
            ),
        ];
    }
}

Si el visible método devuelve false, la herramienta no estará disponible durante la ejecución del agente.

Aprobación de herramientas

Neuron te ofrece compatibilidad total con el patrón human in the loop, incluida la aprobación de herramientas. Es diferente de la visibilidad porque la "aprobación" es un guardián en tiempo de ejecución. El framework intercepta la llamada a la herramienta y pausa esperando la decisión final del usuario.

Puedes integrar esta función en tu agente con nuestro ToolApproval middleware incorporado.

new ToolApproval(
    tools: [
        BuyTicketTool::class => function (array $args): bool {
            return $args['amount'] > 100;
        }
    ]
)

Middleware

Búsqueda de herramientas

Por defecto, cada vez que se invoca al proveedor, todas las herramientas se cargan y se transmiten al LLM de backend. Un agente de producción complejo conectado a correo, calendario, drive, CRM y varios servidores MCP puede alcanzar fácilmente cientos de herramientas, cada una con su nombre, descripción, esquema de parámetros y sugerencias de uso.

La búsqueda de herramientas replantea el catálogo de herramientas como algo que el agente consulta bajo demanda en lugar de algo que lleva en cada solicitud.

Middleware

Supervisión y depuración

Para ver el interior del ciclo de herramientas puedes conectar tu Agente al panel de supervisión Inspector para ver en tiempo real el flujo de ejecución de las llamadas a herramientas.

Neuron AI | Inspectordocs.inspector.dev

Propiedades de la herramienta

Neuron te permite definir el formato de los datos que quieres recibir en la función de la herramienta. Puedes anidar estos objetos unos dentro de otros para definir estructuras de datos complejas.

ToolProperty

Esta clase representa un valor escalar simple como una cadena, un entero o un booleano.

namespace App\Neuron\Tools;

use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ToolProperty(
                name: 'arg',
                type: PropertyType::STRING,
                description: 'Describe el valor que esperas',
                required: true,
                nullable: false
            )
        ];
    }
    
    public function __invoke(string $arg){...}
}

ArrayProperty

El ArrayProperty te permite requerir una lista de elementos con características específicas.

Usa el argumento items para especificar el tipo de dato de los elementos del array. En el ejemplo siguiente pedimos un array de cadenas.

namespace App\Neuron\Tools;

use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ArrayProperty;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ArrayProperty(
                name: 'prop_array',
                description: 'Describe el valor que esperas',
                required: true,
                items: new ToolProperty(
                    name: 'prop',
                    type: PropertyType::STRING,
                    description: 'Describe el valor que esperas',
                    required: true
                )
            )
        ];
    }
    
    public function __invoke(string $arg){...}
}

Límites máximos y mínimos

ArrayProperty también te permite definir limitaciones sobre el tamaño del array esperado usando los argumentos minItems y maxItems .

$property = new ArrayProperty(
    name: "tags",
    description: "Lista de etiquetas asociadas con el elemento",
    required: true,
    items: new ToolProperty(
        name: "tag",
        type: PropertyType::STRING,
        description: "Una sola etiqueta",
        required: true
    ),
    minItems: 1,
    maxItems: 10
);

ObjectProperty

De forma similar al ejemplo anterior del array, puedes definir una estructura de datos de objeto:

namespace App\Neuron\Tools;

use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ObjectProperty;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ObjectProperty(
                name: 'colors',
                description: 'Color RGB',
                required: true,
                properties: [
                    new ToolProperty(
                        name: 'r',
                        type: PropertyType::NUMBER,
                        description: 'La parte roja del RGB',
                        required: true
                    ),
                    new ToolProperty(
                        name: 'g',
                        type: PropertyType::NUMBER,
                        description: 'La parte verde del RGB',
                        required: true
                    ),
                    new ToolProperty(
                        name: 'b',
                        type: PropertyType::NUMBER,
                        description: 'La parte azul del RGB',
                        required: true
                    )
                ]
            )
        ];
    }
    
    public function __invoke(string $arg){...}
}

Entrada estructurada de la herramienta

Si el objeto que quieres tiene muchas propiedades, puedes pasar una clase PHP estructurada a ObjectProperty en lugar de definir el esquema manualmente. Neuron te proporcionará una instancia de esta clase como argumento de entrada de la función de la herramienta:

namespace App\Neuron\Tools;

use App\Neuron\Dto\Color;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ObjectProperty(
                name: 'color',
                description: 'Combinación de colores',
                required: true,
                class: Color::class
            )
        ];
    }
    
    public function __invoke(Color $color){...}
}

Así es como se ve la clase Colors:

<?php

namespace App\Neuron\Dto;

use NeuronAI\StructuredOutput\SchemaProperty;

class Color
{
    #[SchemaProperty(description: "La parte ROJA del RGB", required: true)]
    public float $r;
    
    #[SchemaProperty(description: "La parte VERDE del RGB", required: true)]
    public float $g;
    
    #[SchemaProperty(description: "La parte AZUL del RGB", required: true)]
    public float $b;
}

Herramientas del proveedor

Algunos proveedores ofrecen la posibilidad de usar sus herramientas integradas como web_search, file_search y otras en lugar de depender de servicios externos. Incluso cuando ofrecen este servicio, introducen muchas restricciones al usar estas herramientas. La forma más flexible y fiable de añadir capacidades a tus agentes sigue siendo los sistemas Tools y Toolkit.

Puedes añadir una herramienta del proveedor como de costumbre en el array de herramientas de tu agente:

use NeuronAI\Tools\ProviderTool;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAIResponses(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL',
        );
    }

    protected function tools(): array
    {
        return [
            ProviderTool::make(
                type: 'web_search'
             )->setOptions([...]),
        ];
    }
}

Actualmente solo OpenAIResponses, Gemini, y Anthropic admiten estas herramientas.

Toolkits

La filosofía detrás del sistema de toolkits de Neuron surgió de una observación fundamental durante el desarrollo de agentes de IA: aunque las herramientas individuales ofrecen capacidades específicas, los agentes de IA del mundo real a menudo requieren conjuntos coordinados de funcionalidades relacionadas.

En lugar de obligar a los desarrolladores a ensamblar manualmente colecciones de herramientas para casos de uso comunes, Neuron introduce los toolkits como una capa de abstracción que transforma cómo pensamos en la composición de capacidades de los agentes. Aquí tienes un ejemplo de cómo puedes añadir un toolkit a un agente:

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Calculator\CalculatorToolkit;

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}

El enfoque tradicional requiere instanciar cada herramienta individualmente. Imagina que quieres construir agentes que necesiten razonamiento matemático: las herramientas de suma, resta, multiplicación, división y exponenciación deben declararse todas por separado en la configuración de herramientas del agente. Este enfoque granular se vuelve rápidamente inmanejable cuando los agentes requieren conjuntos de funcionalidades completos.

Los toolkits representan la solución de Neuron a esta complejidad, empaquetando herramientas creadas alrededor del mismo ámbito en una sola interfaz coherente que puede adjuntarse a cualquier agente con una sola línea de código.

Aquí tienes un ejemplo de CalculatorToolkit:

namespace NeuronAI\Tools\Toolkits\Calculator;

use NeuronAI\Tools\Toolkits\AbstractToolkit;

class CalculatorToolkit extends AbstractToolkit
{
    public function guidelines(): ?string
    {
        return "Este toolkit te permite realizar operaciones matemáticas. También puedes usar estas funciones para resolver
        expresiones matemáticas ejecutando operaciones más pequeñas paso a paso para calcular el resultado final.";
    }

    public function provide(): array
    {
        return [
            SumTool::make(),
            SubtractTool::make(),
            MultiplyTool::make(),
            DivideTool::make(),
            ExponentiateTool::make(),
        ];
    }
}

El AbstractToolkit la clase base establece una interfaz coherente que todos los toolkits heredan, garantizando un comportamiento predecible en todo el framework.

Directrices

El guidelines() método cumple una función especialmente importante en el desarrollo de agentes: proporciona información contextual que ayuda al modelo de lenguaje subyacente a entender no solo qué herramientas están disponibles, sino cómo deben usarse en conjunto. En el caso de CalculatorToolkit, las directrices sugieren explícitamente que las expresiones matemáticas complejas pueden resolverse mediante operaciones paso a paso, guiando al agente hacia estrategias eficaces de resolución de problemas.

Proporcionar

El provide() método devuelve el array de herramientas incluidas en el toolkit por defecto. Cuando un toolkit se adjunta a un agente, las herramientas individuales quedan disponibles exactamente como si se hubieran añadido por separado, pero sin la sobrecarga cognitiva de gestionar múltiples declaraciones de herramientas.

Filtros

Durante el desarrollo de agentes complejos, con frecuencia me he encontrado con escenarios en los que un toolkit proporciona en su mayoría la funcionalidad correcta pero incluye herramientas que podrían llevar a comportamientos no deseados en contextos específicos, o que simplemente necesitan restringirse y configurarse individualmente.

Excluir

El exclude() método aborda este desafío con elegancia, permitiendo a los desarrolladores adjuntar toolkits completos mientras mantienen un control detallado sobre las capacidades disponibles. Esto resulta especialmente útil cuando trabajas con agentes especializados que necesitan capacidades concretas, pero quieres reducir la probabilidad de un error del agente y disminuir el consumo de tokens.

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
    	return [
            CalculatorToolkit::make()->exclude([
                DivideTool::class,
                ExponentiateTool::class,
                MultiplyTool::class,
            ]),
        ];
    }
}

El mecanismo de exclusión opera a nivel de clase, utilizando nombres de clase completamente calificados para identificar las herramientas que deben eliminarse.

Solo

De la misma forma también puedes usar el método only() para solicitar un subconjunto de las herramientas disponibles en el toolkit.

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
    	return [
            CalculatorToolkit::make()->only([
                StandardDeviationTool::class,
                MedianTool::class,
            ]),
        ];
    }
}

Con

Siguiendo el mismo patrón, puede que necesites recuperar una instancia de una herramienta específica del toolkit para cambiar su configuración. Puedes hacerlo usando el with() método. Puede pasar el nombre completo de la clase para declarar qué herramienta desea recuperar, y la instancia de la herramienta se inyectará en el callback para que pueda cambiar su configuración y devolverla.

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
    	return [
            MySQLToolkit::make()
                ->with(
                    MySQLSchemaTool::class, 
                    fn (ToolInterface $tool) => $tool->setMaxTries(1)
                ),
        ];
    }
}

Desde la perspectiva de la extensibilidad, el sistema de toolkits abre oportunidades extraordinarias para la contribución de la comunidad y el crecimiento del ecosistema. La interfaz coherente significa que los desarrolladores externos pueden crear toolkits específicos de dominio que se integren sin problemas con la arquitectura de Neuron. Un desarrollador que construya agentes para aplicaciones financieras podría crear un FinancialToolkit que incluya herramientas para conversión de divisas, cálculo de intereses y evaluación de riesgos. Del mismo modo, un WebScrapingToolkit podría empaquetar herramientas de solicitudes HTTP, capacidades de análisis de HTML y utilidades de extracción de datos en un único componente reutilizable.

Toolkits disponibles

Neuron incluye varias herramientas y toolkits integrados que le permiten equipar rápidamente a sus agentes con muchas capacidades. Puede usar estas herramientas individualmente o adjuntar toolkits completos con una sola línea de código.

Calculadora

El CalculatorToolkit proporciona un conjunto completo de herramientas de cálculo diseñadas para hacer que sus agentes de IA realicen cálculos precisos. Puede integrarse sin problemas con toolkits complementarios que proporcionan acceso a datos —como conectores de bases de datos, procesadores CSV, clientes API o lectores de hojas de cálculo—, lo que permite a los agentes de IA realizar cálculos estadísticos sofisticados y ofrecer información completa en respuesta a consultas empresariales complejas.

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Calculator\CalculatorToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}

suma	NeuronAI\Tools\Toolkits\Calculator\SumTool
restar	NeuronAI\Tools\Toolkits\Calculator\SubtractTool
multiplicar	NeuronAI\Tools\Toolkits\Calculator\MultiplyTool
dividir	NeuronAI\Tools\Toolkits\Calculator\DivideTool
exponencial	NeuronAI\Tools\Toolkits\Calculator\ExponentialTool
raíz cuadrada	NeuronAI\Tools\Toolkits\Calculator\SquareRootTool
raíz n-ésima	NeuronAI\Tools\Toolkits\Calculator\NthRootTool
media	NeuronAI\Tools\Toolkits\Calculator\MeanTool
mediana	NeuronAI\Tools\Toolkits\Calculator\MedianTool
moda	NeuronAI\Tools\Toolkits\Calculator\ModeTool
desviación estándar	NeuronAI\Tools\Toolkits\Calculator\StandardDeviationTool
varianza	NeuronAI\Tools\Toolkits\Calculator\VarianceTool

Calendario

Este toolkit proporciona operaciones completas de fecha y hora. Use estas herramientas para que su agente pueda trabajar con fechas, horas, formato, cálculos y conversiones de zona horaria.

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\CalendarToolkit\CalendarToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            CalendarToolkit::make(),
        ];
    }
}

current_datetime	NeuronAI\Tools\Toolkits\Calendar\CurrentDateTimeTool
get_timestamp	NeuronAI\Tools\Toolkits\Calendar\GetTimestampTool
format_date	NeuronAI\Tools\Toolkits\Calendar\FormatDateTool
date_difference	NeuronAI\Tools\Toolkits\Calendar\DateDifferenceTool
add_time	NeuronAI\Tools\Toolkits\Calendar\AddTimeTool
subtract_time	NeuronAI\Tools\Toolkits\Calendar\SubtractTimeTool
calculate_age	NeuronAI\Tools\Toolkits\Calendar\CalculateAgeTool
convert_timezone	NeuronAI\Tools\Toolkits\Calendar\ConvertTimezoneTool
get_timezone_info	NeuronAI\Tools\Toolkits\Calendar\GetTimezoneInfoTool
get_weekday	NeuronAI\Tools\Toolkits\Calendar\GetWeekdayTool
is_weekend	NeuronAI\Tools\Toolkits\Calendar\IsWeekendTool
is_leap_year	NeuronAI\Tools\Toolkits\Calendar\IsLeapYearTool
get_days_in_month	NeuronAI\Tools\Toolkits\Calendar\GetDaysInMonthTool
start_of_period	NeuronAI\Tools\Toolkits\Calendar\StartOfPeriodTool
end_of_period	NeuronAI\Tools\Toolkits\Calendar\EndOfPeriodTool
get_week_number	NeuronAI\Tools\Toolkits\Calendar\GetWeekNumberTool
compare_dates	NeuronAI\Tools\Toolkits\Calendar\CompareDatesTool
is_date_in_range	NeuronAI\Tools\Toolkits\Calendar\IsDateInRangeTool

MySQL y PostgreSQL

Estos toolkits permiten que su agente interactúe con su base de datos. Si pregunta "¿Cuántos votos obtuvieron los autores en los últimos 14 días?", el agente no adivina ni alucina una respuesta. En su lugar, reconoce que esta pregunta requiere acceso a la base de datos, identifica las tablas apropiadas involucradas y recupera datos reales de su sistema.

Todas las herramientas de los toolkits de MySQL y PostgreSQL requieren una PDO instancia como argumento del constructor. Si se encuentra en un entorno de framework o ya está usando un ORM en general, puede obtener la instancia PDO subyacente del ORM y pasarla a las herramientas. Puede aprender más sobre esta estrategia de implementación en este artículo detallado: https://inspector.dev/mysql-ai-toolkit-bringing-intelligence-to-your-database-layer-in-php/

La instancia PDO es básicamente una conexión a una base de datos específica, así que también podría pensar en crear credenciales dedicadas para su agente. Podría ser útil controlar el nivel de acceso que su agente tiene a la base de datos.

En cualquier caso, tiene herramientas separadas para leer y escribir en la base de datos. Si no está seguro del comportamiento de su agente, puede no proporcionar la herramienta de escritura.

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;
use NeuronAI\Tools\Toolkits\MySQL\PGSQLToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            // Conectar a una base de datos MySQL
            MySQLToolkit::make(
                new \PDO("mysql:host=localhost;dbname=DB_NAME;charset=utf8mb4", "DB_USER", "DB_PASS"),
            ),
            
            // o base de datos PostgreSQL
            PGSQLToolkit::make(
                new \PDO("pgsql:host=localhost;dbname=DB_NAME;charset=utf8mb4", "DB_USER", "DB_PASS"),
            ),
        ];
    }
}

Estos ejemplos se refieren a la MySQLToolkit pero es exactamente lo mismo usando PGSQLToolkit.

MySQLSchemaTool / PGSQLSchemaTool

Esta herramienta permite a los agentes comprender la estructura de su base de datos, lo que les permite construir consultas inteligentes sin que usted tenga que codificar manualmente las estructuras de las tablas o sus relaciones en los prompts. Esta herramienta, en esencia, le da a su agente el equivalente al conocimiento de un administrador de bases de datos sobre su esquema, permitiéndole crear consultas que respeten su modelo de datos y aprovechen los índices y relaciones existentes.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            
            // PGSQLSchemaTool::make(new \PDO(...)),
        ];
    }
}

Esta herramienta también acepta un segundo argumento $tables. Básicamente puede pasar una lista de tablas que desea incluir en la información del esquema que se envía al LLM. Esto es básicamente una forma de limitar el alcance de las consultas que el agente ejecutará más adelante en la base de datos.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(
                new \PDO(...),
                ['users', 'categories', 'articles', 'tags']
            ),
        ];
    }
}

Al limitar el alcance del esquema, puede crear agentes especializados que se centren en áreas específicas de su aplicación. Un agente de gestión de contenido podría necesitar acceso solo a las tablas de artículos, categorías y etiquetas, mientras que un agente de administración de usuarios requiere visibilidad sobre las tablas de usuarios, roles y permisos. Este enfoque no solo mejora el rendimiento, sino que también reduce la carga cognitiva del modelo de lenguaje, lo que conduce a respuestas más precisas y enfocadas.

MySQLSelectTool / PGSQLSelectTool

Use esta herramienta para que su agente pueda ejecutar consultas SELECT en la base de datos.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSelectTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            MySQLSelectTool::make(new \PDO(...)),
        ];
    }
}

MySQLWriteTool / PGSQLWriteTool

Use esta herramienta para que su agente pueda realizar operaciones de escritura en la base de datos (INSERT, UPDATE, DELETE).

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLWriteTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            MySQLWriteTool::make(new \PDO(...)),
        ];
    }
}

Sistema de archivos

Este toolkit permite que el agente interactúe con el sistema de archivos local.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\FileSystem\FileSystemToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            FileSystemToolkit::make(),
        ];
    }
}

describe_directory_content	NeuronAI\Tools\Toolkits\FileSystem\DescribeDirectoryContentTool
read_file	NeuronAI\Tools\Toolkits\FileSystem\ReadFileTool
grep_file_content	NeuronAI\Tools\Toolkits\FileSystem\GrepFileContentTool
glob_path	NeuronAI\Tools\Toolkits\FileSystem\GlobPathTool
preview_file	NeuronAI\Tools\Toolkits\FileSystem\PreviewFileTool
parse_file	NeuronAI\Tools\Toolkits\FileSystem\ParseFileTool

Tavily

Este toolkit permite que su agente realice búsquedas web, extracción del contenido de páginas y rastreo.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilyToolkit::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

Búsqueda web de Tavily

Hace que su agente pueda buscar en la web. Requiere acceso a APIs de Tavily.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilySearchTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilySearchTool::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

Puede personalizar las opciones predeterminadas para obtener resultados de búsqueda pasando su preferencia en el withOptions método:

TavilySearchTool::make(
    key: 'TAVILY_API_KEY'
)->withOptions([
    'days' => 30,
    'max_results' => 10,
]),

Extracción de Tavily

Extrae el contenido de una página web desde una URL. Requiere acceso a APIs de Tavily.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyExtractTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilyExtractTool::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

Rastreo de Tavily

Tavily Crawl es una herramienta de recorrido de sitios web basada en grafos que puede explorar cientos de rutas en paralelo con extracción integrada y descubrimiento inteligente.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyCrawlTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilyCrawlTool::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

Jina

Este toolkit permite que su agente realice búsquedas web y lea el contenido de una URL específica.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            JinaToolkit::make(
                key: 'JINA_API_KEY'
            ),
        ];
    }
}

Búsqueda web de Jina

Hace que su agente pueda buscar en la web. Requiere acceso a API de Jina.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaWebSearch;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            JinaWebSearch::make(
                key: 'JINA_API_KEY'
            ),
        ];
    }
}

Lector de URL de Jina

Extrae el contenido de una página web desde una URL. Requiere acceso a API de Jina.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaUrlReader;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            JinaUrlReader::make(
                key: 'JINA_API_KEY'
            ),
        ];
    }
}

Memoria de Zep

Este toolkit conecta un agente de NeuronAI a Zep gráfo de conocimiento. Este tipo de sistema permite al agente almacenar hechos relevantes que pueden surgir durante las interacciones con el agente a lo largo del tiempo. Es una memoria a largo plazo en el sentido de que no está limitada a la conversación actual como lo hace el ChatHistory componente. Es un almacenamiento externo persistente que el agente utilizará para guardar y recuperar piezas individuales de información que pueden permitir respuestas más personalizadas.

Para saber más sobre las capacidades de este tipo de sistema, puede visitar el sitio web de Zep: https://www.getzep.com/

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Zep\ZepLongTermMemoryToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            ZepLongTermMemoryToolkit::make(
                key: 'ZEP_API_KEY',
                user_id: 'ID'
            ),
        ];
    }
}

El user_id los argumentos le permiten separar la memoria a largo plazo en diferentes silos si desea atender a varios usuarios. Según su caso de uso, puede usar este parámetro como una "clave" para separar la memoria de las distintas entidades con las que interactúa el agente (usuarios, empresas, etc.).

AWS SES

Servicio simple de correo electrónico (SES)

Esta herramienta permite al agente enviar un mensaje de correo electrónico a uno o más destinatarios, enviar notificaciones, confirmaciones, informes o cualquier otra comunicación basada en correo electrónico. La herramienta maneja automáticamente la entrega correcta del correo y el manejo básico de errores.

Para usar esta herramienta, el SDK de AWS para PHP debe estar instalado.

composer require aws/aws-sdk-php

La herramienta obtiene una instancia de la SesClient clase del SDK de AWS para PHP.

namespace App\Neuron;

use Aws\Ses\SesClient;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\AWS\SESTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SESTool::make(
                sesClient: new SesCleint(...),
                fromEmail: '[email protected]'
            ),
        ];
    }
}

Supadata YouTube

Este toolkit proporciona acceso a transcripciones de videos de YouTube, metadatos, información del canal y datos de listas de reproducción a través de Supadata.ai con fines de análisis de contenido e investigación.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataYouTubeToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataYouTubeToolkit::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

Transcripción de video

Permite al agente recuperar la transcripción de un video de YouTube.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataVideoTranscriptTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataVideoTranscriptTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

Metadatos del video

Permite al agente recuperar los metadatos de un video de YouTube.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataVideoMetadataTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataVideoMetadataTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

Metadatos del canal

Permite al agente recuperar metadatos de un canal de YouTube, incluidos el nombre, la descripción, el número de suscriptores y más.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataYoutubeChannelTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataYoutubeChannelTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

Metadatos de la lista de reproducción

Permite al agente recuperar metadatos de una lista de reproducción de YouTube, incluido el título, la descripción, el número de videos y más.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataYoutubePlaylistTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataYoutubePlaylistTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

Llamadas paralelas a herramientas

Si sus agentes hacen un uso intensivo de herramientas, puede habilitar la ejecución paralela si el modelo solicita múltiples llamadas a herramientas en una sola petición.

Ejecución secuencial (estándar)

El agente llama a las herramientas una a la vez, esperando que cada una termine antes de comenzar la siguiente:

1. Llamar a la herramienta A → esperar el resultado
2. Llamar a la herramienta B → esperar el resultado  
3. Llamar a la herramienta C → esperar el resultado

Tiempo total: Tiempo(A) + Tiempo(B) + Tiempo(C)

Ejecución paralela (con pcntl)

El agente llama a múltiples herramientas simultáneamente, permitiéndoles ejecutarse al mismo tiempo:

1. Llamar a las herramientas A, B y C a la vez
2. Esperar a que todas terminen

Tiempo total: Máx(Tiempo(A), Tiempo(B), Tiempo(C))

Requisitos

Para usar esta función necesita instalar el spatie/fork paquete. Para más información, consulte el repositorio de GitHub: https://github.com/spatie/fork

composer require spatie/fork

Limitaciones

Esta implementación requiere la pcntl extensión, que está instalada por defecto en muchos sistemas Unix y Mac.

pcntl solo funciona en procesos CLI, no en un contexto web.

Si el pcntl extensión no está presente en el sistema que ejecuta el agente (por ejemplo, máquinas Windows), el trait vuelve automáticamente a la ejecución estándar de llamadas a herramientas. Esto puede ser útil si tiene una falta de coincidencia entre su entorno de desarrollo local y el entorno de producción. Puede desarrollar localmente con pcntl deshabilitado, luego desplegar en entornos de producción donde puede estar habilitado—sin modificar una sola línea de código. El agente se adapta automáticamente a cualquier entorno de ejecución en el que se encuentre.

Habilitar ejecución paralela

Establezca parallelToolCalls(true) en su agente o RAG. El framework inyectará el nodo dedicado ParallelToolNode en lugar del estándar ToolNode en el flujo de trabajo.

class DemoAgent extends Agent
{
    public function __construct()
    {
        parent::__construct();
        $this->parallelToolCalls(true);
    }
    
    protected function provider(): AIProviderInterface
    {
        ...
    }

    protected function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}

Manejador de errores

Ahora la cuestión es cómo manejar los errores de las herramientas. Hay un par de opciones para adaptarse a diferentes escenarios y necesidades.

El ToolNode acepta un $errorHandler argumento (código). Es un callback que recibe la excepción lanzada por la herramienta y la instancia de la herramienta que falla.

Le permite implementar una lógica personalizada en caso de error de la herramienta (excepciones generales de la herramienta, o ToolRunsExceededException). Si devuelve un valor, se devolverá al modelo como resultado de la herramienta. Por defecto, el ToolNode vuelve a lanzar los errores de ejecución.

Definición fluida:

$agent = Agent::make()
    ->toolErrorHandler(
        fn(Throwable $e, ToolInterface $tool): string => "Error: {$e->getMessage()}"
    );

Ampliando el agente

También puede implementar resolveToolErrorHandler() directamente para definir el callback que se ejecutará.

class MyAgent extends Agent
{
    ...

    protected function resolveToolErrorHandler(): ?callable
    {
        return fn(Throwable $e, ToolInterface $tool): string => "Error: {$e->getMessage()}";
    }
}