> 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

### Introducción

Puedes crear tu agente ampliando la `NeuronAI\Agent\Agent` clase para heredar las funciones principales del framework y crear agentes totalmente 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.

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 favorece la portabilidad, porque todas las piezas móviles están encapsuladas 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 vídeos 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 (string) new SystemPrompt(
            background: ["Eres un agente de IA amable creado con el framework Neuron."],
        );
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

### Monitorización y depuración

Muchas de las aplicaciones que construyas con Neuron contendrán varios 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()` devolviendo la instancia del proveedor que quieras 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 (string) new SystemPrompt(
            background: ["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 o Ollama si quieres ejecutar el modelo localmente. Consulta los [proveedores compatibles](/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 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 en la entidad 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 de 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 vídeos de YouTube."],
            steps: [
                "Obtén la URL de un vídeo de YouTube, o pide al usuario que proporcione una.",
                "Usa las herramientas disponibles para recuperar la transcripción del vídeo.",
                "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 vídeo.",
            ]
        );
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

El `SystemPrompt` clase está diseñada para tomar tus instrucciones base y construir un prompt coherente para el modelo subyacente, reduciendo el esfuerzo de la ingeniería de prompts. Las propiedades tienen el siguiente significado:

* **background**: Escribe sobre el papel del Agente. Piensa en las tareas macro que está destinado a realizar.
* **steps**: Define la forma en que esperas que se comporte el Agente. Varios pasos ayudan al Agente a actuar de forma consistente.
* **output**: Define cómo quieres que responda el agente. Sé explícito en el formato que esperas.

Recomendamos encarecidamente usar la `SystemPrompt` clase para aumentar la calidad de los resultados; alternativamente, puedes devolver simplemente una cadena:

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;

class YouTubeAgent extends Agent
{
    ...
    
    protected function instructions(): string
    {
        return "Eres un agente de IA especializado en escribir resúmenes de vídeos de YouTube.";
    }
}
```

### Habla con el Agente

Estamos listos para probar cómo responde el agente a nuestro mensaje según las nuevas instrucciones.

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

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

### Estado del agente

Dado que el Agente es una extensión del Workflow, en lugar de obtener la última respuesta del modelo con la `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 sucedió durante la ejecución del agente.

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

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

#### Pasos

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

```php
$state = MyAgent::make()
    ->chat(new UserMessage("¿Quién eres?"))
    ->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 lleva un seguimiento 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 se alcanza. Puedes acceder a este mapa:

```php
$state = MyAgent::make()
    ->chat(new UserMessage("¿Quién eres?"))
    ->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 de 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="/pages/486423c4246cb85a9e7816bfb932ace3778a684a" 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()
    ->setAiProvider(
        new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        )
    )
    ->setInstructions(
        (string) new SystemPrompt(...)
    )
    ->addTool([...]);
    
$message = $agent->chat(new UserMessage(...))->getMessage();
echo $message->gentContent();
```