> 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/messages.md).

# 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 diferentes formatos de respuesta de OpenAI, Anthropic, Gemini, Ollama y muchos otros proveedores, los desarrolladores trabajan con una abstracción única y elegante que maneja toda la complejidad detrás de escena. 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 para capitalizar de inmediato estas mejoras sin emprender un gran proyecto de refactorización.

**La capa de mensajería va más allá del simple contenido de texto y proporciona 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 salida de los modelos, y contienen 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 el mensaje del asistente como respuesta.

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

$response = MyAgent::make()
    ->setThreadId('chat_id')
    ->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 el modelo genera para responder a tu prompt. Los mensajes pueden tener una lista de objetos que extienden la `ContentBlock` interfaz. Neuron proporciona tipos de contenido dedicados para texto, imagen, archivo, audio y video.

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

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

```php
$response = MyAgent::make()
    ->setThreadId('chat_id')
    ->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:

```php
$response = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("..."))
    ->getMessage();

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

{% hint style="info" %}

#### Verificar las capacidades del modelo

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

### 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:

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

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

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

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

// Obtener todos los bloques de texto concatenados
echo $message->getContent();
// Hola mi nombre es John. Recuerda responder como si fueras un concierge 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 final en texto. Neuron lo captura automáticamente a partir de la respuesta del modelo:

```php
// Chatear 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.

```php
use NeuronAI\Chat\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

```php
use NeuronAI\Chat\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 generar un gran ahorro en el consumo de tokens y mejorar el tiempo de respuesta del modelo.

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

```php
// Referenciar un ID de archivo previamente subido 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

```php
use NeuronAI\Chat\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

```php
use NeuronAI\Chat\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::MP4
    )
);

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