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

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
import { readFile } from "fs/promises";

async function* generateMessages(): AsyncGenerator<SDKUserMessage> {
  // First message
  yield {
    type: "user",
    message: {
      role: "user",
      content: "Analyze this codebase for security issues"
    },
    parent_tool_use_id: null
  };

  // Wait for conditions or user input
  await new Promise((resolve) => setTimeout(resolve, 2000));

  // Follow-up with image
  yield {
    type: "user",
    message: {
      role: "user",
      content: [
        {
          type: "text",
          text: "Review this architecture diagram"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: await readFile("diagram.png", "base64")
          }
        }
      ]
    },
    parent_tool_use_id: null
  };
}

// Process streaming responses
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 10,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
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

import { query } from "@anthropic-ai/claude-agent-sdk";

// Simple one-shot query
for await (const message of query({
  prompt: "Explain the authentication flow",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

// Continue conversation with session management
for await (const message of query({
  prompt: "Now explain the authorization process",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}