Iteradores asíncronos para streaming en el SDK de TypeScript

Consume deltas de mensajes con bucles for-await en lugar de oyentes de eventos manuales.

Resumen

El paquete @anthropic-ai/sdk transmite respuestas de Claude como una secuencia de eventos, y la forma moderna de consumirlos es un bucle for await...of sobre el objeto de stream devuelto por client.messages.stream(...).

Las versiones anteriores del SDK y muchos tutoriales configuran el streaming con oyentes de eventos del tipo .on('text', ...) tomados del patrón EventEmitter de Node. Ese estilo todavía funciona, pero dispersa el estado entre cierres de callback y hace que el manejo de errores sea incómodo.

Los iteradores asíncronos se integran de forma natural en el flujo de control normal de async/await. Escribes un bucle lineal, usas try/catch para errores y break para salir anticipadamente exactamente como lo harías con un array.

El objeto de stream devuelto por .stream() es tanto un iterable asíncrono (para la vista granular evento por evento) como una utilidad con finalMessage() (para la respuesta completa ensamblada una vez que el stream finaliza).

Esta página contrasta ambos estilos y recorre un ejemplo completo que transmite una respuesta de chat y renderiza deltas de texto incrementalmente.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Escribe un haiku sobre iteradores asíncronos." }],
});
 
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}
 
const message = await stream.finalMessage();
console.log("\n\nUso:", message.usage);

Cuándo usar esto:

• Quieres renderizar tokens incrementalmente en una UI, CLI o terminal a medida que llegan.
• Necesitas el mensaje final ensamblado (texto, razón de parada, uso) después de que el stream se complete.
• Quieres manejo seguro de tipos para diferentes tipos de bloques de contenido sin nombres de eventos manuales.
• Estás escribiendo código nuevo para streaming y no tienes una razón heredada para usar oyentes de eventos.

Ejemplo funcional

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
async function streamChatResponse(userMessage: string): Promise<void> {
  const stream = client.messages.stream({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: userMessage }],
  });
 
  let currentBlockType: string | null = null;
 
  for await (const event of stream) {
    switch (event.type) {
      case "content_block_start":
        currentBlockType = event.content_block.type;
        if (currentBlockType === "text") {
          process.stdout.write("Claude: ");
        }
        break;
 
      case "content_block_delta":
        if (event.delta.type === "text_delta") {
          // Renderiza deltas de texto incrementalmente a medida que llegan.
          process.stdout.write(event.delta.text);
        } else if (event.delta.type === "thinking_delta") {
          // Los deltas de pensamiento extendido llegan en su propio tipo de bloque.
          process.stdout.write(event.delta.thinking);
        }
        break;
 
      case "content_block_stop":
        if (currentBlockType === "text") {
          process.stdout.write("\n");
        }
        currentBlockType = null;
        break;
 
      case "message_stop":
        // El stream ha finalizado; finalMessage() a continuación es rápido.
        break;
    }
  }
 
  // Después del bucle, el mensaje completo está disponible sin volver a leer eventos.
  const finalMessage = await stream.finalMessage();
  console.log("Razón de parada:", finalMessage.stop_reason);
  console.log("Tokens de entrada:", finalMessage.usage.input_tokens);
  console.log("Tokens de salida:", finalMessage.usage.output_tokens);
}
 
streamChatResponse("Explica los iteradores asíncronos en dos frases.").catch((error) => {
  console.error("El streaming falló:", error);
});

Lo que esto demuestra:

• Un único bucle lineal for await...of reemplaza múltiples callbacks de oyentes de eventos con nombre.
• El estrechamiento de event.type y event.delta.type proporciona acceso seguro a tipos para variantes de text, thinking y otras sin necesidad de conversiones.
• El manejo de errores estilo try/catch (aquí, .catch() en la función asíncrona externa) cubre todo el stream, no solo eventos individuales.
• stream.finalMessage() devuelve el objeto Message completo ensamblado después de que la iteración finaliza, sin contabilidad adicional.
• Las variables locales como currentBlockType residen en el ámbito normal del bucle en lugar de ser transportadas a través de cierres.

Análisis en profundidad

Cómo funciona

• client.messages.stream(...) abre una conexión de eventos enviados por el servidor (server-sent events) a la API de Mensajes y devuelve un objeto MessageStream inmediatamente, antes de que hayan llegado eventos.
• MessageStream implementa Symbol.asyncIterator, por lo que for await (const event of stream) extrae eventos de la conexión uno a la vez, en orden, esperando cada uno a medida que está disponible.
• Cada iteración produce un evento del protocolo de stream sin procesar: message_start, content_block_start, content_block_delta, content_block_stop, message_delta o message_stop.
• Dado que el bucle es solo flujo de control async, un return, break o error lanzado dentro de él se propaga de la manera que lo haría en cualquier otro bucle for await, y la conexión subyacente se limpia.
• stream.finalMessage() se resuelve una vez que el stream ha finalizado, utilizando un acumulador interno que reensambla todos los bloques de contenido y deltas en un único objeto Message idéntico en forma a una respuesta no streaming.
• No tienes que iterar los eventos en absoluto si solo te importa el resultado final: llamar directamente a await stream.finalMessage() (sin un bucle for await) todavía funciona, ya que el SDK impulsa el stream a completarse internamente.

Tipos de eventos de un vistazo

Iteradores asíncronos vs. Oyentes de eventos manuales

// Estilo antiguo: configuración manual de oyentes de eventos.
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hola, Claude" }],
});
 
stream.on("text", (textDelta) => {
  process.stdout.write(textDelta);
});
 
stream.on("error", (error) => {
  console.error("Error del stream:", error);
});
 
stream.on("end", () => {
  console.log("\nTerminado.");
});
 
// Estilo moderno: un bucle de iterador asíncrono, mostrado en la Receta y el Ejemplo funcional arriba.

El estilo de oyente todavía se envía en el SDK para compatibilidad con versiones anteriores, pero tiene tres desventajas prácticas frente a for await...of:

• Flujo de control disperso. El éxito, el error y la finalización viven cada uno en un callback separado, por lo que no hay un lugar único para razonar sobre "qué sucede durante este stream".
• Limpieza incómoda. Salir de un stream anticipadamente (por ejemplo, después de que el usuario cancele una solicitud) significa llamar manualmente a stream.abort() y anular el registro de oyentes, en lugar de simplemente break en un bucle.
• Tipado más débil en el sitio de llamada. Nombres de eventos como "text" son cadenas que debes escribir correctamente, en comparación con los valores event.type que TypeScript reduce por ti dentro del bucle.

Notas de TypeScript

import type { MessageStreamEvent } from "@anthropic-ai/sdk/resources/messages";
 
function handleEvent(event: MessageStreamEvent): void {
  // event.type reduce la unión, por lo que event.delta y event.content_block
  // solo son accesibles con los campos que esa variante realmente tiene.
  if (event.type === "content_block_delta") {
    if (event.delta.type === "text_delta") {
      console.log(event.delta.text); // string, no se necesita conversión
    } else if (event.delta.type === "input_json_delta") {
      console.log(event.delta.partial_json); // string, fragmento de entrada de herramienta
    }
  }
}

El SDK envía sus propias definiciones de tipo, por lo que cada evento y bloque de contenido es una unión discriminada indexada por type. Reducir con if/switch en event.type (y event.delta.type un nivel más abajo) te proporciona un manejo exhaustivo y verificado por el compilador en lugar de cargas útiles de callback débilmente tipadas.

Parámetros y valores de retorno

Trampas comunes

• Iterar el stream dos veces. Un MessageStream solo se puede consumir una vez; llamar a for await sobre él una segunda vez no produce nada. Solución: captura lo que necesites (texto, uso, llamadas a herramientas) durante el único pase, o llama a stream.finalMessage() si solo necesitas el resultado final.
• Olvidar reducir event.delta.type. Tratar cada content_block_delta como un delta de texto falla cuando llega un thinking_delta o input_json_delta, ya que esas variantes usan nombres de campo diferentes. Solución: siempre verifica event.delta.type antes de leer event.delta.text.
• Mezclar oyentes .on() con un bucle for await en el mismo stream. Ambos consumen los mismos eventos subyacentes, por lo que combinarlos conduce a datos perdidos o duplicados. Solución: elige un estilo por stream; usa el iterador asíncrono a menos que tengas una razón específica para mantener los oyentes.
• No manejar errores del stream. Una excepción no controlada de una conexión rota o un error de API a mitad del stream hará que un proceso de Node falle si nada lo espera o lo captura. Solución: envuelve el bucle (o la función asíncrona que llama) en try/catch, o adjunta un .catch() a la función asíncrona externa.
• Llamar a finalMessage() antes de que termine el bucle. Si llamas a stream.finalMessage() concurrentemente mientras iteras en otra parte del código, puedes terminar compitiendo por el mismo stream. Solución: llama a finalMessage() después de que el bucle for await se complete, o omite el bucle por completo y solo llama a finalMessage() si no necesitas actualizaciones por token.
• Asumir que content_block_start siempre significa texto. Los bloques de uso de herramientas y los bloques de pensamiento también disparan content_block_start, con un content_block.type diferente. Solución: verifica content_block.type antes de asumir que el bloque es text.

Alternativas

Preguntas frecuentes

const stream = client.messages.stream({ /* ... */ });
 
const timeout = setTimeout(() => stream.abort(), 5000);
 
for await (const event of stream) {
  // ... manejar eventos
}
 
clearTimeout(timeout);

const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hola" }],
});
 
for await (const text of stream.textStream ?? []) {
  process.stdout.write(text);
}

Relacionado

• Conceptos básicos del SDK de TypeScript/JavaScript - configuración del cliente y conceptos básicos de solicitudes en los que se basa esta página.
• El modelo mental del SDK de TypeScript de Anthropic - cómo encajan conceptualmente las solicitudes, respuestas y streams.
• Referencia de tipos del SDK de TypeScript para bloques de contenido - referencia completa de tipos para TextBlock, ToolUseBlock y ThinkingBlock.
• Creación de un endpoint de chat en streaming con Next.js y el SDK de TypeScript - aplica este patrón de streaming dentro de un manejador de rutas de Next.js.
• Patrones de reintento, tiempo de espera y AbortController en el SDK de TypeScript - cancelación y reintento seguro de streams.

Versiones de pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de TypeScript @anthropic-ai/sdk (última versión). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.