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.
Ativar streaming de saída
Para ativar o streaming, definainclude_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:
- Verificar o tipo de cada mensagem para distinguir
StreamEventde outros tipos de mensagem - Para
StreamEvent, extrair o campoevente verificar seutype - Procurar por eventos
content_block_deltaondedelta.typeétext_delta, que contêm os chunks de texto reais
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:- Python:
StreamEvent(importar declaude_agent_sdk.types) - TypeScript:
SDKPartialAssistantMessagecomtype: 'stream_event'
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 umaAssistantMessage 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:
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 omessage_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çacontent_block_deltacominput_json_delta: chunks de entrada chegamcontent_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 sinalizadorin_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_deltanão validados de uma chamada de ferramenta, e apenas o resultado validado chega aoResultMessage.structured_outputfinal. 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:- Interactive vs one-shot queries: escolha entre modos de entrada para seu caso de uso
- Structured outputs: obtenha respostas JSON digitadas do agente
- Permissions: controle quais ferramentas o agente pode usar