​
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

​
Benefí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);
  }
}