> 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/agent.md).

# Agente

Implementa fácilmente interacciones con LLM con memoria integrada y uso de herramientas.

{% hint style="warning" %}

#### Habilidad del agente de programación

Usa **`/neuron-agent`** para enseñar a tu agente de programación cómo implementar un agente usando componentes de Neuron AI.

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

### Introducción

Puedes crear tu agente extendiendo la `NeuronAI\Agent\Agent` clase para heredar las funciones principales del framework y crear agentes completamente funcionales.

Esta clase gestiona automáticamente algunos mecanismos por ti, como la memoria, las herramientas y las llamadas a funciones. Trataremos estos aspectos con más detalle en las siguientes secciones.

Te recomendamos encarecidamente extender la clase Agent en lugar de crear agentes usando la [definición fluida](#fluent-agent-definition). Esta estrategia facilita añadir métodos y comportamiento personalizados al agente, y también fomenta la portabilidad, porque todas las partes móviles se encapsulan en una sola entidad que puedes ejecutar donde quieras en tu aplicación, o incluso publicar como un paquete Composer independiente.

Empecemos creando un agente de IA que resuma videos de YouTube. Empezamos creando la `YouTubeAgent` clase:

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

```bash
vendor/bin/neuron make:agent App\\Neuron\\YouTubeAgent
```

{% endtab %}

{% tab title="Windows" %}

```powershell
.\vendor\bin\neuron make:agent App\Neuron\YouTubeAgent
```

{% endtab %}
{% endtabs %}

El comando creará una clase como esta:

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // devuelve una instancia de Anthropic, OpenAI, Gemini, Ollama, etc...
    }
    
    protected function instructions(): string
    {
        return new SystemMessage(
            "Eres un agente de IA amable creado con el framework Neuron."
        );
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

### 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>" %}

### Proveedor de IA

La implementación mínima requiere asignar un proveedor de IA que será el motor de lenguaje y razonamiento de tu agente.

El único método requerido para implementar es `provider()` que devuelve la instancia del proveedor que deseas usar. Supongamos que es Anthropic.

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Message\SystemMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // devuelve una instancia de Anthropic, OpenAI, Gemini, Ollama, etc...
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    protected function instructions(): SystemMessage
    {
        return new SystemMessage(
            "Eres un agente de IA amable creado con el framework Neuron."
        );
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

También puedes usar otros proveedores como OpenAI, Gemini u Ollama si quieres ejecutar el modelo localmente. Consulta los [proveedores compatibles](https://docs.neuron-ai.dev/neuron-v3-es/proveedores/ai-provider.md).

### Instrucciones del sistema

El segundo bloque de construcción importante son las instrucciones del sistema. Las instrucciones del sistema proporcionan indicaciones para hacer que la IA actúe de acuerdo con la tarea que queremos lograr. Son instrucciones fijas que se enviarán al LLM en cada interacción.

Por eso se definen mediante un método interno y permanecen encapsuladas dentro de la entidad del agente. Implementemos el `instructions()` método:

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\SystemMessage;;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

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(): SystemMessage
    {
        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);
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

La clase SystemMessage también puede poblarse con múltiples bloques de contenido SystemContent para inyectar dinámicamente contenidos en las instrucciones del sistema:

```php
class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        ...
    }
    
    protected function instructions(): SystemMessage
    {
        $message = 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.
        TEXT);
        
        $message->addContent(
            new SystemContent("Escribe un resumen en un párrafo sin usar listas. Usa solo texto fluido.")
        );
        
        $message->addContent(
            new SystemContent("Después del resumen, añade una lista de tres oraciones con las tres conclusiones más importantes del video.")
        );
                
        return $message;
    }
}
```

Si quieres usar el almacenamiento en caché del prompt del sistema para proveedores como Anthropic, puedes llamar al método cache() en cada parte de contenido que quieras almacenar en caché:

```php
$message->addContent(
    new SystemContent("...")->cache()
);
```

O llama al método cache en el `SystemMessage` para almacenar en caché todo el prompt del sistema:

```php
    protected function instructions(): SystemMessage
    {
        $message = new SystemMessage(...);
        
        $message->addContent(
            new SystemContent(...)
        );
        
        $message->addContent(
            new SystemContent(...)
        );
                
        return $message->cache(); // <- Almacenar todo en caché
    }
```

### Habla con el agente

Ya estamos listos para probar cómo responde el agente a nuestro mensaje basándose en las nuevas instrucciones.

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

$message = YouTubeAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("¿Quién eres?"))
    ->getMessage();
    
echo $message->getContent();
// Hola, ¡soy un agente de IA amable especializado en resumir videos de YouTube!
// ¿Puedes darme la URL de un video de YouTube del que quieras un resumen rápido?
```

### Estado del agente

Dado que el Agent es una extensión del Workflow, en lugar de obtener la última respuesta del modelo con el `getMessage()` método, puedes simplemente ejecutar el flujo de trabajo del agente y obtener el estado bruto del agente como valor de retorno. El estado del agente contiene información adicional que puede ayudarte a inspeccionar lo que ocurrió durante la ejecución del agente.

```php
$state = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("¿Quién eres?"));

// $state es una instancia de la clase NeuronAI\Agent\AgentState
$state->getMessage();
```

#### Pasos

Al llamar al `getMessage()` método solo puedes obtener el último mensaje generado por el modelo para responder a tu solicitud. Pero internamente el agente puede realizar muchas iteraciones de llamadas a herramientas antes de llegar a la respuesta final.

El estado del agente almacena la lista de todos los mensajes entre el agente y el proveedor para el ciclo de ejecución actual, en lugar de solo la respuesta final. Así puedes acceder a la lista de mensajes con el `getSteps()` método en el estado del agente:

```php
$state = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("¿Quién eres?"));

// Accede a la lista de pasos durante la ejecución
foreach($state->getSteps() as $message) {
    echo "- ".$message::class."\n";
}

// La respuesta final
echo $state->getMessage()->getContent();
```

#### Ejecuciones de herramientas

Si el agente decide usar herramientas durante la ejecución, el estado del agente mantiene un seguimiento del número de ejecuciones de herramientas para detener la ejecución si el [maxRuns](https://docs.neuron-ai.dev/neuron-v3-es/agente/tools.md#max-runs) límite se alcanza. Puedes acceder a este mapa:

```php
$state = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("¿Quién eres?"));

// Accede al mapa de ejecuciones de herramientas
foreach($state->getToolRuns() as $toolName => $runs) {
    echo "- La herramienta {$toolName} se usó {$runs} veces\n";
}
```

### Mensaje

El agente siempre acepta la entrada como una `Mensaje` clase y devuelve instancias de Message.

Como viste en el ejemplo anterior, enviamos una instancia de `UserMessage` al agente y recuperamos el mensaje de respuesta que será una instancia de `AssistantMessage` . Una lista de mensajes del asistente y mensajes del usuario crea un chat.

Aprenderemos más sobre [ChatHistory](https://docs.neuron-ai.dev/neuron-v3-es/agente/chat-history-and-memory.md) más adelante, pero es importante saber que la interfaz unificada para la entrada y salida del agente es el `Mensaje` objeto.

<a href="https://docs.neuron-ai.dev/neuron-v3-es/agente/messages.md" class="button primary" data-icon="arrow-right-long">Más información sobre Messages</a>

### Definición fluida del agente

Como alternativa a la encapsulación en una sola clase, también puedes instruir al agente en línea usando la cadena fluida de métodos:

```php
$agent = Agent::make()
    ->setThreadId('chat_id')
    ->setAiProvider(
        new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        )
    )
    ->setInstructions(
        new SystemMessage(...)
    )
    ->addTool([...]);
    
$message = $agent->chat(new UserMessage(...))->getMessage();
echo $message->gentContent();
```
