Mensajes

Unidad de contexto unificada entre proveedores de IA y LLM.

La capa unificada de mensajería

Una de las principales ventajas de la arquitectura de Neuron es la capa unificada de mensajería para interactuar con múltiples proveedores de IA. En lugar de lidiar con los distintos formatos de respuesta de OpenAI, Anthropic, Gemini, Ollama y muchos otros proveedores, los desarrolladores trabajan con una única y elegante abstracción que maneja toda la complejidad entre bastidores. Tu código se vuelve independiente del motor LLM específico que uses.

Cuando integras Neuron Agents en tu aplicación, no quedas atado al ecosistema ni al modelo de precios de ningún proveedor específico. Puedes cambiar sin problemas entre proveedores para gestionar costos, entornos o aprovechar nuevos lanzamientos de modelos y capitalizar estas mejoras de inmediato sin emprender un gran proyecto de refactorización.

La capa de mensajería va más allá del contenido de texto simple, proporcionando interfaces unificadas para entrada/salida multimodal (archivo, imagen, video, audio) en todos los proveedores compatibles, incluso cuando las implementaciones subyacentes varían drásticamente. Esta decisión arquitectónica significa que tus agentes de IA siguen siendo portables y preparados para el futuro: cuando surgen nuevos proveedores o los existentes actualizan sus API, el código de tu aplicación permanece sin cambios mientras la capa de mensajería de Neuron absorbe toda la complejidad de adaptación.

¿Qué es un mensaje?

Los mensajes son la unidad fundamental de contexto. Representan la entrada y la salida de los modelos, y llevan tanto el contenido como los metadatos necesarios para representar el estado de una conversación al interactuar con un LLM.

Los mensajes son objetos que contienen:

• Rol - Identifica el tipo de mensaje (por ejemplo, usuario, asistente)

• Bloques de contenido - Representa el contenido real del mensaje (como texto, imágenes, audio, archivos, etc.)

• Metadatos - Campos opcionales, como información adicional de respuesta del LLM.

Aquí tienes un ejemplo de cómo enviar un mensaje de usuario al agente y obtener de vuelta el mensaje del asistente como respuesta.

use NeuronAI\Chat\Messages\UserMssage;

$response = MyAgent::make()
    ->chat(new UserMessage("Hola, ¿quién eres?"))
    ->getMessage();

echo $response->getContent();

Bloques de contenido

Puedes pensar en el bloque de contenido de un mensaje como la carga útil de datos que se envía al modelo, o que genera el modelo para responder a tu prompt. Los mensajes pueden tener una lista de objetos que extienden la ContentBlock interfaz. Neuron proporciona tipos de contenido específicos para texto, imagen, archivo, audio y video.

El mensaje puede contener una lista arbitraria de bloques, incluso múltiples bloques de cada tipo. Neuron asigna automáticamente los tipos de bloque al formato apropiado para cada proveedor.

Puedes obtener y procesar la lista de bloques en un mensaje usando el método getContentBlocks() de contenido:

$response = MyAgent::make()->chat(...)->getMessage();

foreach ($response->getContentBlocks() as $block) {
    echo match($block::class) {
        ReasoningContent::class => "Razonamiento: ".$block->content."\n\n",
        TextContent::class => $block->content,
        ...
        // otros bloques de contenido 
    };
}

O simplemente usa getContent() para obtener todo el contenido textual concatenado:

$response = MyAgent::make()
    ->chat(new UserMessage("..."))
    ->getMessage();

// Obtener todos los bloques de texto concatenados como una sola cadena
echo $response->getContent();

Verificar las capacidades del modelo

Antes de usar bloques de contenido específicos, debes verificar las capacidades del modelo para interpretar la información que quieres enviar (imagen, audio, video).

Texto

Este bloque representa la parte de texto de un mensaje. Puedes inicializar un mensaje con una simple cadena como argumento del constructor, o añadir explícitamente un TextContent bloque:

use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\TextContent;

// Pasar una cadena en el constructor añadirá el primer bloque TextContent al mensaje
$message = new UserMessage("Hola");

// Añadir otras partes de texto al mensaje
$message->addContent(
    new TextContent("Me llamo John.")
);

$message->addContent(
    new TextContent('Recuerda responder como si fueras un conserje profesional.')
);

// Obtener todos los bloques de texto concatenados
echo $message->getContent();
// Hola me llamo John. Recuerda responder como si fueras un conserje profesional.

// O obtener el array de bloques de contenido de texto
$blocks = $message->getTextBlocks();

Como puedes notar, el mensaje final será una composición de múltiples bloques.

Razonamiento

Este bloque contendrá los pasos de razonamiento que el modelo realizó antes de la respuesta textual final. Neuron lo captura automáticamente a partir de la respuesta del modelo:

// Conversar con un modelo de razonamiento
$response = MyAgent::make()->chat(...)->getMessage();

foreach ($response->getContentBlocks() as $block) {
    echo match($block::class) {
        ReasoningContent::class => "Razonamiento: ".$block->content."\n\n",
        TextContent::class => $block->content,
        ...
        // otros bloques de contenido 
    };
}

Imagen

Para los modelos que admiten multimodalidad puedes adjuntar imágenes y otros tipos de contenido, como archivos, audio y video.

use NeuronAI\Chat\Enum\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\ImageContent;

$message = new UserMessage("Describe esta imagen");

$message->addContent(
    new ImageContent(
        source: 'https://placehold.co/600x400/EEE/31343C',
        sourceType: SourceType::URL,
        mediaType: MediaType::PNG
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response->getContent();

Archivo

use NeuronAI\Chat\Enum\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\FileContent;

$message = new UserMessage("Resume este documento");

$message->addContent(
    new FileContent(
        source: base64_encode(file_get_contents(__DIR__.'/invoice.pdf')),
        sourceType: SourceType::BASE64,
        mediaType: MediaType::PDF
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response->getContent();

ID de archivo

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

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

// Hacer referencia a un ID de archivo previamente cargado 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 o Video, etc., según las especificaciones de tu proveedor.

Audio

use NeuronAI\Chat\Enum\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\AudioContent;

$message = new UserMessage("Transcribe este audio");

$message->addContent(
    new FileContent(
        source: base64_encode(file_get_contents(__DIR__.'/music.mp3')),
        sourceType: SourceType::BASE64,
        mediaType: MediaType::MP3
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response ->getContent();

Video

use NeuronAI\Chat\Enum\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\VideoContent;

$message = new UserMessage("Resume el contenido de esta lección.");

$message->addContent(
    new VideoContent(
        source: base64_encode(file_get_contents(__DIR__.'/lesson_1.mp4')),
        sourceType: SourceType::BASE64,
        mediaType: MediaType::MP$
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response->getContent();