​
Descripción General

El Claude Code SDK admite dos modos de entrada distintos para interactuar con agentes:
  • Modo de Entrada de Streaming (Predeterminado y Recomendado) - Una sesión persistente e interactiva
  • Entrada de Mensaje Único - Consultas de una sola vez que usan el estado de sesión y la reanudación
Esta guía explica las diferencias, beneficios y casos de uso para cada modo para ayudarte a elegir el enfoque correcto para tu aplicación.

​
Modo de Entrada de Streaming (Recomendado)

El modo de entrada de streaming es la forma preferida de usar el Claude Code SDK. Proporciona acceso completo a las capacidades del agente y permite experiencias ricas e interactivas. Permite que el agente opere como un proceso de larga duración que recibe entrada del usuario, maneja interrupciones, presenta solicitudes de permisos y maneja la gestión de sesiones.

​
Cómo Funciona

​
Beneficios

Subida de Imágenes

Adjunta imágenes directamente a los mensajes para análisis visual y comprensión

Mensajes en Cola

Envía múltiples mensajes que se procesan secuencialmente, con capacidad de interrumpir

Integración de Herramientas

Acceso completo a todas las herramientas y servidores MCP personalizados durante la sesión

Soporte de Hooks

Usa hooks de ciclo de vida para personalizar el comportamiento en varios puntos

Retroalimentación en Tiempo Real

Ve las respuestas mientras se generan, no solo los resultados finales

Persistencia de Contexto

Mantén el contexto de conversación a través de múltiples turnos naturalmente

​
Ejemplo de Implementación

import { query } from "@anthropic-ai/claude-code";
import { readFileSync } from "fs";

async function* generateMessages() {
  // Primer mensaje
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Analiza esta base de código para problemas de seguridad"
    }
  };
  
  // Esperar condiciones o entrada del usuario
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Seguimiento con imagen
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Revisa este diagrama de arquitectura"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// Procesar respuestas 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 Mensaje Único

La entrada de mensaje único es más simple pero más limitada.

​
Cuándo Usar Entrada de Mensaje Único

Usa entrada de mensaje único cuando:
  • Necesites una respuesta de una sola vez
  • No necesites adjuntos de imagen, hooks, etc.
  • Necesites operar en un entorno sin estado, como una función lambda

​
Limitaciones

El modo de entrada de mensaje único no admite:
  • Adjuntos de imagen directos en mensajes
  • Encolado dinámico de mensajes
  • Interrupción en tiempo real
  • Integración de hooks
  • Conversaciones naturales de múltiples turnos

​
Ejemplo de Implementación

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

// Consulta simple de una sola vez
for await (const message of query({
  prompt: "Explica el flujo de autenticación",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// Continuar conversación con gestión de sesión
for await (const message of query({
  prompt: "Ahora explica el proceso de autorización",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}