Pular para o conteúdo principal

Visão Geral

O Claude Agent SDK suporta dois modos de entrada distintos para interagir com agentes:
  • Modo Streaming Input (Padrão e Recomendado) - Uma sessão persistente e interativa
  • Single Message Input - Consultas únicas que usam estado de sessão e retomada
Este guia explica as diferenças, benefícios e casos de uso para cada modo para ajudá-lo a escolher a abordagem correta para sua aplicação. O modo streaming input é a forma preferida de usar o Claude Agent SDK. Ele fornece acesso completo aos recursos do agente e permite experiências ricas e interativas. Ele permite que o agente funcione como um processo de longa duração que recebe entrada do usuário, lida com interrupções, exibe solicitações de permissão e gerencia a sessão.

Como Funciona

Benefícios

Uploads de Imagens

Anexe imagens diretamente às mensagens para análise e compreensão visual

Mensagens Enfileiradas

Envie múltiplas mensagens que processam sequencialmente, com capacidade de interrupção

Integração de Ferramentas

Acesso completo a todas as ferramentas e servidores MCP personalizados durante a sessão

Feedback em Tempo Real

Veja as respostas conforme são geradas, não apenas os resultados finais

Persistência de Contexto

Mantenha o contexto da conversa em múltiplos turnos naturalmente

Exemplo de Implementação

No SDK TypeScript, se seu gerador de mensagens lançar uma exceção, por exemplo quando um arquivo que ele lê está faltando, o stream termina com um erro que diz Claude Code process aborted by user em vez do erro original, então verifique o código dentro do seu gerador primeiro quando você vir essa mensagem. O erro também pode ser precedido por uma longa linha minificada do código-fonte do SDK agrupado, então leia até o final da saída para encontrar o texto do erro.No SDK Python, uma exceção do gerador é registrada no nível de debug e a sessão trava sem lançar, então se uma sessão de streaming ficar pendurada sem saída, ative o registro de debug e verifique seu gerador.

Entrada de Mensagem Única

A entrada de mensagem única é mais simples, mas mais limitada.

Quando Usar Entrada de Mensagem Única

Use entrada de mensagem única quando:
  • Você precisa de uma resposta única
  • Você não precisa de anexos de imagens ou métodos de controle mid-session
  • Você precisa operar em um ambiente sem estado, como uma função lambda

Limitações

O modo de entrada de mensagem única não suporta:
  • Anexos de imagens diretos em mensagens
  • Enfileiramento dinâmico de mensagens
  • Interrupção em tempo real
  • Conversas naturais com múltiplos turnos
Se uma consulta terminar com um resultado de erro, como error_max_turns, uma chamada única de query() gera um erro que inclui o texto da falha após gerar a mensagem de resultado final, portanto, envolva o loop em um bloco try se seu código precisar continuar. Consulte Lidar com o resultado para os subtipos de resultado.

Exemplo de Implementação