Alojamiento del Agent SDK

​

El modelo de subproceso

query({ prompt, options: { cwd: "/work/session-a" } })

​

Estado que vive en el disco local

​

Elegir un patrón de sesión

​

Sesiones efímeras

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

const prompt = process.env.TASK_PROMPT!;
for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
  console.log(message);
}

​

Sesiones de larga duración

​

Sesiones híbridas

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

declare const userInput: string;
declare const sessionId: string;          // looked up from your database by user
declare const sessionStore: SessionStore; // S3, Redis, Postgres, or your own adapter

for await (const message of query({
  prompt: userInput,
  options: { resume: sessionId, sessionStore },
})) {
  // ...
}

​

Contenedor multiagente

​

Aprovisionar el contenedor

​

Sandboxing basado en contenedor

• Quién ejecuta el sandbox: un proveedor de sandbox-as-a-service opera la infraestructura para usted, mientras que las opciones autohospedadas le proporcionan software para ejecutar en su propio servidor.
• Latencia de inicio en frío: cuánto tiempo desde “crear un sandbox” hasta “listo para aceptar la primera solicitud”. Los patrones efímeros necesitan inicios subsegundos. Los patrones de larga duración toleran más.
• Almacenamiento persistente: si el proveedor ofrece volúmenes duraderos o solo disco efímero. El patrón híbrido necesita almacenamiento duradero en algún lugar, ya sea en el sandbox o junto a él.
• Modelo de precios: facturación por segundo, por solicitud u horaria plana. La facturación por segundo se adapta bien a cargas de trabajo efímeras intermitentes. La facturación horaria se adapta a sesiones de larga duración.
• Redes: soporte para reglas de salida personalizadas, proxies salientes y emparejamiento privado de VPC para entornos regulados.

• Modal Sandbox, con una implementación de demostración
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

​

Dependencias de tiempo de ejecución

• Python 3.10+ para el SDK de Python, o Node.js 18+ para el SDK de TypeScript
• Ambos paquetes SDK incluyen un binario nativo de Claude Code para la plataforma del host, por lo que no se necesita una instalación separada de Claude Code o Node.js para la CLI generada

​

Recursos

​

Red

​

Gestionar preocupaciones de producción

​

Persistencia de sesión y estado

• Solo transcripciones: SessionStore refleja transcripciones, no archivos de memoria CLAUDE.md u otros artefactos del directorio de trabajo. Monte un volumen compartido o sincronice esos por separado.
• Reflejo, no reemplazo: el subproceso escribe en el disco local primero, y el almacén recibe una copia de cada lote. Las escrituras locales siguen siendo autoritativas.
• Mensajes mirror_error: si el almacén rechaza o agota el tiempo de espera, el SDK emite un mensaje { type: "system", subtype: "mirror_error" } y continúa la consulta sin reintentos. Alerte sobre estos si la durabilidad del almacén es importante.

​

Observabilidad

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318

​

Autenticación y secretos

• API de Anthropic: el subproceso lee ANTHROPIC_API_KEY de su entorno. Suministrelo desde su gestor de secretos, o establezca ANTHROPIC_BASE_URL para enrutar llamadas de modelo a través de un proxy que inyecte la clave fuera del contenedor. Consulte Gestión de credenciales para el patrón de proxy y la descripción general del SDK para los métodos de autenticación admitidos.
• Entrada: coloque la autenticación en una puerta de enlace frente al contenedor del agente. El agente debe recibir solicitudes preauthenticadas y no debe ser el componente que valide los tokens del usuario.
• Herramientas salientes: mantenga las credenciales de herramientas fuera del entorno del agente. Enrute las llamadas salientes a través de un proxy que inyecte claves API después de que la solicitud salga del contenedor. El agente realiza la llamada; el proxy añade la credencial.

​

Escalado y concurrencia

agentes por host = (RAM del host - sobrecarga) / (límite máximo de RAM por sesión)

​

Costo

​

Aislamiento multiinquilino

• Pase settingSources: [] en TypeScript o setting_sources=[] en Python para que no se cargue ninguna configuración del sistema de archivos.
• Establezca CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 en env. Auto memory en ~/.claude/projects/<project>/memory/ se carga en el mensaje del sistema independientemente de settingSources. Consulte Lo que settingSources no controla para las otras entradas que se cargan incondicionalmente.
• Apunte CLAUDE_CONFIG_DIR a un directorio por inquilino para que los inquilinos no compartan la configuración global ~/.claude.json.
• Use un directorio de trabajo por inquilino. Pase cwd explícitamente en cada llamada query().
• Aplique reglas de salida por inquilino en su proxy, como IPs salientes distintas, credenciales o listas de permitidos de dominio, para que un inquilino comprometido no pueda exfiltrar datos a través de la política de salida de otro inquilino.

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

declare const prompt: string;
declare const tenantDir: string;
declare const configDir: string;

for await (const message of query({
  prompt,
  options: {
    cwd: tenantDir,
    settingSources: [],
    env: {
      ...process.env,
      CLAUDE_CONFIG_DIR: configDir,
      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
    },
  },
})) {
  // ...
}

​

Limitaciones conocidas

​

Próximos pasos

• Guía de alojamiento: recorrido por el notebook con código implementable para Docker, Modal y Kubernetes.
• Almacenamiento de sesiones: persistir transcripciones entre hosts con un adaptador SessionStore.
• Observabilidad: exportar trazas OTEL, métricas y registros a su recopilador.
• Implementación segura: controles de red, gestión de credenciales y endurecimiento de aislamiento.
• Seguimiento de costos: contabilidad de tokens y costos por sesión.