El Claude Agent SDK difiere de las API LLM tradicionales sin estado en que mantiene el estado conversacional y ejecuta comandos en un entorno persistente. Esta guía cubre la arquitectura, consideraciones de alojamiento y mejores prácticas para implementar agentes basados en SDK en producción.

​
Requisitos de Alojamiento

​
Aislamiento en Contenedores

Por seguridad y aislamiento, el SDK debe ejecutarse dentro de un entorno de contenedor aislado. Esto proporciona:
  • Aislamiento de procesos - Entorno de ejecución separado por sesión
  • Límites de recursos - Restricciones de CPU, memoria y almacenamiento
  • Control de red - Restringir conexiones salientes
  • Sistemas de archivos efímeros - Estado limpio para cada sesión

​
Requisitos del Sistema

Cada instancia del SDK requiere:
  • Dependencias de tiempo de ejecución
    • Python 3.10+ (para Python SDK) o Node.js 18+ (para TypeScript SDK)
    • Node.js (requerido por Claude Code CLI)
    • Claude Code CLI: npm install -g @anthropic-ai/claude-code
  • Asignación de recursos
    • Recomendado: 1GiB de RAM, 5GiB de disco y 1 CPU (varía esto según tu tarea según sea necesario)
  • Acceso de red
    • HTTPS saliente a api.anthropic.com
    • Opcional: Acceso a servidores MCP o herramientas externas

​
Comprensión de la Arquitectura del SDK

A diferencia de las llamadas API sin estado, el Claude Agent SDK opera como un proceso de larga duración que:
  • Ejecuta comandos en un entorno de shell persistente
  • Gestiona operaciones de archivos dentro de un directorio de trabajo
  • Maneja la ejecución de herramientas con contexto de interacciones anteriores

​
Opciones de Proveedores de Sandbox

Varios proveedores se especializan en entornos de contenedores seguros para la ejecución de código de IA:

​
Patrones de Implementación en Producción

​
Patrón 1: Sesiones Efímeras

Crea un nuevo contenedor para cada tarea del usuario, luego destrúyelo cuando se complete. Mejor para tareas puntuales, el usuario aún puede interactuar con la IA mientras se completa la tarea, pero una vez completada el contenedor se destruye. Ejemplos:
  • Investigación y Corrección de Errores: Depura y resuelve un problema específico con contexto relevante
  • Procesamiento de Facturas: Extrae y estructura datos de recibos/facturas para sistemas contables
  • Tareas de Traducción: Traduce documentos o lotes de contenido entre idiomas
  • Procesamiento de Imágenes/Vídeos: Aplica transformaciones, optimizaciones o extrae metadatos de archivos multimedia

​
Patrón 2: Sesiones de Larga Duración

Mantén instancias de contenedor persistentes para tareas de larga duración. A menudo ejecutando múltiples procesos Claude Agent dentro del contenedor según la demanda. Mejor para agentes proactivos que toman acciones sin la entrada del usuario, agentes que sirven contenido o agentes que procesan grandes cantidades de mensajes. Ejemplos:
  • Agente de Correo Electrónico: Monitorea correos electrónicos entrantes y automáticamente clasifica, responde o toma acciones basadas en el contenido
  • Constructor de Sitios: Aloja sitios web personalizados por usuario con capacidades de edición en vivo servidas a través de puertos de contenedor
  • Chatbots de Alta Frecuencia: Maneja flujos continuos de mensajes de plataformas como Slack donde los tiempos de respuesta rápidos son críticos

​
Patrón 3: Sesiones Híbridas

Contenedores efímeros que se hidratan con historial y estado, posiblemente desde una base de datos o desde las características de reanudación de sesión del SDK. Mejor para contenedores con interacción intermitente del usuario que inicia trabajo y se apaga cuando se completa el trabajo pero puede continuarse. Ejemplos:
  • Gestor de Proyectos Personal: Ayuda a gestionar proyectos en curso con verificaciones intermitentes, mantiene contexto de tareas, decisiones y progreso
  • Investigación Profunda: Realiza tareas de investigación de varias horas, guarda hallazgos y reanuda la investigación cuando el usuario regresa
  • Agente de Soporte al Cliente: Maneja tickets de soporte que abarcan múltiples interacciones, carga el historial de tickets y contexto del cliente

​
Patrón 4: Contenedores Únicos

Ejecuta múltiples procesos Claude Agent SDK en un contenedor global único. Mejor para agentes que deben colaborar estrechamente. Este es probablemente el patrón menos popular porque tendrás que evitar que los agentes se sobrescriban entre sí. Ejemplos:
  • Simulaciones: Agentes que interactúan entre sí en simulaciones como videojuegos.

​
Preguntas Frecuentes

​
¿Cómo me comunico con mis sandboxes?

Al alojar en contenedores, expone puertos para comunicarte con tus instancias del SDK. Tu aplicación puede exponer puntos finales HTTP/WebSocket para clientes externos mientras el SDK se ejecuta internamente dentro del contenedor.

​
¿Cuál es el costo de alojar un contenedor?

Hemos encontrado que el costo dominante de servir agentes son los tokens, los contenedores varían según lo que aprovisiones pero un costo mínimo es aproximadamente 5 centavos por hora de ejecución.

​
¿Cuándo debo apagar contenedores inactivos versus mantenerlos activos?

Esto probablemente depende del proveedor, diferentes proveedores de sandbox te permitirán establecer diferentes criterios para tiempos de espera de inactividad después de los cuales un sandbox podría apagarse. Querrás ajustar este tiempo de espera según la frecuencia con la que creas que podría haber respuesta del usuario.

​
¿Con qué frecuencia debo actualizar Claude Code CLI?

Claude Code CLI se versionea con semver, por lo que cualquier cambio importante se versionará.

​
¿Cómo monitoreo la salud del contenedor y el rendimiento del agente?

Dado que los contenedores son solo servidores, la misma infraestructura de registro que usas para el backend funcionará para contenedores.

​
¿Cuánto tiempo puede ejecutarse una sesión de agente antes de agotarse el tiempo?

Una sesión de agente no se agotará, pero recomendamos establecer una propiedad ‘maxTurns’ para evitar que Claude se quede atrapado en un bucle.

​
Próximos Pasos