Guías

Entrada de Streaming

Comprensión de 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 persistente e interactiva
Entrada de Mensaje Único - Consultas de una sola vez que utilizan el estado de la 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 funcione como un proceso de larga duración que recibe entrada del usuario, maneja interrupciones, expone solicitudes de permisos y gestiona la sesión.

Cómo Funciona

Beneficios

Cargas de Imágenes

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

Mensajes en Cola

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

Integración de Herramientas

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

Soporte de Hooks

Utiliza 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 la conversación en múltiples turnos de forma natural

Ejemplo de Implementación

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

async function* generateMessages() {
  // First message
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Analyze this codebase for security issues"
    }
  };
  
  // Wait for conditions or user input
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Follow-up with image
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Review this architecture diagram"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// Process streaming responses
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 imágenes, 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 imágenes directas en mensajes
Encolamiento 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-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") {
    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") {
    console.log(message.result);
  }
}

Guías

Entrada de Streaming

Comprensión de 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 persistente e interactiva
Entrada de Mensaje Único - Consultas de una sola vez que utilizan el estado de la 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 funcione como un proceso de larga duración que recibe entrada del usuario, maneja interrupciones, expone solicitudes de permisos y gestiona la sesión.

Cómo Funciona

Beneficios

Cargas de Imágenes

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

Mensajes en Cola

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

Integración de Herramientas

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

Soporte de Hooks

Utiliza 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 la conversación en múltiples turnos de forma natural

Ejemplo de Implementación

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

async function* generateMessages() {
  // First message
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Analyze this codebase for security issues"
    }
  };
  
  // Wait for conditions or user input
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Follow-up with image
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Review this architecture diagram"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// Process streaming responses
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 imágenes, 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 imágenes directas en mensajes
Encolamiento 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-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") {
    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") {
    console.log(message.result);
  }
}