> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-es/agente/tools.md).

# Herramientas y kits de herramientas

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

{% hint style="warning" %}

#### Habilidad del agente de programación

**`/neuron-tool`** para enseñarle a tu agente de programación cómo implementar herramientas personalizadas y usarlas en tu clase de agente.

[Desarrollo asistido por IA](https://docs.neuron-ai.dev/neuron-v3-es/resumen/agentic-development.md)
{% endhint %}

El bucle central del agente implica llamar a un modelo, dejar que elija herramientas para ejecutar y, luego, terminar cuando ya no se necesitan más herramientas para proporcionar una respuesta:

<figure><img src="https://4076695836-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2F59ZHXSPR086dp25ry7ou%2Fneuron-tool-call.png?alt=media&amp;token=f1a11d32-9024-4efc-8f44-6c329f2d102a" alt=""><figcaption></figcaption></figure>

### 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. Te permiten ampliar las capacidades de tu agente al darle acceso a funciones concretas que puede llamar dentro de tu código.

{% embed url="<https://www.youtube.com/watch?v=lI8xE-uIek8>" %}

En el [YouTubeAgent](https://docs.neuron-ai.dev/neuron-v3-es/agente/agent.md) ejemplo podemos definir una herramienta para hacer que el Agente pueda recuperar la transcripción del video de YouTube, para que pueda crear un breve resumen:

```php
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 proveedor de IA (Anthropic, OpenAI, Ollama, Gemini, etc.)
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    protected function instructions(): string 
    {
        return new SystemMessage(<<<TEXT
            Eres un agente de IA especializado en escribir resúmenes de videos de YouTube.
            Obtén la URL de un video de YouTube, o pide al usuario que proporcione una.
            Usa las herramientas disponibles para recuperar la transcripción del video.
            Escribe un resumen en un párrafo sin usar listas. Usa solo texto fluido.
            Después del resumen, añade una lista de tres oraciones con las tres conclusiones más importantes del video.
        TEXT);
    }
    
    protected function tools(): array
    {
        return [
            GetTranscriptionTool::make('API_KEY'),
        ];
    }
}

```

Hemos introducido el nuevo método `tools()` en la clase Agent. Este método espera devolver un array de Tools que la IA puede usar si es necesario para completar tareas.

Neuron te proporciona estas APIs claras y sencillas y automatiza todas las interacciones subyacentes con el LLM. Puedes conectar prácticamente todo lo que quieras al agente. Poder ejecutar funciones locales te permite invocar cualquier API externa o componente de la aplicación y dejar que el agente realice acciones reales en tu entorno.

### Crear herramientas

Las herramientas son componentes que extienden la `Tool` class. Eres libre de crear herramientas preempaquetadas para hacer que el agente pueda realizar acciones.

Para crear una nueva herramienta, ejecuta el comando de consola que aparece a continuación:

{% tabs %}
{% tab title="Unix" %}

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

{% endtab %}

{% tab title="Windows" %}

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

{% endtab %}
{% endtabs %}

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

```php
<?php

namespace App\Neuron\Tools;

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

class GetTranscriptionTool extends Tool
{
    protected string $name = 'get_transcription';
    
    protected ?string $description = 'Recuperar la transcripción de un video de YouTube.';
    
    protected Client $client;
    
    public function __construct(protected string $key)
    {
    }
    
    /**
     * 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
            )
        ];
    }
    
    /**
     * Implementando la lógica de la herramienta
     */
    public function __invoke(string $video_url): ToolOutput
    {
        $response = $this->getClient()
            ->get('transcript?url=' . $video_url.'&text=true')
            ->getBody()
            ->getContents();

        $response = json_decode($response, true);

        return ToolOutput::text($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**: Esta es la información que el LLM usa para decidir cuándo y por qué se debe usar la herramienta. La ingeniería de prompts puede ayudar a instruir 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 se devolverá al modelo.

Observa cómo el `__invoke()` método acepta los mismos argumentos definidos por la `ToolProperty` con el mismo nombre y tipo de datos.

Una vez implementada, puedes listar la herramienta en el array devuelto por el método tools.

```php
<?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'),
        ];
    }
}
```

`GetTranscriptionTool` es solo un ejemplo. Con el tiempo, puedes implementar otras herramientas para hacer que el Agente pueda recuperar otros metadatos del video y mejorar así sus capacidades de análisis de video.

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

```php
use NeuronAI\Chat\Messages\UserMessage;

$message = YouTubeAgent::make($user)
    ->setThreadId('chat_id')
    ->chat(
        new UserMessage('¿Qué hay de 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 poderoso 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 eligen actuar los seres humanos hacia la Naturaleza determina ...

*/
```

### Máximo de ejecuciones

Los agentes tienen un mecanismo de seguridad que hace seguimiento del 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 `ToolRunsExceededException` lanza. Por defecto, el límite es de 10 llamadas, y se cuenta para cada herramienta de forma individual.

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

```php
try {

    $response = YouTubeAgent::make()
        ->setThreadId('chat_id')
        ->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
}
```

Por defecto, las ejecuciones de las herramientas se rastrean por el nombre de la herramienta. Puedes personalizar esta clave implementando `getRunKey()` en la clase de la herramienta:

```php
class GetTranscriptionTool extends Tool
{
    ...
    
    public function getRunKey(): string
    {
        return $this->getName() . ':' . hash('sha1', json_encode($this->getInputs()));
    }
}
```

En el ejemplo anterior, también hacemos seguimiento de las ejecuciones de la herramienta en función de los parámetros de entrada, por lo que la misma herramienta, llamada con distintas entradas, se contará en claves separadas. Para este caso de uso específico puedes utilizar el trait integrado `NeuronAI\Tools\TrackByInputs` que ya implementa un seguimiento de ejecuciones teniendo en cuenta los parámetros:

```php
use NeuronAI\Tools\TrackByInputs;

class GetTranscriptionTool extends Tool
{
    use TrackByInputs;
    
    ...
}
```

### Visibilidad

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

```php
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.

### Salida multimodal de la herramienta

Por defecto, una herramienta devuelve una cadena (o un array, que se codifica en JSON). Cuando tu herramienta necesita enviar contenido más rico al modelo, como imágenes, documentos, audio o video, devuelve una `ToolOutput` instancia de `__invoke()` en su lugar. Envuelve una lista de bloques de contenido que los proveedores que admiten resultados multimodales de herramientas (como Anthropic) mapean de forma nativa a su API; los proveedores solo de texto recurren automáticamente a los bloques de texto concatenados. Esto funciona en todas las herramientas desde el primer momento.

```php
use NeuronAI\Chat\Enums\MediaType;
use NeuronAI\Chat\Enums\SourceType;
use NeuronAI\Chat\Messages\ContentBlocks\ImageContent;
use NeuronAI\Chat\Messages\ContentBlocks\TextContent;
use NeuronAI\Tools\ToolOutput;

class PriceChartTool extends Tool
{
    ...

    public function __invoke(string $symbol): ToolOutput
    {
        $base64 = $this->renderChart($symbol);

        return new ToolOutput([
            new TextContent("Gráfico de precios para {$symbol}"),
            new ImageContent($base64, SourceType::BASE64, MediaType::PNG),
        ]);
    }
}
```

Para salidas de un solo bloque puedes usar los constructores abreviados: `ToolOutput::text(...)`, `ToolOutput::image(...)`, `ToolOutput::file(...)`, `ToolOutput::audio(...)`, `ToolOutput::video(...)`.

> Incluye un `TextContent` bloque en las salidas pensadas para funcionar con todos los proveedores: los proveedores solo de texto ven únicamente los bloques de texto, por lo que una salida solo de imagen les llegaría vacía.

### Aprobación de herramientas

Neuron te ofrece compatibilidad completa con los patrones human in the loop, incluida la aprobación de herramientas. El framework intercepta la llamada a la herramienta y se pausa, esperando la decisión final del usuario.

Simplemente sobrescribe el `approvalPolicy()` método en la clase Tool para determinar si la herramienta debería requerir aprobación. El método recibirá las entradas que el modelo quiere usar para llamar a la herramienta. Devolver una cadena cuenta como true y también funciona como el motivo de la solicitud de aprobación.

```php
class BuyTicketTool extends Tool
{
    ...,
    
    protected function approvalPolicy(array $inputs): bool|string
    {
        // La herramienta requiere aprobación si el importe es mayor que 100
        return $inputs['amount'] > 100;
    }
}
```

Consulta la sección dedicada para entender cómo gestionar el flujo completo de aprobación: [Aprobación de herramientas](https://docs.neuron-ai.dev/neuron-v3-es/agente/tool-approval.md)

### Búsqueda de herramientas

Por defecto, cada vez que se invoca el proveedor, todas las herramientas se cargan y se transmiten al LLM del backend. Un agente de producción complejo conectado a correo electrónico, calendario, drive, CRM y múltiples 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.

{% content-ref url="/pages/b17ff1200828767959e6ec06f777645020907a3a" %}
[Middleware](https://docs.neuron-ai.dev/neuron-v3-es/agente/middleware.md)
{% endcontent-ref %}

{% embed url="<https://www.youtube.com/watch?v=qYmidHAXEYM>" %}

### Monitoreo y depuración

Muchas de las aplicaciones que construyas con Neuron contendrán múltiples pasos con múltiples invocaciones de llamadas a LLM. A medida que estas aplicaciones se vuelven cada vez más complejas, resulta crucial poder inspeccionar exactamente qué está ocurriendo dentro de tu sistema agéntico. La mejor manera de hacerlo es con [Inspector](https://inspector.dev/).

{% embed url="<https://docs.inspector.dev/guides/neuron-ai>" %}

## 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 entre sí para definir estructuras de datos complejas.

### ToolProperty

Esta clase representa un valor escalar simple como string, int o boolean.

```php
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
            )
        ];
    }
    
    public function __invoke(string $arg): ToolOutput 
    {
        ...
    }
}
```

### ArrayProperty

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

Usa el argumento `items` para especificar el tipo de datos de los elementos del array. En el ejemplo de abajo pedimos un array de strings.

```php
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): ToolOutput
    {
        ...
    }
}
```

#### Límites máximos y mínimos

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

```php
$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:

```php
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): ToolOutput
    {
        ...
    }
}
```

### Entrada estructurada de la herramienta

Si el objeto que quieres tiene muchas propiedades, puedes pasar una clase PHP estructurada a la `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:

```php
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): ToolOutput
    {
        ...
    }
}
```

Así es como se ve la clase Colors:

```php
<?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;
}
```

## Herramienta 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. Aunque 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:

```php
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](https://docs.neuron-ai.dev/neuron-v3-es/proveedores/ai-provider.md#openairesponses), [Gemini](https://docs.neuron-ai.dev/neuron-v3-es/proveedores/ai-provider.md#gemini), y [Anthropic](https://docs.neuron-ai.dev/neuron-v3-es/proveedores/ai-provider.md#anthropic) admiten estas herramientas.

## Herramienta de frontend

Hasta ahora, una herramienta era una sola cosa: una representación de una función PHP que el modelo puede pedir ejecutar y que el backend ejecuta. `Herramienta de frontend` te permite definir herramientas que se ejecutarán en el frontend de tu aplicación. Una vez completadas, el frontend devuelve el resultado de la ejecución de la herramienta, y Neuron proporciona este resultado al modelo para continuar el bucle.

Así, los agentes del backend pueden acceder a las APIs del navegador o a las capacidades del dispositivo en una aplicación móvil de forma transparente.

`Herramienta de frontend` lo convierte en un concepto de primera clase en Neuron. El modelo lo ve y puede llamarlo, pero el backend nunca lo ejecuta. Cuando el modelo llama a una herramienta de frontend, el agente suspende la ejecución, te entrega las llamadas pendientes y continúa desde ese punto exacto una vez que envías los resultados.

El framework incluye integración integrada para AG-UI con [CopilotKit](https://docs.copilotkit.ai/frontend-tools), y [Vercel AI SDK](https://ai-sdk.dev/docs/foundations/tools#provider-defined-tools).

### Cómo funciona

Una `Herramienta de frontend` se construye a partir de un nombre, una descripción opcional y un esquema JSON opcional que describe sus entradas. No tiene `__invoke()`; así que una herramienta de frontend nunca puede ejecutarse en el servidor.

Cuando el modelo devuelve un lote de llamadas a herramientas, el agente divide el lote:

1. **Primero la aprobación.** Cualquier llamada cuya herramienta requiera aprobación suspende la ejecución con una `ApprovalRequest`, exactamente igual que con las herramientas locales. Consulta [aprobación de herramientas](#tool-approval).
2. **Las herramientas locales se ejecutan** en el backend como de costumbre.
3. **Las llamadas diferidas suspenden la ejecución** con una `ToolResultsRequest`. La solicitud lleva los `ToolCall` objetos pendientes (nombre, ID de llamada, entradas) para que puedas enviarlos al frontend.

{% hint style="warning" %}
Recomendamos usar **`/neuron-frontend-integration`** skill en tu asistente de programación para entender mejor el flujo completo y los detalles de implementación.
{% endhint %}

Para continuar, envía los resultados asociados por ID de llamada a través de `Agent::submitInputs()` con una `ToolResultsTranslator`. Una vez que cada llamada diferida tenga un resultado, el agente escribe los resultados de las herramientas en el historial del chat y ejecuta la siguiente inferencia.

### Registro de una herramienta de frontend

```php
use NeuronAI\Tools\FrontendTool;

$readTitle = new FrontendTool(
    name: 'read_page_title',
    description: 'Leer el título de la página que el usuario está viendo actualmente.'
);

$readText = new FrontendTool(
    name: 'read_element_text',
    description: 'Leer el contenido de texto de un elemento de la página.',
    inputSchema: [
        'type' => 'object',
        'properties' => [
            'selector' => ['type' => 'string', 'description' => 'Selector CSS del elemento'],
        ],
        'required' => ['selector'],
    ]
);

$agent = Agent::make()
    ->setAiProvider($provider)
    ->setChatHistory(new SQLChatHistory($pdo, $threadId))
    ->setPersistence(new DatabasePersistence($pdo))
    ->addTool([$readTitle, $readText, new SearchDocsTool()]);
```

Sin un esquema, una herramienta diferida se comporta como cualquier otra herramienta: puedes añadir propiedades con `addProperty()` o sobrescribir `properties()` en una subclase. Una herramienta de frontend también puede requerir aprobación con `requireApproval()` como cualquier otra herramienta.

### Suspender y reanudar con resultados

```php
use NeuronAI\Agent\Interrupt\ToolResultsRequest;
use NeuronAI\Agent\Interrupt\ToolResultsTranslator;
use NeuronAI\Chat\Messages\UserMessage;

// La solicitud 1: el modelo decide leer la página.
$state = $agent->chat(new UserMessage('¿De qué trata esta página?'));

if ($state->isInterrupted()) {
    $request = $state->getInterruptRequest();

    if ($request instanceof ToolResultsRequest) {
        foreach ($request->getToolCalls() as $call) {
            // Enviar $call->getName(), $call->getCallId() y $call->getInputs()
            // al cliente que los ejecutará.
        }
    }
}

// Solicitud 2: el cliente envía los resultados de vuelta, indexados por ID de llamada.
$results = [
    'call_01' => ['result' => 'Neuron AI - PHP Agent Framework'],
    'call_02' => ['error' => 'Elemento no encontrado'],
];

$state = $agent
    ->submitInputs($results, new ToolResultsTranslator())
    ->run();

echo $state->getMessage()->getContent();
```

La siguiente inferencia ve el resultado exitoso como un mensaje normal de resultado de herramienta, y el error como un error de herramienta sobre el que el modelo puede actuar.

{% hint style="warning" %}
Recomendamos usar **`/neuron-frontend-integration`** skill en tu asistente de programación para entender mejor el flujo completo y los detalles de implementación.
{% endhint %}

## Conjuntos de herramientas

La filosofía detrás del sistema de conjuntos de herramientas de Neuron surgió de una observación fundamental durante el desarrollo de agentes de IA: aunque las herramientas individuales proporcionan 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 la forma en que pensamos sobre la composición de capacidades de los agentes. Aquí hay un ejemplo de cómo puedes añadir un toolkit a un agente:

```php
<?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 por separado. 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 rápidamente se vuelve engorroso 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 única interfaz coherente que puede adjuntarse a cualquier agente con una sola línea de código.

Aquí hay un ejemplo:

```php
namespace NeuronAI\Tools\Toolkits\Calculator;

use NeuronAI\Tools\Toolkits\AbstractToolkit;

class BookingToolkit extends AbstractToolkit
{
    public function guidelines(): ?string
    {
        return "Este conjunto de herramientas 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 [
            Search::make(),
            Book::make(),
            Checkin::make(),
            Checkout::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()` la función 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 juntas. 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.

**Proveer**

El `provide()` la función devuelve el array de herramientas incluidas en el toolkit de forma predeterminada. Cuando un toolkit se adjunta a un agente, las herramientas individuales pasan a estar 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, a menudo me he encontrado con situaciones en las que un toolkit proporciona en su mayoría la funcionalidad adecuada, pero incluye herramientas que podrían provocar un comportamiento no deseado en contextos específicos, o simplemente necesitan restringirse y configurarse individualmente.

#### Excluir

El `exclude()` la función aborda este desafío con elegancia, permitiendo a los desarrolladores adjuntar toolkits completos mientras mantienen un control granular sobre las capacidades disponibles. Esto resulta especialmente útil cuando se trabaja con agentes especializados que necesitan capacidades concretas, pero quieres reducir la probabilidad de errores del agente y el consumo de tokens.

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

El mecanismo de exclusión opera a nivel de clase, utilizando nombres de clase completamente cualificados para identificar las herramientas que se eliminarán.

#### Solo

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

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

#### Con

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

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

Desde la perspectiva de la extensibilidad, el sistema de toolkits abre oportunidades notables para la contribución de la comunidad y el crecimiento del ecosistema. La interfaz coherente significa que desarrolladores de terceros pueden crear toolkits específicos de dominio que se integren perfectamente 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.

### Añadir herramientas en tiempo de ejecución

Puedes añadir una o más herramientas a un toolkit y las directrices generadas o las instrucciones del sistema del agente también las cubrirán. Ten en cuenta que los filtros también actúan sobre las herramientas añadidas.

```php
// Añadir una herramienta
MyToolkit::make()->add(new CustomTool());

// Esto excluye CustomTool del toolkit
MyToolkit::make()
    ->add(new CustomTool())
    ->only([AnotherTool::class]);
```

## Conjuntos de herramientas disponibles

Neuron incluye varias herramientas y toolkits integrados que te permiten equipar rápidamente a tus agentes con muchas habilidades. Puedes usar estas herramientas individualmente o adjuntar conjuntos completos de herramientas 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 tus agentes de IA resuelvan con precisión expresiones matemáticas. 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.

{% hint style="warning" %}
**`ext-bcmath`** se requiere la extensión de PHP para usar este toolkit. Asegúrate de añadirla como requisito en tu `composer.json` archivo.
{% endhint %}

```php
<?php

namespace App\Neuron;

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

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

<table data-header-hidden><thead><tr><th width="253"></th><th></th></tr></thead><tbody><tr><td>evaluar</td><td>NeuronAI\Tools\Toolkits\Calculator\Evaluate</td></tr><tr><td>media</td><td>NeuronAI\Tools\Toolkits\Calculator\MeanTool</td></tr><tr><td>mediana</td><td>NeuronAI\Tools\Toolkits\Calculator\MedianTool</td></tr><tr><td>moda</td><td>NeuronAI\Tools\Toolkits\Calculator\ModeTool</td></tr><tr><td>desviación estándar</td><td>NeuronAI\Tools\Toolkits\Calculator\StandardDeviationTool</td></tr><tr><td>varianza</td><td>NeuronAI\Tools\Toolkits\Calculator\VarianceTool</td></tr></tbody></table>

### Calendario

​Este toolkit proporciona operaciones completas de fecha y hora. Usa estas herramientas para que tu agente pueda trabajar con fechas, horas, formatos, cálculos y conversiones de zona horaria.

```php
<?php

namespace App\Neuron;

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

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

<table data-header-hidden><thead><tr><th width="205"></th><th></th></tr></thead><tbody><tr><td>current_datetime</td><td>NeuronAI\Tools\Toolkits\Calendar\CurrentDateTimeTool</td></tr><tr><td>get_timestamp</td><td>NeuronAI\Tools\Toolkits\Calendar\GetTimestampTool</td></tr><tr><td>format_date</td><td>NeuronAI\Tools\Toolkits\Calendar\FormatDateTool</td></tr><tr><td>date_difference</td><td>NeuronAI\Tools\Toolkits\Calendar\DateDifferenceTool</td></tr><tr><td>add_time</td><td>NeuronAI\Tools\Toolkits\Calendar\AddTimeTool</td></tr><tr><td>subtract_time</td><td>NeuronAI\Tools\Toolkits\Calendar\SubtractTimeTool</td></tr><tr><td>calculate_age</td><td>NeuronAI\Tools\Toolkits\Calendar\CalculateAgeTool</td></tr><tr><td>convert_timezone</td><td>NeuronAI\Tools\Toolkits\Calendar\ConvertTimezoneTool</td></tr><tr><td>get_timezone_info</td><td>NeuronAI\Tools\Toolkits\Calendar\GetTimezoneInfoTool</td></tr><tr><td>get_weekday</td><td>NeuronAI\Tools\Toolkits\Calendar\GetWeekdayTool</td></tr><tr><td>is_weekend</td><td>NeuronAI\Tools\Toolkits\Calendar\IsWeekendTool</td></tr><tr><td>is_leap_year</td><td>NeuronAI\Tools\Toolkits\Calendar\IsLeapYearTool</td></tr><tr><td>get_days_in_month</td><td>NeuronAI\Tools\Toolkits\Calendar\GetDaysInMonthTool</td></tr><tr><td>start_of_period</td><td>NeuronAI\Tools\Toolkits\Calendar\StartOfPeriodTool</td></tr><tr><td>end_of_period</td><td>NeuronAI\Tools\Toolkits\Calendar\EndOfPeriodTool</td></tr><tr><td>get_week_number</td><td>NeuronAI\Tools\Toolkits\Calendar\GetWeekNumberTool</td></tr><tr><td>compare_dates</td><td>NeuronAI\Tools\Toolkits\Calendar\CompareDatesTool</td></tr><tr><td>is_date_in_range</td><td>NeuronAI\Tools\Toolkits\Calendar\IsDateInRangeTool</td></tr></tbody></table>

### MySQL y PostgreSQL

Estos toolkits permiten que tu agente interactúe con tu base de datos. Si preguntas "¿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 implicadas y recupera datos reales de tu sistema.

<figure><img src="https://content.gitbook.com/content/GHx4l2LknIex7vFIUg1R/blobs/se2Qip6z2M3hyHvV8rQm/data-analyst-ai-agent-php-report.png" alt=""><figcaption></figcaption></figure>

Todas las herramientas de los toolkits de MySQL y PostgreSQL requieren una [PDO](https://www.php.net/manual/en/class.pdo.php) instancia como argumento del constructor. Si te encuentras en un entorno de framework o ya estás usando un ORM en general, puedes obtener la instancia PDO subyacente del ORM y pasársela a las herramientas. Puedes 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ías pensar en crear credenciales dedicadas para tu agente. Podría ser útil para controlar el nivel de acceso que tu agente tiene a la base de datos.

En cualquier caso, tienes herramientas separadas para leer y escribir en la base de datos. Si no confías en el comportamiento de tu agente, puedes no proporcionar la herramienta de escritura.

```php
<?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 [
            // Conectarse 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"),
            ),
        ];
    }
}
```

{% hint style="warning" %}
Estos ejemplos hacen referencia a `MySQLToolkit` pero es exactamente lo mismo usando `PGSQLToolkit`.
{% endhint %}

#### MySQLSchemaTool / PGSQLSchemaTool

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

```php
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 puedes pasar una lista de tablas que quieres incluir en la información del esquema que se envía al LLM. Es, en esencia, una forma de limitar el alcance de las consultas que el agente ejecutará más tarde en la base de datos.

```php
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, puedes crear agentes especializados que se centren en áreas específicas de tu aplicación. Un agente de gestión de contenidos podría necesitar solo acceso 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 centradas.

#### MySQLSelectTool / PGSQLSelectTool

Usa esta herramienta para que tu agente pueda ejecutar consultas SELECT contra la base de datos.

```php
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

Usa esta herramienta para que tu agente pueda realizar operaciones de escritura contra la base de datos (INSERT, UPDATE, DELETE).

```php
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.

```php
namespace App\Neuron;

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

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

<table data-header-hidden><thead><tr><th width="256"></th><th></th></tr></thead><tbody><tr><td>describe_directory_content</td><td>NeuronAI\Tools\Toolkits\FileSystem\DescribeDirectoryContentTool</td></tr><tr><td>read_file</td><td>NeuronAI\Tools\Toolkits\FileSystem\ReadFileTool</td></tr><tr><td>grep_file_content</td><td>NeuronAI\Tools\Toolkits\FileSystem\GrepFileContentTool</td></tr><tr><td>glob_path</td><td>NeuronAI\Tools\Toolkits\FileSystem\GlobPathTool</td></tr><tr><td>preview_file</td><td>NeuronAI\Tools\Toolkits\FileSystem\PreviewFileTool</td></tr><tr><td>parse_file</td><td>NeuronAI\Tools\Toolkits\FileSystem\ParseFileTool</td></tr></tbody></table>

### Tavily

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

```php
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

Permite que tu agente busque en la web. Requiere acceso a [las API de Tavily](https://tavily.com/).

```php
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'
            ),
        ];
    }
}
```

Puedes personalizar las opciones predeterminadas para recuperar resultados de búsqueda pasando tu preferencia en `withOptions` método:

```php
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 [las API de Tavily](https://tavily.com/).

```php
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.

```php
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 tu agente realice búsquedas web y lea el contenido de una URL específica.

```php
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

Permite que tu agente busque en la web. Requiere acceso a [API de Jina](https://jina.ai/).

```php
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](https://jina.ai/).

```php
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'
            ),
        ];
    }
}
```

## Llamadas paralelas a herramientas

Si tus agentes consumen muchas herramientas, puedes habilitar la ejecución en paralelo 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 a que cada una termine antes de iniciar 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**, permitiendo que se ejecuten al mismo tiempo:

```
1. Llamar a las herramientas A, B y C al mismo tiempo
2. Esperar a que todas terminen

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

### Requisitos

Para usar esta función necesitas instalar el `spatie/fork` paquete. Para más información consulta el repositorio de GitHub: <https://github.com/spatie/fork>

```shellscript
composer require spatie/fork
```

{% hint style="warning" %}

### 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 recurre automáticamente a la ejecución estándar de llamadas a herramientas. Esto puede ser útil si tienes una discrepancia entre tu entorno local de desarrollo y el entorno de producción. Puedes desarrollar localmente con `pcntl` deshabilitado, y luego desplegar en entornos de producción donde pueda estar habilitado—**sin modificar ni una sola línea de código**. El agente se adapta automáticamente al entorno de ejecución en el que se encuentre.
{% endhint %}

### Habilitar la ejecución paralela

Establece `parallelToolCalls(true)` en tu Agent o RAG. El framework inyectará el nodo dedicado `ParallelToolNode` en lugar del `ToolNode` estándar en el flujo de trabajo.

```php
class DemoAgent extends Agent
{
    public function __construct()
    {
        parent::__construct();
        
        // Habilitar llamada paralela a herramientas
        $this->parallelToolCalls(
            enabled: true,
            beforeChild: fn() => DB::purge(),
            afterChild: fn() => DB::purge()
        );
    }
    
    protected function provider(): AIProviderInterface
    {
        ...
    }

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

El método acepta dos callbacks opcionales: `beforeChild`, `afterChild`.

Los procesos hijo bifurcados pueden heredar recursos vinculados al proceso que no pueden compartirse de forma segura, como las conexiones a bases de datos.

## Manejador de errores

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

El `ToolNode` acepta un `$errorHandler` argumento [(code)](https://github.com/neuron-core/neuron-ai/blob/3.x/src/Agent/Nodes/ToolNode.php#L37)Es una callback que recibe la excepción lanzada por la herramienta y la instancia de la herramienta que ha fallado.

Te permite implementar una lógica personalizada en caso de error de herramienta (excepciones generales de herramientas, o `ToolRunsExceededException`). **Si devuelves un valor, se devolverá al modelo como resultado de la herramienta.** De forma predeterminada, ToolNode vuelve a lanzar los errores de ejecución.

**Definición fluida:**

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

**Extender el agente**

También puedes implementar `resolveToolErrorHandler()` directamente para definir la callback que se ejecutará.

```php
class MyAgent extends Agent
{
    ...

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