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

# Transmisión

Muestra a los usuarios fragmentos del texto de respuesta y de la interfaz a medida que llegan, en lugar de esperar ciegamente la respuesta completa.

<figure><img src="https://4076695836-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2Fgit-blob-81daaa38ae7b2c87f2c759b32da89aaec04af465%2Fgenerative-ui.gif?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Usa **`/neuron-streaming`** para enseñarle a tu agente de programación cómo transmitir la respuesta del agente a la interfaz de usuario.

[Desarrollo asistido por IA](https://docs.neuron-ai.dev/neuron-v3-es/resumen/agentic-development.md)
{% endhint %}

Para transmitir la respuesta de la IA debes usar el `stream()` método en el agente, en lugar de `chat()`. Este método prepara el flujo de trabajo del agente para usar el `StreamingNode` en lugar de `ChatNode`.

Al llamar al `events()` método en el controlador del agente de retorno obtienes un generador de PHP que puede usarse para consumir la transmisión como un objeto iterable.

```php
use App\Neuron\MyAgent;
use NeuronAI\Chat\Messages\UserMessage;

$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->stream(new UserMessage('How are you?'));

// Imprime la respuesta fragmento por fragmento en tiempo real
foreach ($stream as $chunk) {
    echo $chunk->content;
}

// Estoy bien, gracias. ¿Cómo puedo ayudarte hoy?
```

### Fragmentos de transmisión

Cuando procesas la respuesta transmitida del agente, puedes esperar recibir tres tipos de objetos chunk:

* `TextChunk`: representa un fragmento de texto
* `ReasoningChunk`: contiene fragmentos del resumen de razonamiento del modelo (solo disponible para modelos de razonamiento)
* `ToolCallChunk`: representa que el LLM solicita la ejecución de una herramienta
* `ToolResultChunk`: contiene los resultados de la ejecución de la herramienta

Estos objetos son una capa de abstracción entre el flujo de mensajes subyacente dentro del agente para realizar una tarea y los datos necesarios en el lado del cliente para mantenerse informado sobre lo que ocurre detrás de escena.

La composición de la transmisión depende de la implementación de tu agente. Si el agente no tiene herramientas conectadas, no hay posibilidad de recibir una `ToolCallChunk` o `ToolResultChunk` instancia, así que puedes iterar sobre la salida transmitida esperando solo fragmentos de texto y de razonamiento.

### Transmisión y herramientas

Neuron admite herramientas y llamadas a funciones en combinación con la respuesta transmitida. Eres libre de proporcionar herramientas a tus agentes y se gestionarán automáticamente en medio de la transmisión, para continuar hacia la respuesta final.

Cuando el agente recibe una solicitud de llamada a una herramienta desde el LLM, transmitirá dos tipos de chunk: `ToolCallChunk`, `ToolResultChunk`.

Estas clases contienen la instancia de la herramienta llamada por el LLM, para que puedas mostrar información útil al cliente sobre lo que el agente está haciendo para responder al mensaje del usuario.

Aquí tienes un ejemplo de cómo puedes manejar este escenario:

```php
use App\Neuron\MyAgent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Tools\Tool;

$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->addTool(
        Tool::make(
            'get_server_configuration',
            'recuperar la configuración de red del servidor'
        )->addProperty(...)->setCallable(...)
    )
    ->stream(
        new UserMessage("¿Cuál es la dirección IP del servidor?")
    );

// Iterar sobre los chunks
foreach ($stream as $chunk) {
    if ($chunk instanceof ToolCallChunk) {
        // Mostrar la llamada a la herramienta en curso
        echo "\n- Llamando a la herramienta: ".$chunk->tool->getName();
        echo "\n- Entrada: ".json_encode($chunk->tool->getInputs());
        continue;
    }
    
    if ($chunk instanceof ToolResultChunk) {
        echo "\n- La herramienta ".$chunk->tool->getName()." se completó";
        echo "\n- Resultado: ".$chunk->tool->getResult();
        continue;
    }
    
    // Manejar TextChunk y ReasoningChunk
    echo $chunk->content;
}

// Déjame recuperar la configuración del servidor. 
// - Llamando a la herramienta: get_server_configuration
// - La herramienta get_server_configuration se completó
// La dirección IP del servidor es: 192.168.0.10
```

### Obtener el resultado final

Cuando el modelo termine de transmitir la salida, puedes recuperar el `AssistantMessage` instancia con el `getMessage()` método en el controlador del flujo de trabajo:

```php
$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->stream(...);

// Iterar sobre los chunks
foreach ($stream as $chunk) {
    // ...
}

$message = $stream->getResult()->getMessage(); // Obtener la instancia del mensaje final
echo $message->getContent();
```

### 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 vuelven 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](https://inspector.dev/)

{% embed url="<https://docs.inspector.dev/guides/neuron-ai>" %}

## Adaptadores de flujo

El sistema de adaptadores de flujo de Neuron proporciona una forma flexible e independiente del protocolo para ayudarte a integrar fácilmente agentes impulsados por Neuron con tu pila frontend.

Los adaptadores de flujo traducen los eventos internos de transmisión de Neuron (fragmentos de texto, llamadas a herramientas, pasos de razonamiento) a eventos de protocolos frontend específicos como AG-UI.

Esta arquitectura te permite integrar sin problemas agentes de Neuron con varios frameworks frontend sin modificar la lógica central de tu agente. Los adaptadores manejan aspectos específicos del protocolo como eventos del ciclo de vida de los mensajes, formato de eventos y seguimiento de IDs, mientras mantienen un comportamiento de transmisión coherente en todos los proveedores (Anthropic, OpenAI, Gemini, Ollama, etc.). El sistema es altamente extensible, puedes crear adaptadores personalizados extendiendo `SSEAdapter` para implementar transformaciones de datos de transmisión, o implementar directamente la `StreamAdapterInterface` para necesidades personalizadas.

<figure><img src="https://4076695836-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2F0Vv4CSAloxu40vUoZddx%2Fstreaming-adapter.png?alt=media&amp;token=eb8846c3-eef5-415a-bb2e-108f1ecd0cf2" alt=""><figcaption></figcaption></figure>

Solo necesitas proporcionar una instancia de adaptador al `stream()` método del agente usado para transmitir la respuesta del LLM.

### Adaptador del Vercel AI SDK

Adaptador para el protocolo de flujo de datos del Vercel AI SDK: <https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol>

```php
use NeuronAI\Chat\Messages\Stream\Adapters\VercelAIAdapter;

// Instruye al agente
$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->setStreamAdapter(new VercelAIAdapter())
    ->stream(
        new UserMessage('¿Cuál es la raíz cuadrada de 144?')
    );

// Procesar la respuesta
foreach ($stream as $line) {
    echo $line;
}
```

### Adaptador AG-UI

Implementa el protocolo basado en eventos de transmisión definido por el protocolo AG-UI para interacción en tiempo real entre agente e interfaz. Admite mensajes de texto, llamadas a herramientas, razonamiento y eventos del ciclo de vida.

Para más información, visita: <https://docs.ag-ui.com/concepts/events>

```php
use NeuronAI\Chat\Messages\Stream\Adapters\AGUIAdapter;

// Instruye al agente
$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->setStreamAdapter(new AGUIAdapter('chat_id'))
    ->stream(
        new UserMessage('¿Cuál es la raíz cuadrada de 144?')
    );

// Procesar la respuesta
foreach ($stream as $line) {
    echo $line;
}
```

#### Conectando un frontend AG-UI

Un cliente AG-UI (como CopilotKit) no solo abre una conexión. Envía una solicitud POST con un cuerpo JSON llamado `RunAgentInput`, que contiene la conversación y los identificadores de la ejecución actual:

```json
{
  "threadId": "thread_123",
  "runId": "run_456",
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "content": "What is the square root of 144?"
    }
  ],
  "tools": [],
  "state": {},
  "context": [],
  "forwardedProps": {}
}
```

Tu endpoint debe leer esta carga útil, mapear los mensajes a objetos de mensaje de Neuron y pasar `threadId` y `runId` al constructor del adaptador. El adaptador los devuelve en los `RUN_STARTED` y `RUN_FINISHED` eventos, para que el cliente pueda correlacionar la transmisión con la ejecución que solicitó. Si los omites, el adaptador genera sus propios identificadores (útil para pruebas, pero un frontend AG-UI real espera recibir sus propios IDs).

El adaptador también proporciona las cabeceras HTTP requeridas por el transporte SSE mediante el `getHeaders()` método. Recuerda enviarlas y vaciar la salida después de cada línea; de lo contrario, la transmisión puede quedarse atascada en los buffers de salida de PHP o en proxies.

Aquí tienes un ejemplo completo de endpoint:

```php
use NeuronAI\Chat\Messages\Stream\Adapters\AGUIAdapter;
use NeuronAI\Chat\Messages\UserMessage;

// Analizar la carga útil de AG-UI RunAgentInput
$input = json_decode(file_get_contents('php://input'), true);

$messages = [];
foreach ($input['messages'] as $message) {
    if ($message['role'] === 'user') {
        $messages[] = new UserMessage($message['content']);
    }
}

// Devolver al stream los identificadores de hilo y ejecución del cliente
$adapter = new AGUIAdapter(
    threadId: $input['threadId'],
    runId: $input['runId'],
);

// Enviar las cabeceras SSE requeridas por el protocolo
foreach ($adapter->getHeaders() as $name => $value) {
    header("{$name}: {$value}");
}

$stream = MyAgent::make()
    ->setStreamAdapter($adapter)
    ->stream($messages);

foreach ($stream as $line) {
    echo $line;
    flush();
}
```

El adaptador traduce los fragmentos de transmisión de Neuron a los siguientes eventos AG-UI:

Las herramientas conectadas a un agente de Neuron se ejecutan en el servidor. El cliente se informa de la ejecución en curso a través de los `TOOL_CALL_*` eventos y recibe la salida de la herramienta en el `TOOL_CALL_RESULT` evento, seguido del mensaje de texto final del agente. Las herramientas definidas en el frontend y listadas en `tools` campo de `RunAgentInput` (herramientas ejecutadas por el cliente) no son gestionadas por el adaptador.

El adaptador no emite los eventos de estado compartido de AG-UI (`STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`), por lo que las funciones de sincronización de estado de los clientes AG-UI no están disponibles a través de este adaptador.

### Eventos personalizados

Ambos adaptadores entienden eventos portables de paso, actividad y personalizados. AG-UI usa sus eventos nativos `STEP_STARTED`, `STEP_FINISHED`, `ACTIVITY_SNAPSHOT`, y `CUSTOM` events. Vercel emite partes transitorias `data-*` por lo que la información intermedia está disponible en la UI sin añadirse al historial de mensajes del asistente.

Mapea un evento de la aplicación por su clase exacta cuando el código del dominio deba permanecer independiente de los objetos de eventos portables de Neuron:

```php
use NeuronAI\Chat\Messages\Stream\Adapters\Events\ActivityStreamEvent;
use NeuronAI\Chat\Messages\Stream\Adapters\VercelAIAdapter;

$adapter = (new AGUIAdapter())->mapEvent(
    IndexingProgress::class,
    static fn (IndexingProgress $event): ActivityStreamEvent =>
        new ActivityStreamEvent(
            id: $event->jobId,
            type: 'indexing',
            data: [
                'processed' => $event->processed,
                'total' => $event->total,
            ],
        ),
);
```

La devolución de la función de retorno es un evento portable, nunca SSE, JSON ni un array específico del protocolo. Devuelve `null` para suprimir el evento mapeado explícitamente. Los mapeos coinciden exactamente por clase, por lo que un mapeo de clase padre no captura silenciosamente a las subclases.

### Adaptadores personalizados

El `stream()` método del controlador del agente acepta una instancia de `StreamAdapterInterface`. Así que eres libre de implementar esta interfaz con una implementación personalizada y pasarla al controlador. Así es como se ve la interfaz:

```php
interface StreamAdapterInterface
{
    /**
     * Iniciar un segmento de ejecución. El flujo de trabajo lo llama antes de start() en cada
     * segmento, por lo que una instancia puede servir a una suspensión y a su continuación
     * en el mismo proceso: descarta el estado de flujo del segmento anterior, conserva
     * la identidad y la instantánea del protocolo sembradas.
     */
    public function reset(): void;
    
    /**
     * Transforma un chunk de Neuron en eventos de protocolo.
     *
     * @param object $chunk Chunk de Neuron (TextChunk, ToolCallChunk, etc.) u objetos personalizados
     * @return iterable<ProtocolEvent> Cero o más eventos
     */
    public function transform(object $chunk): iterable;

    /**
     * Secuencia de inicialización del protocolo (opcional).
     *
     * @return iterable<ProtocolEvent>
     */
    public function start(): iterable;

    /**
     * Secuencia de terminación del protocolo (opcional).
     *
     * @return iterable<ProtocolEvent>
     */
    public function end(): iterable;

    /**
     * Secuencia de suspensión del protocolo, consumida en lugar de end() cuando la ejecución
     * se pausa para una entrada externa.
     *
     * Los adaptadores codifican las solicitudes activas para que el cliente sepa a qué está esperando la ejecución,
     * incluidas las tramas de terminación. Devuelve un iterable vacío si el protocolo no puede expresar una pausa.
     * @param array<int, InterruptRequest> $requests Las solicitudes activas, indexadas por ID de interrupción.
     *
     * @param array<int, InterruptRequest> $requests Las solicitudes activas, indexadas por ID de interrupción.
     * @return iterable<ProtocolEvent>
     */
    public function interrupt(array $requests): iterable;

    /**
     * Secuencia de fallo del protocolo, consumida en lugar de end() cuando falla la transmisión.
     *
     * Los adaptadores codifican el error original para su protocolo, incluidas las tramas de terminación.
     * Devuelve un iterable vacío si no se necesita salida de fallo.
     *
     * @return iterable<ProtocolEvent>
     */
    public function error(Throwable $error): iterable;
}
```

Siempre puedes inspirarte en las implementaciones integradas.

## Canales de transmisión

A medida que los agentes se vuelven más interactivos y capaces, los desarrolladores de aplicaciones se ven cada vez más obligados a ejecutarlos fuera del ciclo de vida de la solicitud HTTP debido a sus límites de tiempo de espera, lo que deja la salida transmitida sin forma de llegar a la interfaz. Los canales entregan la salida transmitida de los Agentes y Flujos de trabajo a la interfaz de usuario mediante sistemas de difusión externos como [Pusher](https://pusher.com/), websockets, una cola de Redis o cualquier cosa que ya use tu aplicación.

### El problema que resuelve

Hay dos formas de ejecutar un Agente. Puedes consumir sus eventos en tiempo real:

```php
foreach ($agent->events() as $event) {
    // manejar cada elemento transmitido
}
```

o puedes simplemente pedir el resultado final:

```php
$state = $agent->setThreadId('chat_id')->chat(new UserMessage(...));
```

El primer estilo funciona bien cuando el código de tu aplicación mantiene el flujo desde el principio hasta el final, como un controlador que mantiene abierta la conexión HTTP e imprime cada fragmento en el navegador.

El problema aparece cuando nadie está sosteniendo la transmisión. Piensa en un Agente ejecutándose en un trabajo en segundo plano. El trabajo llama `events()`, el agente produce fragmentos, pero no hay ningún navegador conectado a ese proceso. Sin un Channel, toda esa salida simplemente se descarta.

Los Channels reenvían automáticamente los eventos transmitidos a un transporte personalizado: un websocket, una cola de Redis, una respuesta SSE, lo que quieras, para transmitir resultados en tiempo real a tu aplicación web desde un proceso en segundo plano.

Recuerda que se requiere un adaptador de transmisión para usar channels. Si quieres reenviar los chunks nativos de Neuron al canal, puedes usar el integrado `NeuronAI\Agent\Adapter\AgentChunkAdapter`.

### Adjuntar un canal

Adjuntas un Channel implementando el `channel()` método en la clase Agent, o usando `setChannel()` directamente en la instancia del Agent.

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Channel\CallbackChannel;
use NeuronAI\Workflow\Persistence\FilePersistence;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        // O adaptadores especializados de protocolos de interfaz de usuario
        return new AgentChunkAdapter();
    }
    
    protected function channel(): ?StreamingChannelInterface
    {
        return new PusherChannel(
            client: new Pusher(...),
            channel: 'PUSHER_CHANNEL_NAME'
        );
    }
}

// Ejecutar el agente
MyAgent::make()->stream(new UserMessage('Hi'));
```

### CallbackChannel

La forma más rápida de empezar es `CallbackChannel`. Agrupa hasta cuatro cierres, uno por cada método de la interfaz. Todos son opcionales. Aquí tienes un ejemplo completo que publica cada elemento transmitido en Redis, para que un servidor websocket pueda reenviarlo al navegador:

```php
use NeuronAI\Workflow\Channel\CallbackChannel;
use NeuronAI\Workflow\Persistence\FilePersistence;

$agent = MyAgent::make()
    ->setThreadId('chat_id')
    ->setChannel(new CallbackChannel(
        onSend: function (ProtocolEvent $item) use ($redis): void {
            $redis->publish('thread-123', serialize($item));
        },
    ));

$agent->stream(new UserMessage('Hi'));
```

Ahora no importa si `stream()` lo llama un controlador, un trabajador de cola o un trabajo cron. Los chunks siempre llegan a Redis y, desde allí, a tu frontend.

También puedes reaccionar a las llamadas terminales. Este ejemplo notifica al frontend cuando la ejecución se pausa para aprobación, finaliza o falla:

```php
use NeuronAI\Workflow\Channel\CallbackChannel;
use NeuronAI\Workflow\Interrupt\InterruptRequest;
use NeuronAI\Workflow\WorkflowState;

$channel = new CallbackChannel(
    onSend: fn (ProtocolEvent $item) => $redis->publish(
        'thread-123', 
        json_encode($item)
    ),
    onInterrupted: fn (InterruptRequest $request, string $runId) => $redis->publish(
        'thread-123',
        json_encode(['type' => 'interrupted', 'runId' => $runId])
    ),
    onCompleted: fn (WorkflowState $state, string $runId) => $redis->publish(
        'thread-123',
        json_encode(['type' => 'completed', 'runId' => $runId])
    ),
    onFailed: fn (\Throwable $e, string $runId) => $redis->publish(
        'thread-123',
        json_encode(['type' => 'failed', 'runId' => $runId, 'message' => $e->getMessage()])
    ),
);

MyAgent::make()
    ->setChannel($channel)
    ->stream(new UserMessage('Hi'));
```

### Pusher

Puedes transmitir la salida del Agente al frontend a través de Pusher, o de servidores compatibles con Pusher.

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Streaming\Channel\PusherChannel;
use NeuronAI\Workflow\Streaming\Channel\StreamingChannelInterface;
use Pusher\Pusher;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        // O adaptadores especializados de protocolos de interfaz de usuario
        return new AgentChunkAdapter();
    }
    
    protected function channel(): StreamingChannelInterface
    {
        return new PusherChannel(
            client: new Pusher(...),
            channel: 'PUSHER_CHANNEL_NAME',
            maxRequestBytes: 10_000,
            batchSize: 10
        );
    }
}
```

**`maxRequestBytes`** te permite ajustar la compatibilidad del componente con servidores compatibles con Pusher. Su valor predeterminado de 10 KB es adecuado para Pusher, pero otros servidores podrían admitir un tamaño de solicitud diferente.

**`batchSize`** te permite definir cuántos eventos deben recopilarse antes de enviarlos en una sola solicitud por lotes. Valores más altos hacen que la ejecución del backend fluya mejor, pero pueden resultar en una experiencia frontend más dispersa. Valores más bajos hacen que la experiencia frontend fluya mejor, enviando más solicitudes en el backend.

{% hint style="warning" %}
Usa **`/neuron-streaming`** habilidad o habilidades específicas del framework **`/neuron-laravel-integration`** , **`/neuron-symfony-integration`** para darle a tu agente instrucciones precisas para esta integración.
{% endhint %}

#### Eventos parciales

Pusher limita un evento a 10 KB; Reverb usa el mismo valor por defecto, Soketi a 100 KB, y `maxRequestBytes` (por defecto `10_000`) ajusta el límite.

Para admitir la transmisión cuando tu servidor en tiempo real tiene ese límite, un evento que no cabe en el tamaño máximo - normalmente una llamada a herramienta, un resultado de herramienta o una instantánea de mensaje - se divide en fragmentos consecutivos. Además, los servidores no garantizan que los fragmentos lleguen en orden ni que nunca se intercalen. Por eso el navegador debe ser capaz de reconciliar esta fragmentación y el orden para ofrecer una transmisión coherente a tus componentes de interfaz.

Neuron incluye un módulo Typescript de primera parte que lleva esta capacidad a tu frontend.

Instala el módulo con:

```shellscript
npm install @neuron-core/streaming
```

Consulta la documentación dedicada para integrarlo en tu frontend: <https://www.npmjs.com/package/@neuron-core/streaming>

### Mercure

Puedes transmitir la salida del agente a un Hub de Mercure usando SSE:

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Streaming\Channel\MercureChannel;
use NeuronAI\Workflow\Streaming\Channel\StreamingChannelInterface;
use Pusher\Pusher;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        // O adaptadores especializados de protocolos de interfaz de usuario
        return new AgentChunkAdapter();
    }
    
    protected function channel(): StreamingChannelInterface
    {
        return new MercureChannel(
            hub: new Hub(...),
            topic: 'thread:'.$this->getThreadId(),
            maxRequestBytes: 1_048_576,
            maxRequestsPerSecond: null,
            private: true
        );
    }
}
```

Por defecto `maxRequestsPerSecond` se establece en null, porque las instancias autoalojadas no tienen ningún límite de tasa. Si usas una instancia gestionada en la nube, imponen límites de tasa estrictos de una a veinte solicitudes por segundo según tu plan de suscripción.

Una vez que configuras MercureChannel con la misma restricción que tienes en el servidor Mercure, el componente limita automáticamente el ritmo al que envía eventos y, eventualmente, divide el evento en múltiples fragmentos si el tamaño supera `maxRequestBytes` . El navegador debe ser capaz de reconciliar esta fragmentación y el orden para ofrecer una transmisión coherente a tus componentes de interfaz.

Neuron incluye un módulo Typescript de primera parte que lleva esta capacidad a tu frontend.

Instala el módulo con:

```shellscript
npm install @neuron-core/streaming
```

Consulta la documentación dedicada para integrarlo en tu frontend: <https://www.npmjs.com/package/@neuron-core/streaming>

{% hint style="warning" %}
Usa **`/neuron-streaming`** habilidad o habilidades específicas del framework **`/neuron-laravel-integration`** , **`/neuron-symfony-integration`** para darle a tu agente instrucciones precisas para esta integración.
{% endhint %}

### Redis

`RedisChannel` publica el segmento en un canal Redis Pub/Sub, la difusión habitual entre un trabajador que ejecuta el agente y el proceso que mantiene la conexión del cliente (un endpoint SSE, un servidor websocket). Necesita `ext-redis` y un `Redis` cliente conectado.

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Streaming\Channel\RedisChannel;
use NeuronAI\Workflow\Streaming\Channel\StreamingChannelInterface;
use Redis;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        return new AGUIAdapter($this->getThreadId());
    }
    
    protected function channel(): StreamingChannelInterface
    {
        return new RedisChannel(
            client: new Redis(...), 
            channel: "chat:{$threadId}",
        );
    }
}
```

#### Consumidor de Redis

Con los canales, tu agente envía fragmentos transmitidos a la cola de redis especificada. Así que ahora tu aplicación necesita una forma de escuchar estos fragmentos y reenviar la transmisión al frontend.

`RedisChannelReader` lee lo que `RedisChannel` publica. Un agente que se inició antes de suscribirse, lanza `ChannelReadException`, al igual que el silencio tras su tiempo de espera. Redis entrega los mensajes de un publicador en orden y `RedisChannel` nunca los fragmenta, así que no necesita reordenación ni reensamblado.

```php
(new RedisChannelReader(new Redis(...), 'chat:{$threadId}'))
    ->listen(function (ProtocolEvent $event): void {
        echo SSEEncoder::frame($event);
        if (ob_get_level() > 0) {
            ob_flush();
        }
        flush();
    });
```

{% hint style="warning" %}
Usa **`/neuron-streaming`** habilidad o habilidades específicas del framework **`/neuron-laravel-integration`** , **`/neuron-symfony-integration`** para darle a tu agente instrucciones precisas para esta integración.
{% endhint %}

### Los errores del canal nunca interrumpen la ejecución

Un canal habla con sistemas externos, y los sistemas externos fallan. Un servidor Redis puede estar caído, un socket puede cerrarse. El framework protege la ejecución de esto: cada llamada al canal está protegida. Si tu canal lanza una excepción, el flujo de trabajo la captura, la informa como un `ChannelError` evento a través del sistema de observabilidad y continúa la ejecución como si nada hubiera pasado.

Esto significa que el trabajo de IA nunca se pierde porque un transporte de entrega tuvo un problema. El historial del chat sigue siendo la fuente de verdad. El flujo en vivo es solo una comodidad encima de ello, y un cliente que se haya perdido algunos fragmentos siempre puede recargar el resultado final desde el historial.

Si tu transporte necesita una política real para fallos repetidos, por ejemplo dejar de intentarlo después de diez errores, pon esa lógica dentro de tu implementación de Canal, porque solo el Canal sabe qué significa un fallo para su propio transporte.

### Canales personalizados

Un canal es cualquier clase que implemente `ChannelInterface`. Tiene cuatro métodos. Uno recibe los elementos transmitidos y tres te indican cómo terminó la ejecución:

```php
namespace NeuronAI\Workflow\Channel;

interface StreamingChannelInterface
{
    /** 
     * Un evento de protocolo producido por el adaptador de flujo, en el orden del flujo. 
     */
    public function send(ProtocolEvent $event): void;

    /**
     * El segmento de ejecución terminó con una o más solicitudes de interrupción activas.
     */
    public function interrupted(WorkflowState $state): void;

    /** El segmento de ejecución terminó correctamente. */
    public function completed(WorkflowState $state, string $workflowId): void;

    /**
     * El segmento de ejecución murió por un throwable no controlado. Solo notificación — la
     * excepción se propaga igualmente al llamador.
     */
    public function failed(Throwable $exception, string $workflowId): void;
}
```

Cada ejecución termina con exactamente una de las tres llamadas terminales: `suspended()`, `completed()`, o `failed()`. Esto es importante para las interfaces de usuario. Si una ejecución falla y no tienes ninguna señal de error, el usuario se queda con un indicador de carga que nunca se detiene. Con `failed()` tu frontend siempre recibe una señal clara de fin y puede recuperarse, por ejemplo recargando el historial del chat.

Hay dos detalles que conviene conocer. El `failed()` método es solo una notificación: la excepción sigue llegando al código que llamó a `chat()`.

Aquí hay un ejemplo de un `LogChannel`:

```php
use NeuronAI\Workflow\Channel\ChannelInterface;
use NeuronAI\Workflow\Interrupt\InterruptRequest;
use NeuronAI\Workflow\WorkflowState;

class LogChannel implements ChannelInterface
{
    public function __construct(protected LoggerInterface $log)
    {
    }

    public function send(ProtocolEvent $item): void
    {
        $this->log->debug(json_encode($item));
    }

    public function interrupted(InterruptRequest $request, string $runId): void
    {
        $this->log->debug("interrupted: {$runId}");
    }

    public function completed(WorkflowState $state, string $runId): void
    {
        $this->log->debug("completed: {$runId}");
    }

    public function failed(Throwable $exception, string $runId): void
    {
        $this->log->debug("failed: {$runId} ({$exception->getMessage()})");
    }
}
```

Y adjúntalo como cualquier otro canal:

```php
$agent->setChannel(new LogChannel(new Logger(__DIR__ . '/storage/workflow.log')));
```
