Skip to main content
Por padrão, o Agent SDK produz uma AssistantMessage completa para cada bloco de conteúdo não vazio, como um bloco de texto ou uma chamada de ferramenta, após Claude terminar de gerar esse bloco. Para receber atualizações incrementais conforme o texto e as chamadas de ferramentas são geradas, ative o streaming de mensagens parciais.
Esta página aborda o streaming de saída (recebimento de tokens em tempo real). Para modos de entrada (como você envia mensagens), consulte Enviar mensagens para agentes. Você também pode transmitir respostas usando o Agent SDK via CLI.

Ativar streaming de saída

Para ativar o streaming, defina include_partial_messages (Python) ou includePartialMessages (TypeScript) como true nas suas opções. Isso faz com que o SDK produza mensagens StreamEvent contendo eventos brutos da API conforme chegam, além das mensagens AssistantMessage e ResultMessage usuais. Seu código então precisa:
  1. Verificar o tipo de cada mensagem para distinguir StreamEvent de outros tipos de mensagem
  2. Para StreamEvent, extrair o campo event e verificar seu type
  3. Procurar por eventos content_block_delta onde delta.type é text_delta, que contêm os chunks de texto reais
O exemplo abaixo ativa o streaming e imprime chunks de texto conforme chegam. Observe as verificações de tipo aninhadas: primeiro para StreamEvent, depois para content_block_delta, depois para text_delta:

Referência de StreamEvent

Quando mensagens parciais estão ativadas, você recebe eventos brutos de streaming da Claude API encapsulados em um objeto. O tipo tem nomes diferentes em cada SDK: Ambos contêm eventos brutos da Claude API, não texto acumulado. Você precisa extrair e acumular deltas de texto você mesmo. O campo parent_tool_use_id é sempre None em Python e null em TypeScript. Eventos de stream são emitidos apenas para a sessão principal; deltas no nível de token de subagentos não são encaminhados. Para atribuir saída a um subagentos, use mensagens completas, que carregam parent_tool_use_id. Veja Detectar invocação de subagentos. Claude Code define user_message_uuid no primeiro evento de stream não-ping da rodada, e novamente quando a mensagem que a rodada está respondendo muda, sob as condições em user_message_uuid. O StreamEvent do Python não expõe este campo. O campo event contém o evento de streaming bruto da Claude API. Os tipos de evento comuns incluem:

Fluxo de mensagens

Claude Code emite uma AssistantMessage conforme cada bloco de conteúdo não vazio é concluído, portanto uma resposta com um bloco de texto e uma chamada de ferramenta produz dois objetos AssistantMessage. Cada um carrega apenas seu próprio bloco de conteúdo, e ambos compartilham o mesmo ID de mensagem, que você lê como message.message.id em TypeScript e message.message_id em Python. Com mensagens parciais ativadas, cada AssistantMessage chega antes do evento content_block_stop desse bloco, e você recebe mensagens nesta ordem:
Sem mensagens parciais ativadas, você recebe todos os tipos de mensagem, exceto StreamEvent. Os tipos comuns incluem SystemMessage (inicialização de sessão), AssistantMessage (blocos de conteúdo completos), ResultMessage (resultado final) e uma mensagem de limite compacta indicando quando o histórico de conversa foi compactado (SDKCompactBoundaryMessage em TypeScript; SystemMessage com subtipo "compact_boundary" em Python).

Lidar com um stream interrompido

Se um stream for interrompido no meio de uma mensagem, como quando você interrompe o turno ou a conexão cai, você ainda recebe o message_stop dessa mensagem antes que o turno termine. Um bloco de texto ou de pensamento interrompido também recebe seu content_block_stop. Uma chamada de ferramenta interrompida não recebe, portanto, se message_stop chegar enquanto o bloco de uma chamada de ferramenta ainda estiver aberto, trate a entrada dessa chamada como incompleta. Antes do Claude Code v2.1.290, um stream interrompido podia encerrar o turno sem message_stop, de modo que uma resposta que você renderiza a partir de eventos de stream podia continuar sendo exibida como em andamento. O Agent SDK para TypeScript inclui o Claude Code v2.1.290 ou posterior a partir da v0.3.290, e o Agent SDK para Python a partir da v0.2.164. Se uma resposta continuar sendo exibida como em andamento após o término do turno, atualize o SDK.

Transmitir chamadas de ferramentas

As chamadas de ferramentas também são transmitidas incrementalmente. Você pode rastrear quando as ferramentas começam, receber sua entrada conforme é gerada e ver quando são concluídas. O exemplo abaixo rastreia a ferramenta atual sendo chamada e acumula a entrada JSON conforme é transmitida. Ele usa três tipos de evento:
  • content_block_start: ferramenta começa
  • content_block_delta com input_json_delta: chunks de entrada chegam
  • content_block_stop: chamada de ferramenta concluída

Construir uma interface de usuário de streaming

Este exemplo combina streaming de texto e ferramentas em uma interface coerente. Ele rastreia se o agente está executando uma ferramenta (usando um sinalizador in_tool) para mostrar indicadores de status como [Using Read...] enquanto as ferramentas são executadas. O texto é transmitido normalmente quando não está em uma ferramenta, e a conclusão da ferramenta dispara uma mensagem “done”. Este padrão é útil para interfaces de chat que precisam mostrar progresso durante tarefas de agente em várias etapas.

Limitações conhecidas

  • Structured output: com mensagens parciais ativadas, o JSON é transmitido como chunks input_json_delta não validados de uma chamada de ferramenta, e apenas o resultado validado chega ao ResultMessage.structured_output final. Consulte structured outputs para detalhes.

Próximas etapas

Agora que você pode transmitir texto e chamadas de ferramentas em tempo real, explore estes tópicos relacionados: