Guías

Entrada de Streaming

Comprendiendo los dos modos de entrada para Claude Agent SDK y cuándo usar cada uno

Descripción General

El Claude Agent SDK admite dos modos de entrada distintos para interactuar con agentes:

Modo de Entrada de Streaming (Predeterminado y Recomendado) - Una sesión interactiva persistente
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 Agent 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 gestiona la administració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-agent-sdk";
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 multi-turno naturales

Ejemplo de Implementación

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

// 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);
  }
}

Guías

Entrada de Streaming

Comprendiendo los dos modos de entrada para Claude Agent SDK y cuándo usar cada uno

Descripción General

El Claude Agent SDK admite dos modos de entrada distintos para interactuar con agentes:

Modo de Entrada de Streaming (Predeterminado y Recomendado) - Una sesión interactiva persistente
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 Agent 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 gestiona la administració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-agent-sdk";
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 multi-turno naturales

Ejemplo de Implementación

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

// 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);
  }
}