> 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

## 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 muchísimos otros proveedores, los desarrolladores trabajan con una única y elegante abstracción que gestiona toda la complejidad entre bastidores. Tu código se vuelve independiente del motor LLM específico que utilices.

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 estas mejoras de inmediato sin emprender un gran proyecto de refactorización.

**La capa de mensajería va más allá del simple contenido de texto y ofrece 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, transportando 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 (p. ej., 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 la respuesta del LLM.

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

```php
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 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 en un mensaje usando `getContentBlocks()` método:

```php
$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 todos los contenidos textuales concatenados:

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

// Obtén 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 cadena simple como argumento del constructor, o agregar explícitamente un `TextContent` bloque:

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

// Al pasar una cadena en el constructor, se agregará el primer TextContentBlock al mensaje
$message = new UserMessage("Hola");

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

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

// Obtén todos los bloques de texto concatenados
echo $message->getContent();
// Hola, mi nombre es John. Recuerda responder como si fueras un conserje profesional.

// O bien obtén el array de bloques de contenido de texto
$blocks = $message->getTextBlocks();
```

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

### Razonamiento

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

```php
// Chatea 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\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: 'image/png'
    )
);

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

### Archivo

```php
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: 'application/pdf'
    )
);

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

### ID del 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 hacer referencia a esos archivos con un simple ID en el mensaje. Esto puede desbloquear 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`.

```php
// 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, o Video, etc., según las especificaciones de tu proveedor.

### Audio

```php
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: 'audio/mpeg3'
    )
);

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

### Video

```php
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: 'video/mp4'
    )
);

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