Referência de Tipos de Eventos de Streaming
Um guia conciso para cada tipo de evento que a API de Mensagens emite durante o streaming, seus campos e quando ele é disparado no ciclo de vida do evento.
Como Usar Esta Lista
- Percorra a tabela Ciclo de Vida do Evento de cima para baixo - esta é a ordem em que os eventos realmente chegam para uma resposta típica.
- Use a tabela Tipos de Delta quando estiver dentro de um manipulador
content_block_deltae precisar saber quais valoresevent.delta.typepodem ocorrer. - As tabelas Referência de Campos listam todos os campos que você realmente lerá de cada objeto de evento no SDK Python.
- Faça referência cruzada com Como os Server-Sent Events Potencializam as Respostas de Streaming do Claude para o modelo conceitual por trás desta tabela.
Ciclo de Vida do Evento
| Ordem | Tipo de Evento (type) | Dispara | Propósito |
|---|---|---|---|
| 1 | message_start | Uma vez, primeiro | Abre a mensagem; carrega id, model, role e o uso inicial (próximo de zero) usage. |
| 2 | content_block_start | Uma vez por bloco de conteúdo | Abre um bloco; carrega o type do bloco (text, tool_use ou thinking) e o index. |
| 3 | content_block_delta | Muitas vezes por bloco | Carrega um fragmento incremental do conteúdo desse bloco - veja Tipos de Delta abaixo. |
| 4 | content_block_stop | Uma vez por bloco de conteúdo | Fecha um bloco; o conteúdo do bloco está agora completo para esse index. |
| - | (passos 2-4 repetem) | Por bloco adicional | Uma resposta pode conter múltiplos blocos (por exemplo, thinking seguido de text seguido de tool_use) em sequência. |
| 5 | message_delta | Uma vez, perto do fim | Carrega stop_reason, stop_sequence e o usage finalizado (tokens de saída). |
| 6 | message_stop | Uma vez, por último | Sinaliza que o stream está completo; nenhum evento adicional segue. |
| - | ping | A qualquer momento (raro) | Um evento de "keep-alive" sem payload; seguro para ignorar. |
| - | error | A qualquer momento | Sinaliza um erro durante o stream (por exemplo, um modelo sobrecarregado); encerra o stream. |
Tipos de Delta (dentro de content_block_delta)
delta.type | Pertence ao tipo de bloco | Campo chave | Significado |
|---|---|---|---|
text_delta | text | delta.text | O próximo fragmento de prosa gerada. |
input_json_delta | tool_use | delta.partial_json | O próximo fragmento da string de argumentos JSON de uma chamada de ferramenta. |
thinking_delta | thinking | delta.thinking | O próximo fragmento de texto de raciocínio "extended-thinking". |
signature_delta | thinking | delta.signature | Um fragmento de assinatura criptográfica para o bloco "thinking", enviado perto de seu fechamento. |
Referência de Campos: message_start
| Campo | Tipo | Descrição |
|---|---|---|
message.id | str | Identificador único para esta mensagem. |
message.model | str | O modelo que gerou a resposta (por exemplo, claude-sonnet-5). |
message.role | str | Sempre "assistant" para respostas da API. |
message.usage.input_tokens | int | Contagem de tokens de entrada, conhecida imediatamente. |
message.usage.output_tokens | int | Próximo de zero neste ponto; finalizado posteriormente em message_delta. |
Referência de Campos: content_block_start / content_block_stop
| Campo | Tipo | Descrição |
|---|---|---|
index | int | Qual bloco de conteúdo este evento pertence; a chave para rastrear o estado por bloco. |
content_block.type | str | "text", "tool_use" ou "thinking". |
content_block.name | str | Nome da ferramenta - presente apenas quando type é "tool_use". |
content_block.id | str | O tool_use_id - presente apenas quando type é "tool_use". |
Referência de Campos: message_delta / message_stop
| Campo | Tipo | Descrição |
|---|---|---|
delta.stop_reason | str | Por que a geração parou: "end_turn", "max_tokens", "tool_use", "stop_sequence". |
delta.stop_sequence | str | None | A sequência de parada personalizada correspondida, se stop_reason for "stop_sequence". |
usage.output_tokens | int | Contagem final de tokens de saída para toda a mensagem. |
| (nenhum) | - | message_stop não carrega nenhum payload além de type - é um sinal puro. |
Padrões de Acesso do SDK Python
| Você quer | Use |
|---|---|
| Apenas o texto, à medida que chega | for text in stream.text_stream: |
| Cada evento bruto, todos os tipos | for event in stream: |
A Message completa após o streaming | stream.get_final_message() após a iteração terminar |
| Equivalentes assíncronos | async for text in stream.text_stream: / async for event in stream: em AsyncAnthropic |
FAQs
Qual é o primeiro evento em todo stream?
message_start, sempre. Ele chega antes que qualquer bloco de conteúdo exista.
Qual é o último evento em todo stream?
message_stop, sempre - é um evento de sinal puro sem payload próprio.
Onde encontro as contagens de uso de tokens?
Tokens de entrada estão em message_start.message.usage.input_tokens. Tokens de saída são finalizados em message_delta.usage.output_tokens.
Como diferencio um bloco de texto de um bloco tool_use?
Verifique content_block.type no evento content_block_start para o index desse bloco - é "text", "tool_use" ou "thinking".
Qual campo eu leio para argumentos de chamada de ferramenta transmitidos?
event.delta.partial_json em eventos content_block_delta onde event.delta.type == "input_json_delta" - acumule estes antes de analisar como JSON.
O `ping` é algo que preciso lidar?
Não, é um keep-alive sem payload. Seguro para ignorar em um dispatch baseado em tipo (simplesmente não corresponderá a nenhum dos seus casos tratados).
O que `stop_reason` me diz?
Por que o modelo parou de gerar: "end_turn" (conclusão natural), "max_tokens" (atingiu o limite de tokens), "tool_use" (pausou para chamar uma ferramenta) ou "stop_sequence" (correspondeu a uma string de parada personalizada).
Uma resposta pode conter mais de um bloco de conteúdo?
Sim - por exemplo, um bloco thinking seguido por um bloco text, ou um bloco text seguido por um ou mais blocos tool_use, cada um aberto e fechado independentemente por index.
Para que serve `signature_delta`?
Ele transmite uma assinatura criptográfica associada a um bloco "extended-thinking", usada para verificar se o conteúdo de pensamento não foi adulterado ao ser passado de volta em um turno posterior.
Um evento `error` significa que toda a minha solicitação falhou?
Significa que o stream terminou anormalmente no meio da geração. Trate-o da mesma forma que uma conexão perdida: qualquer conteúdo que chegou antes dele está incompleto, e a solicitação deve ser normalmente retentada.
Como `content_block_delta` difere de `message_delta`?
content_block_delta carrega conteúdo incremental dentro de um bloco (fragmentos de texto, JSON ou "thinking"). message_delta carrega metadados em nível de mensagem (stop_reason, uso final) que só são conhecidos quando a geração está terminando.
Onde encontro o nome do modelo que gerou uma resposta?
message_start.message.model - ele ecoa o modelo que você solicitou (útil se seu código permite que um alias de modelo seja resolvido para um snapshot específico datado).
Relacionados
- Como os Server-Sent Events Potencializam as Respostas de Streaming do Claude - o modelo conceitual por trás desta tabela.
- Noções Básicas de Respostas de Streaming - exemplos executáveis usando esses tipos de evento.
- Lidando com JSON Parcial Durante Chamadas de Ferramentas Transmitidas - usando
input_json_deltana prática. - Transmitindo Blocos de "Extended Thinking" para o Frontend - usando
thinking_deltaesignature_delta. - Referência de Papéis da API de Mensagens e Tipos de Blocos de Conteúdo - o modelo de bloco de conteúdo não-streaming ao qual isso se mapeia.
Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente 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
anthropicpara Python (última versão 0.x). 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.