Skip to main content

Descripción General

El Claude Agent SDK admite dos modos de entrada distintos para interactuar con agentes:
  • Modo de Entrada de Streaming: 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
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, muestra solicitudes de permisos y gestiona la sesión.

Beneficios

En el modo de entrada de streaming, usted trabaja en una sesión persistente con estas capacidades:
  • Cargas de imágenes: adjunte imágenes directamente a los mensajes para análisis visual y comprensión
  • Mensajes en cola: envíe múltiples mensajes que se procesen secuencialmente, con capacidad de interrumpir
  • Integración de herramientas: acceso completo a todas las herramientas y servidores MCP personalizados durante la sesión
  • Retroalimentación en tiempo real: vea las respuestas mientras se generan, no solo los resultados finales
  • Persistencia de contexto: mantenga el contexto de la conversación en múltiples turnos de forma natural

Ejemplo de Implementación

Estos ejemplos leen una imagen llamada diagram.png del directorio de trabajo. Cree una allí primero, o cambie el nombre del archivo para que apunte a su propia imagen.
Cuando ejecuta el ejemplo, la versión de TypeScript imprime cada respuesta a medida que se completa. El bucle receive_response() de la versión de Python termina en el primer mensaje de resultado, por lo que imprime el análisis de seguridad; para leer ambas respuestas, use un par query() y receive_response() por mensaje como se muestra en el ejemplo de referencia de Python sobre cómo continuar una conversación. Si falta el source de un bloque de imagen o no es un objeto, el SDK no reporta un error. Claude Code envía a Claude una nota de texto en lugar de la imagen, como [Image could not be processed: image block has no source object], y la sesión continúa.
En el SDK de TypeScript, si su generador de mensajes lanza una excepción, por ejemplo cuando falta un archivo que lee, la secuencia termina con un error que dice Claude Code process aborted by user en lugar del error original, así que verifique el código dentro de su generador primero cuando vea ese mensaje. El error también puede estar precedido por una línea minificada larga del código fuente del SDK agrupado, así que lea hasta el final de la salida para encontrar el texto del error.En el SDK de Python, una excepción del generador se registra en el nivel de depuración y la sesión se detiene sin generar una excepción, así que si una sesión de streaming se cuelga sin salida, habilite el registro de depuración y verifique su generador.

Entrada de Mensaje Único

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

Cuándo Usar Entrada de Mensaje Único

Use entrada de mensaje único cuando:
  • Necesite una respuesta de una sola vez
  • No necesite adjuntos de imágenes ni métodos de control a mitad de sesión
  • Necesite 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
  • Conversaciones naturales de múltiples turnos
Si una consulta termina con un resultado de error, como error_max_turns, una llamada única a query() genera un error que incluye el texto de fallo después de ceder el mensaje de resultado final, así que envuelva el bucle en un bloque try si su código necesita continuar. Consulte Manejar el resultado para los subtipos de resultado.

Ejemplo de Implementación

Cuando ejecute el ejemplo, cada consulta imprime su texto de resultado final: primero la explicación de autenticación, luego la explicación de autorización.