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

### Introducción

Puedes crear tu agente extendiendo la `NeuronAI\Agent\Agent` clase para heredar las principales características 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. Profundizaremos en estos aspectos 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 comportamientos personalizados al agente, y también fomenta la portabilidad, porque todas las partes móviles quedan encapsuladas en una sola entidad que puedes ejecutar donde quieras en tu aplicación, o incluso publicar como un paquete independiente de Composer.

Empecemos a crear 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 "Eres un agente de IA amigable creado con el framework Neuron AI.";
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

### Monitorización y depuración

Muchas de las aplicaciones que construyas con Neuron contendrán múltiples pasos con varias invocaciones de llamadas LLM. A medida que estas aplicaciones se vuelven cada vez más complejas, resulta crucial poder inspeccionar qué está ocurriendo exactamente 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 obligatorio de implementar es `provider()` que devuelve la instancia del proveedor que quieres usar. Supongamos que es Anthropic.

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
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(): string
    {
        return "Eres un agente de IA amigable creado con el framework Neuron AI.";
    }
    
    /**
     * @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](/neuron-v3-es/proveedores/ai-provider.md).

### Instrucciones del sistema

El segundo bloque fundamental importante son las instrucciones del sistema. Las instrucciones del sistema proporcionan directrices para 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\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // devuelve una instancia del proveedor de IA (Anthropic, OpenAI, Ollama, Gemini, etc.)
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    protected function instructions(): string
    {
        return <<<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 que tienes 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 [];
    }
}
```

### Habla con el agente

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()
    ->chat(new UserMessage("Who are you?"))
    ->getMessage();
    
echo $message->getContent();
// ¡Hola, soy un agente de IA amigable 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

Como 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 como valor de retorno el estado bruto del agente. 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()
    ->chat(new UserMessage("Who are you?"))
    ->run();

// $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 prompt. 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í que puedes acceder a la lista de mensajes con el `getSteps()` método en el estado del agente:

```php
$state = MyAgent::make()
    ->chat(new UserMessage("Who are you?"))
    ->run();

// 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 registro del número de ejecuciones de herramientas para detener la ejecución si el [maxRuns](/neuron-v3-es/agente/tools.md#max-runs) límite es alcanzado. Puedes acceder a este mapa:

```php
$state = MyAgent::make()
    ->chat(new UserMessage("Who are you?"))
    ->run();

// 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 `UserMessage` instancia al agente y recuperamos el mensaje de respuesta, que será una `AssistantMessage` instancia. Una lista de mensajes del asistente y mensajes del usuario crea un chat.

Aprenderemos más sobre [ChatHistory](/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="/neuron-v3-es/agente/messages.md" class="button primary" data-icon="arrow-right-long">Más información sobre los mensajes</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()
    ->setAiProvider(
        new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        )
    )
    ->setInstructions(
        "Nuevas instrucciones del sistema..."
    )
    ->addTool([...]);
    
$message = $agent->chat(new UserMessage(...))->getMessage();
echo $message->gentContent();
```