For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/developers/streaming-and-events.md.
Kivox

Streaming y eventos

El envío de un mensaje devuelve la respuesta como text/event-stream, en lugar de esperar a que el turno completo termine de generarse. Esto permite que la interfaz reaccione mientras la operación está en curso.

Tipos de evento

EventoContiene
text_deltaUn fragmento de texto de la respuesta
reasoning_deltaUna actualización del razonamiento interno del modelo
tool_call_startedEl modelo comenzó a construir una llamada a una herramienta
tool_call_deltaUn fragmento incremental de los argumentos de esa llamada
tool_callLa llamada a la herramienta quedó completa y Kivox va a ejecutarla
tool_resultEl resultado devuelto por la herramienta ya ejecutada
turn_completeEl turno terminó por completo
errorUn error ocurrido durante la ejecución del turno

El ciclo de vida de una llamada a herramienta

Las herramientas se ejecutan del lado de Kivox: su aplicación nunca recibe una llamada que deba ejecutar por su cuenta, solo observa su progreso y su resultado a través del stream.

Un turno puede incluir varias llamadas a herramientas, secuenciales o superpuestas. No asuma que solo habrá una.

Consumir el stream

import { readSSE } from "zudoku/client/sse";

for await (const event of readSSE(response.body)) {
    if (event.type === "text_delta") {
        appendText(event.data.chunk);
    }
    if (event.type === "error") {
        showError();
    }
    if (event.type === "turn_complete") {
        markDone();
    }
}

turn_complete es la señal explícita de que el turno finalizó. Prefiera este evento sobre inferir el final a partir del cierre del stream: el cierre de la conexión también ocurre ante un error o una cancelación, y turn_complete es la única forma de distinguir un final exitoso de esos otros casos.

Estados de una respuesta

Cancelar un stream

Una conversación activa puede cancelarse cuando la aplicación ya no necesita continuar el turno, por ejemplo si el usuario interrumpe una respuesta mientras el agente está respondiendo o navega fuera de la conversación.

cURL
TypeScript
curl -X POST https://server.kivox.com.co/v1/chats/$CHAT_ID/abort \
  -H "Authorization: Bearer $KIVOX_API_KEY"

La respuesta exitosa es 204 No Content. La cancelación debería tratarse como un estado normal del ciclo de una conversación, no como un caso excepcional.

Alternativa del lado del cliente

Si su aplicación construyó la solicitud con un AbortController, abortar esa señal cierra la conexión localmente de inmediato. Llamar además al endpoint de cancelación es lo que le indica a Kivox que detenga el procesamiento del turno en el servidor.

Idempotencia y reintentos

El encabezado Idempotency-Key en el envío de mensajes representa una operación concreta desde la perspectiva del cliente, útil cuando existe la posibilidad de que una solicitud se repita por una pérdida temporal de conexión. Cada operación independiente debe usar una clave distinta.

No todas las solicitudes fallidas deben reintentarse automáticamente. Si una operación ya ejecutó una acción externa antes de que la aplicación perdiera la conexión, repetirla sin una estrategia adecuada puede tener efectos no deseados. El comportamiento general de reintento por código de error está en Manejo de errores.