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

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

Te recomendamos encarecidamente extender la clase Agent en lugar de crear agentes usando la definición fluida. Esta estrategia facilita agregar métodos y comportamiento personalizados al agente, y también promueve la portabilidad, porque todas las piezas móviles quedan encapsuladas en una sola entidad que puedes ejecutar donde quieras en tu aplicación, o incluso publicar como un paquete de Composer independiente.

Empecemos creando un Agente de IA que resuma videos de YouTube. Comenzamos creando la YouTubeAgent clase:

Unix

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

Windows

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

El comando creará una clase como esta:

<?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 amable creado con el framework Neuron AI.";
    }
    
    /**
     * @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 vuelvan 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.

Neuron AI | Inspectordocs.inspector.dev

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 a implementar es provider() que devuelve la instancia del proveedor que deseas usar. Supongamos que es Anthropic.

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

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

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 un 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, agrega una lista de tres frases como las tres ideas 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.

use NeuronAI\Chat\Messages\UserMessage;

$message = YouTubeAgent::make()
    ->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

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 crudo del agente. El estado del agente contiene información adicional que puede ayudarte a inspeccionar lo que ocurrió durante la ejecución del agente.

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

// $state es una instancia de la clase NeuropnAI\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 indicación. 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:

$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 el control del número de ejecuciones de herramientas para detener la ejecución si se alcanza el maxRuns límite. Puedes acceder a este mapa:

$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 del usuario crea un chat.

Aprenderemos más sobre ChatHistory más adelante, pero es importante saber que la interfaz unificada para la entrada y salida del agente es el Mensaje objeto.

Más información sobre los mensajes

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:

$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();