Entrada de Streaming
Visão Geral
O Claude Agent SDK suporta dois modos de entrada distintos para interagir com agentes:
- Modo de Entrada de Streaming (Padrão e Recomendado) - Uma sessão interativa persistente
- Entrada de Mensagem Única - 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 certa para sua aplicação.
Modo de Entrada de Streaming (Recomendado)
O modo de entrada de streaming é a maneira preferida de usar o Claude Agent SDK. Ele fornece acesso completo às capacidades do agente e permite experiências ricas e interativas.
Ele permite que o agente opere como um processo de longa duração que recebe entrada do usuário, lida com interrupções, apresenta solicitações de permissão e gerencia sessões.
Como Funciona
%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
participant App as Sua Aplicação
participant Agent as Claude Agent
participant Tools as Ferramentas/Hooks
participant FS as Ambiente/<br/>Sistema de Arquivos
App->>Agent: Inicializar com AsyncGenerator
activate Agent
App->>Agent: Produzir Mensagem 1
Agent->>Tools: Executar ferramentas
Tools->>FS: Ler arquivos
FS-->>Tools: Conteúdo dos arquivos
Tools->>FS: Escrever/Editar arquivos
FS-->>Tools: Sucesso/Erro
Agent-->>App: Transmitir resposta parcial
Agent-->>App: Transmitir mais conteúdo...
Agent->>App: Completar Mensagem 1
App->>Agent: Produzir Mensagem 2 + Imagem
Agent->>Tools: Processar imagem e executar
Tools->>FS: Acessar sistema de arquivos
FS-->>Tools: Resultados da operação
Agent-->>App: Transmitir resposta 2
App->>Agent: Enfileirar Mensagem 3
App->>Agent: Interromper/Cancelar
Agent->>App: Lidar com interrupção
Note over App,Agent: Sessão permanece ativa
Note over Tools,FS: Estado persistente do<br/>sistema de arquivos mantido
deactivate AgentBenefícios
Upload de Imagens
Anexe imagens diretamente às mensagens para análise visual e compreensão
Mensagens Enfileiradas
Envie múltiplas mensagens que processam sequencialmente, com capacidade de interromper
Integração de Ferramentas
Acesso completo a todas as ferramentas e servidores MCP personalizados durante a sessão
Suporte a Hooks
Use hooks de ciclo de vida para personalizar comportamento em vários pontos
Feedback em Tempo Real
Veja respostas conforme são geradas, não apenas resultados finais
Persistência de Contexto
Mantenha contexto de conversa através de múltiplas rodadas naturalmente
Exemplo de Implementação
import { query } from "@anthropic-ai/claude-agent-sdk";
import { readFileSync } from "fs";
async function* generateMessages() {
// Primeira mensagem
yield {
type: "user" as const,
message: {
role: "user" as const,
content: "Analise esta base de código para problemas de segurança"
}
};
// Aguardar condições ou entrada do usuário
await new Promise(resolve => setTimeout(resolve, 2000));
// Acompanhamento com imagem
yield {
type: "user" as const,
message: {
role: "user" as const,
content: [
{
type: "text",
text: "Revise este diagrama de arquitetura"
},
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: readFileSync("diagram.png", "base64")
}
}
]
}
};
}
// Processar respostas de streaming
for await (const message of query({
prompt: generateMessages(),
options: {
maxTurns: 10,
allowedTools: ["Read", "Grep"]
}
})) {
if (message.type === "result") {
console.log(message.result);
}
}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 imagem, hooks, etc.
- 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 imagem diretos em mensagens
- Enfileiramento dinâmico de mensagens
- Interrupção em tempo real
- Integração de hooks
- Conversas multi-turno naturais
Exemplo de Implementação
import { query } from "@anthropic-ai/claude-agent-sdk";
// Consulta simples de uma única vez
for await (const message of query({
prompt: "Explique o fluxo de autenticação",
options: {
maxTurns: 1,
allowedTools: ["Read", "Grep"]
}
})) {
if (message.type === "result") {
console.log(message.result);
}
}
// Continuar conversa com gerenciamento de sessão
for await (const message of query({
prompt: "Agora explique o processo de autorização",
options: {
continue: true,
maxTurns: 1
}
})) {
if (message.type === "result") {
console.log(message.result);
}
}