Iteradores Assíncronos para Streaming no SDK TypeScript

Consuma deltas de mensagens com loops for-await em vez de listeners de eventos manuais.

Resumo

O pacote @anthropic-ai/sdk transmite respostas do Claude como uma sequência de eventos, e a maneira moderna de consumi-los é um loop for await...of sobre o objeto de stream retornado por client.messages.stream(...).

Versões mais antigas do SDK e muitos tutoriais configuram o streaming com listeners de eventos no estilo .on('text', ...) , emprestado do padrão EventEmitter do Node. Esse estilo ainda funciona, mas espalha o estado entre closures de callback e torna o tratamento de erros complicado.

Iteradores assíncronos se integram naturalmente ao fluxo de controle normal async/await. Você escreve um loop linear, usa try/catch para erros e break para sair mais cedo exatamente como faria com um array.

O objeto de stream retornado por .stream() é tanto um iterável assíncrono (para a visualização granular evento por evento) quanto um helper com finalMessage() (para a resposta completa montada quando o stream termina).

Esta página contrasta ambos os estilos e percorre um exemplo completo que transmite uma resposta de chat e renderiza deltas de texto incrementalmente.

Receita

Cartão de receita de referência rápida, pronto para copiar e colar.

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: "Escreva um haicai sobre iteradores assí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);

Quando usar isso:

• Você deseja renderizar tokens incrementalmente em uma interface de usuário, CLI ou terminal à medida que eles chegam.
• Você precisa da mensagem final montada (texto, motivo de parada, uso) após a conclusão do stream.
• Você deseja tratamento type-safe de diferentes tipos de blocos de conteúdo sem nomes de eventos manuais.
• Você está escrevendo código de streaming novo e não tem um motivo legado para usar listeners de eventos.

Exemplo 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 à medida que chegam.
          process.stdout.write(event.delta.text);
        } else if (event.delta.type === "thinking_delta") {
          // Deltas de pensamento estendido chegam em seu próprio tipo de bloco.
          process.stdout.write(event.delta.thinking);
        }
        break;
 
      case "content_block_stop":
        if (currentBlockType === "text") {
          process.stdout.write("\n");
        }
        currentBlockType = null;
        break;
 
      case "message_stop":
        // O stream terminou; finalMessage() abaixo é agora rápido.
        break;
    }
  }
 
  // Após o loop, a mensagem completa está disponível sem reler os eventos.
  const finalMessage = await stream.finalMessage();
  console.log("Motivo da parada:", finalMessage.stop_reason);
  console.log("Tokens de entrada:", finalMessage.usage.input_tokens);
  console.log("Tokens de saída:", finalMessage.usage.output_tokens);
}
 
streamChatResponse("Explique iteradores assíncronos em duas frases.").catch((error) => {
  console.error("Falha no streaming:", error);
});

O que isso demonstra:

• Um único loop linear for await...of substitui múltiplos callbacks de listener de eventos nomeados.
• O estreitamento em event.type e event.delta.type fornece acesso type-safe a variantes de text, thinking e outras deltas sem necessidade de casting.
• Tratamento de erros no estilo try/catch (aqui, .catch() na função assíncrona externa) cobre todo o stream, não apenas eventos individuais.
• stream.finalMessage() retorna o objeto Message completo montado após a iteração terminar, sem contabilidade extra.
• Variáveis locais como currentBlockType vivem no escopo normal do loop em vez de serem transportadas através de closures.

Mergulho Profundo

Como Funciona

• client.messages.stream(...) abre uma conexão de server-sent-events para a API Messages e retorna um objeto MessageStream imediatamente, antes que quaisquer eventos tenham chegado.
• MessageStream implementa Symbol.asyncIterator, então for await (const event of stream) puxa eventos da conexão um por um, em ordem, aguardando cada um à medida que se torna disponível.
• Cada iteração produz um evento do protocolo de stream bruto: message_start, content_block_start, content_block_delta, content_block_stop, message_delta ou message_stop.
• Como o loop é apenas fluxo de controle async, um return, break ou erro lançado dentro dele se propaga da maneira que faria em qualquer outro loop for await, e a conexão subjacente é limpa.
• stream.finalMessage() resolve assim que o stream termina, usando um acumulador interno que remonta todos os blocos de conteúdo e deltas em um único objeto Message idêntico em forma a uma resposta não-streaming.
• Você não precisa iterar os eventos se estiver interessado apenas no resultado final: chamar await stream.finalMessage() diretamente (sem um loop for await) ainda funciona, pois o SDK impulsiona o stream à conclusão internamente.

Tipos de Eventos em Resumo

Iteradores Assíncronos vs. Listeners de Eventos Manuais

// Estilo antigo: configuração manual de listener de eventos.
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Olá, Claude" }],
});
 
stream.on("text", (textDelta) => {
  process.stdout.write(textDelta);
});
 
stream.on("error", (error) => {
  console.error("Erro no stream:", error);
});
 
stream.on("end", () => {
  console.log("\nConcluído.");
});
 
// Estilo moderno: um loop de iterador assíncrono, mostrado na Receita e no Exemplo Funcional acima.

O estilo de listener ainda é enviado no SDK para compatibilidade com versões anteriores, mas tem três desvantagens práticas em comparação com for await...of:

• Fluxo de controle espalhado. Sucesso, erro e conclusão vivem em callbacks separados, então não há um único lugar para raciocinar sobre "o que acontece durante este stream".
• Limpeza complicada. Sair de um stream mais cedo (por exemplo, depois que o usuário cancela uma solicitação) significa chamar manualmente stream.abort() e desregistrar listeners, em vez de apenas break em um loop.
• Tipagem mais fraca no local de chamada. Nomes de eventos como "text" são strings que você precisa acertar, em vez de valores event.type que o TypeScript refina para você dentro do loop.

Notas do TypeScript

import type { MessageStreamEvent } from "@anthropic-ai/sdk/resources/messages";
 
function handleEvent(event: MessageStreamEvent): void {
  // event.type refina a união, então event.delta e event.content_block
  // só são acessíveis com os campos que essa variante realmente tem.
  if (event.type === "content_block_delta") {
    if (event.delta.type === "text_delta") {
      console.log(event.delta.text); // string, sem necessidade de cast
    } else if (event.delta.type === "input_json_delta") {
      console.log(event.delta.partial_json); // string, fragmento de entrada de ferramenta
    }
  }
}

O SDK envia suas próprias definições de tipo, então cada evento e bloco de conteúdo é uma união discriminada com chave em type. Refinar com if/switch em event.type (e event.delta.type um nível abaixo) fornece tratamento exaustivo e verificado pelo compilador em vez de payloads de callback fracamente tipados.

Parâmetros e Valores de Retorno

Armadilhas

• Iterar o stream duas vezes. Um MessageStream só pode ser consumido uma vez; chamá-lo com for await uma segunda vez não produz nada. Correção: capture o que você precisa (texto, uso, chamadas de ferramenta) durante a única passagem, ou chame stream.finalMessage() se você precisar apenas do resultado final.
• Esquecer de refinar event.delta.type. Tratar cada content_block_delta como um delta de texto falha quando um thinking_delta ou input_json_delta chega, pois essas variantes usam nomes de campos diferentes. Correção: sempre verifique event.delta.type antes de ler event.delta.text.
• Misturar listeners .on() com um loop for await no mesmo stream. Ambos consomem os mesmos eventos subjacentes, então combiná-los leva a dados perdidos ou duplicados. Correção: escolha um estilo por stream; use o iterador assíncrono, a menos que você tenha um motivo específico para manter os listeners.
• Não tratar erros de stream. Uma rejeição não tratada de uma conexão quebrada ou um erro de API no meio do stream derrubará um processo Node se nada o aguardar ou capturar. Correção: envolva o loop (ou a função assíncrona de chamada) em try/catch, ou anexe um .catch() à promessa externa.
• Chamar finalMessage() antes que o loop termine. Se você chamar stream.finalMessage() concorrentemente enquanto ainda itera em outra parte do código, você pode acabar competindo com o mesmo stream. Correção: chame finalMessage() após a conclusão do loop for await, ou pule o loop inteiramente e chame finalMessage() apenas se você não precisar de atualizações por token.
• Assumir que content_block_start sempre significa texto. Blocos de uso de ferramenta e blocos de pensamento também disparam content_block_start, com um content_block.type diferente. Correção: verifique content_block.type antes de assumir que o bloco é text.

Alternativas

FAQs

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

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

Relacionados

• Noções Básicas do SDK TypeScript/JavaScript - configuração do cliente e noções básicas de solicitação nas quais esta página se baseia.
• O Modelo Mental do SDK TypeScript da Anthropic - como solicitações, respostas e streams se encaixam conceitualmente.
• Referência de Tipos do SDK TypeScript para Blocos de Conteúdo - referência completa de tipos para TextBlock, ToolUseBlock e ThinkingBlock.
• Construindo um Endpoint de Chat com Streaming usando Next.js e o SDK TypeScript - aplica este padrão de streaming dentro de um manipulador de rota Next.js.
• Padrões de Retry, Timeout e AbortController no SDK TypeScript - cancelando e tentando streams com segurança.

Versões da Pilha: Escrito contra a linha de modelos Claude atual a partir de ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial @anthropic-ai/sdk TypeScript (último lançamento). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.