Actualización

Actualizar a la v3 desde la v2

En esta nueva versión mayor, las APIs públicas de los componentes de Neuron no cambiaron drásticamente (minimizamos el impacto tanto como fue posible), pero la arquitectura subyacente de Agent, RAG y el sistema de mensajes se ha reconstruido por completo sobre el componente Workflow, que ahora impulsa todo el framework.

Ahora Agent y RAG ya no son objetos simples, sino flujos de trabajo. Heredan funciones que eran imposibles de integrar en la implementación independiente anterior, como:

• El sistema unificado de mensajería para agentes multimodales

• Compatibilidad nativa con aprobación de herramientas y flujos human-in-the-loop totalmente personalizables

• Multiagente streaming y colaboración.

También aprovechamos esta versión para corregir otros problemas críticos de diseño surgidos en la v2, como la compatibilidad completa con modelos de razonamiento en todos los proveedoresy otras mejoras de diseño para tener más libertad de evolucionar el framework con menos cambios incompatibles en el futuro.

Seguimos trabajando para ofrecer la mejor experiencia posible para desarrolladores, y ayudarte a crear productos de IA exitosos en PHP.

Actualización de dependencias

Debes actualizar las siguientes dependencias en el composer.json archivo de tu aplicación:

• neuron-core/neuron-ai a ^3.0

Cambios de alto impacto

Nuevo espacio de nombres de Agent

La clase Agent y las clases y traits relacionados se han movido del directorio raíz al espacio de nombres dedicado NeuronAI\Agent.

Debes actualizar el espacio de nombres en los archivos donde uses la clase Agent, de:

use NeuronAI\Agent;

A:

use NeuronAI\Agent\Agent;

Lo mismo para la clase SystemPrompt. El nuevo espacio de nombres es NeuronAI\Agent\SystemPrompt.

Eliminar chatAsync()

El chatAsync() el método fue eliminado por completo de AgentInterface. Si estás usando este método en tu aplicación, tienes que cambiar al nuevo patrón asíncrono.

Aprende sobre Async

Tipo de retorno de Agent

Como Agent ahora es un flujo de trabajo, tienes APIs ligeramente diferentes para ejecutar realmente el agente y recuperar la respuesta del LLM.

Anteriormente obtenías directamente una instancia de Message desde el chat() método. Ahora el método chat devuelve un estado de flujo de trabajo que puedes usar para recuperar la respuesta final del agente.

El estado del agente devuelto te permite acceder fácilmente a la respuesta del LLM, pero también hace posible inspeccionar otros aspectos de la ejecución interna del agente. Aquí tienes un ejemplo de la nueva sintaxis para ejecutar un agente y mostrar el contenido generado por el LLM.

// Las versiones anteriores de chat() devuelven la respuesta del LLM
$message = MyAgent::make()->chat(new UserMessage("Hola, ¿quién eres?"));

// V3 - necesitas llamar a "getMessage()"
$message = MyAgent::make()
    ->chat(new UserMessage("Hola, ¿quién eres?"))
    ->getMessage();

echo $message->getContent();

Bloques de contenido de mensajes

Los bloques de contenido ahora reemplazan el antiguo enfoque basado en "adjuntos". El sistema heredado de adjuntos ha sido eliminado. Para migrar:

Enfoque antiguo (ya no disponible):

$message = new UserMessage('Analiza esto');
$message->addAttachment(new Image($url, AttachmentContentType::URL));

Nuevo enfoque:

// Mensaje de texto simple (compatible con versiones anteriores)
$message = new UserMessage("Hola");

// Nuevo formato para pasar imágenes, archivos, etc.
$message = new UserMessage([
    new TextBlock('Analiza esto'),
    new ImageBlock($url, SourceType::URL)
]);

// Añadir más bloques
$message->addContent(
    new TextBlock('Recuerda responder como si fueras un conserje profesional.')
);

// Imprimir todos los bloques de contenido de texto
echo $message->getContent();

El método getContent() no cambió, pero ahora devuelve todos los bloques de texto concatenados, omitiendo los tipos multimedia.

La composición de bloques desbloquea la compatibilidad multimodal y puede ser muy útil si necesitas inyectar instrucciones o indicaciones adicionales de forma dinámica durante la ejecución.

Aprende sobre Mensajes

Fragmentos de streaming

En versiones anteriores, la interfaz de streaming devolverá una cadena simple para cada fragmento de respuesta del LLM, y ToolCallMessage, o ToolCallResultMessage instancias directamente para operaciones relacionadas con herramientas. Esto crea un acoplamiento demasiado directo entre las instancias de mensaje y tu aplicación al leer el stream.

Implementamos clases de fragmento dedicadas TextChunk, ReasoningChunk, ToolCallChunk, ToolResultChunky otras, para tener contenedores dedicados para cada tipo de delta del stream. Esta separación más clara de responsabilidades abrió la puerta a la implementación del sistema de adaptadoresy nos da más libertad para mejorar esta capa en el futuro con menos cambios incompatibles en el sistema unificado de mensajes.

ToolCallChunk

En la versión anterior, Neuron transmitía directamente el ToolCallMessage instancia con la lista de herramientas involucradas en la iteración. Ahora obtienes una ToolCallChunk dedicada para cada herramienta que el modelo está solicitando ejecutar.

Leer más sobre streaming

Salida estructurada

Ampliamos el papel del SchemaProperty atributo para que sea la fuente de verdad de la definición del esquema JSON de una propiedad de clase. Ahora admite mín, máx, longitud mínima, longitud máxima, anyOf.

use NeuronAI\StructuredOutput\SchemaProperty;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.',
        required: true,
        minLength: 3,
        maxLength: 255,
    )]
    public string $name;
    
    #[SchemaProperty(
        description: 'Lo que al usuario le encanta comer.', 
        required: false,
        min: 18,
        max: 64,
    )]
    public ?int $age = null;
}

Array de objetos

Si una propiedad es un array de un objeto estructurado, ya no necesitas especificar el doc-block de los tipos de propiedad; solo tienes que listarlos en el anyOf argumento:

class Report
{
    #[SchemaProperty(
        description: 'El contenido del informe', 
        required: true,
        anyOf: [TextBlock::class, TableBlock::class, ImageBlock::class]
    )]
    public array $content;
}

Salida estructurada

Solicitud de interrupción del flujo de trabajo (humano en el proceso)

En la versión anterior, cuando solicitabas una interrupción dentro de un Node, podías pasar un array de datos para informar al cliente sobre el motivo y las acciones detrás de la interrupción.

Sintaxis antigua

$feedback = $this->interrupt(['message' => '¿quieres aprobarlo?']);

Este método con tipado perezoso provocó inconsistencias y errores. Introdujimos el InterruptRequest primitivo para ayudarte a crear flujos de interrupción con una estructura tipada para una integración segura en la UI.

Nueva sintaxis

$feedback = $this->interrupt(new ApprovalRequest(
    reason: '¿Quieres aprobarlo?',
    actions: [
        new Action(...)
    ]
));

Aprende más en la sección dedicada de la documentación.

Interrupción del flujo de trabajo

Cambio en la persistencia de la base de datos del flujo de trabajo

El nombre de las columnas de la tabla de persistencia de la base de datos del flujo de trabajo cambió:

• data -> interrupt

Persistencia del flujo de trabajo

Impacto medio

Renombrar ToolCallResultMessage

Esta clase fue renombrada a ToolResultMessage.

Monitorización y observadores

Las entidades Agent, RAG y Workflow ya no implementan la interfaz de PHP \SplSubject y las clases observer ya no implementan la \SplObserver interfaz. Introdujimos la nueva ObserverInterface que debe ser implementada solo por escuchadores de eventos como LogObserver. Esta estructura más ligera nos ayudó a hacer observables los bloques de construcción del flujo de trabajo, como Workflow, node y middleware. Esto significa que puedes emitir eventos desde tus nodos personalizados, y solo necesitas crear y registrar tu observer personalizado para escuchar estos eventos.

Lee más en la sección de Monitorización.

Eliminar HttpClientOptions

Esta clase fue eliminada a favor de una abstracción completa del HttpClient dentro del framework. Adoptamos un patrón de adaptadores para permitirte inyectar clientes HTTP personalizados en los componentes del framework y personalizar su configuración. El adaptador del cliente Guzzle también admite stack de handlers, encabezados personalizados, etc.

Puedes ver un ejemplo de cómo personalizar la configuración del cliente HTTP en la Async sección.

Qdrant 1.10.x

Los componentes del almacén vectorial de Qdrant se actualizaron para admitir las nuevas APIs de consulta que están incluidas a partir de la versión 1.10.x. Si usas una versión anterior de la base de datos Qdrant, necesitas actualizar tu instancia.

Firma de los métodos de AbstractChatHistory

Si has implementado un componente personalizado de historial de chat, necesitas ajustar la firma de los métodos hook. Cambiaron el nivel de visibilidad, de public a protected, y ya no tienen tipo de retorno:

class MyChatHistory extends AbstractChatHistory
{
    protected function setMessages(array $messages): void
    {
        // Gestiona el guardado de todo el historial de una vez.
    }

    protected function onNewMessage(Message $message): void
    {
        // Gestiona la adición de un solo mensaje.
    }

    protected function onTrimHistory(int $index): void
    {
        // Cuando se activa el recorte, los mensajes en la posición desde cero hasta $index deben eliminarse.
    }

    protected function clear(): void
    {
        // Elimina todos los mensajes.
    }
}

Nuevas funciones

Aprobación de herramientas y aprobación condicional

Gracias al patrón human in the loop compatible con la arquitectura subyacente del flujo de trabajo, creamos un middleware integrado para habilitar la aprobación de herramientas en tu agente como una función plug and play:

new ToolApproval(
    tools: [
        BuyTicketTool::class => function (array $args): bool {
            return $args['amount'] > 100;
        }
    ]
)

Aprobación de herramientas

Proveedor dedicado de Mistral

El proveedor de Mistral ya no es una implementación pura de OpenAI, sino que evolucionó con su propia implementación de formato de API para admitir entrada multimodal y modelos de razonamiento.

Proveedor de Mistral AI

Proveedor de Cohere AI

Esta versión incluye un proveedor totalmente nuevo para admitir la plataforma de inferencia de Cohere tanto en la nube como desplegada de forma privada.

Proveedor de Cohere AI

Proveedores de texto a voz

Gracias a la nueva composición de bloques de los mensajes, ahora es fácil tratar con la multimodalidad de entrada y salida. En esta versión incluimos un par de proveedores que puedes usar para procesar contenidos de audio.

Proveedores de texto a voz

Adaptadores de streaming

Los adaptadores actúan como traductores entre los eventos internos de streaming de Neuron (fragmentos de texto, llamadas a herramientas, pasos de razonamiento) y protocolos específicos de frontend como Vercel AI SDK, AG-UI o las necesidades personalizadas de tu frontend.

Esta arquitectura te permite integrar sin problemas los agentes de Neuron con varios frameworks de frontend (React, Vue, etc.) sin modificar la lógica principal de tu agente.

Aprende más sobre Adaptadores

Bloque de contenido de ID de archivo

Normalmente puedes adjuntar archivos a tu mensaje (imágenes o documentos) como URLs, o codificados en formato base64. Muchos proveedores te permiten subir archivos a su plataforma una vez y referenciar esos archivos con un simple ID en el mensaje. Esto puede generar un gran ahorro en el consumo de tokens y puede mejorar el tiempo de respuesta del modelo.

Después de recibir el ID del archivo de la plataforma del proveedor, puedes agregar un bloque de archivo a tu mensaje con SourceType::ID.

// Haz referencia a un ID de archivo cargado previamente en la plataforma del proveedor
$message = new UserMessage([
    new TextBlock('Analiza esto'),
    new FileBlock("file_id_xxxx", SourceType::ID)
]);

Puedes hacer lo mismo con Image, Video, etc., según las especificaciones de tu proveedor.

Middleware

Middleware proporciona una forma de controlar de cerca lo que ocurre dentro del flujo de trabajo y, por lo tanto, también en tus Agents y RAGs, ya que ahora también son flujos de trabajo.

La ejecución central del Workflow implica llamar a nodos según los eventos devueltos por otros nodos. Middleware expone ganchos para intervenir en antes y después la ejecución de los nodos:

Esta arquitectura se ha utilizado para crear los middlewares integrados para la clase Agent, como la resumización del contexto o la aprobación de herramientas.

Aprende más sobre Middleware