Hosting dell'Agent SDK

​

Il modello subprocess

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

​

Stato che risiede su disco locale

​

Scegliere un modello di sessione

​

Sessioni effimere

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

​

Sessioni a lunga esecuzione

​

Sessioni ibride

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 },
})) {
  // ...
}

​

Container multi-agente

​

Provisioning del container

​

Sandboxing basato su container

• Chi gestisce la sandbox: un provider sandbox-as-a-service gestisce l’infrastruttura per te, mentre le opzioni self-hosted ti forniscono il software da eseguire sulla tua infrastruttura.
• Latenza di cold-start: quanto tempo passa da “crea una sandbox” a “pronto ad accettare la prima richiesta”. I pattern effimeri necessitano di avvii sub-secondo. I pattern a lunga durata tollerano di più.
• Archiviazione persistente: se il provider offre volumi durevoli o solo disco effimero. Il pattern ibrido necessita di archiviazione durevole da qualche parte, sia nella sandbox che accanto ad essa.
• Modello di prezzo: fatturazione per secondo, per richiesta o oraria fissa. La tariffazione per secondo si adatta ai carichi di lavoro effimeri bursty. La tariffazione oraria si adatta alle sessioni a lunga durata.
• Networking: supporto per regole di egress personalizzate, proxy in uscita e peering VPC privato per ambienti regolamentati.

• Modal Sandbox, con un’implementazione demo
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

​

Dipendenze di runtime

• Python 3.10+ per l’SDK Python, o Node.js 18+ per l’SDK TypeScript
• Entrambi i pacchetti SDK includono un binario Claude Code nativo per la piattaforma host, quindi non è necessaria un’installazione separata di Claude Code o Node.js per la CLI generata

​

Risorse

​

Rete

​

Gestire le preoccupazioni di produzione

​

Persistenza della sessione e dello stato

• Solo trascrizioni: SessionStore esegue il mirroring delle trascrizioni, non dei file di memoria CLAUDE.md o di altri artefatti della directory di lavoro. Montate un volume condiviso o sincronizzate quelli separatamente.
• Mirroring, non sostituzione: il sottoprocesso scrive su disco locale per primo, e l’archivio riceve una copia di ogni batch. Le scritture locali rimangono autorevoli.
• Messaggi mirror_error: se l’archivio rifiuta o scade, l’SDK emette un messaggio { type: "system", subtype: "mirror_error" } e continua la query senza riprovare. Avvertite su questi se la durabilità dell’archivio è importante.

​

Osservabilità

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

​

Autenticazione e segreti

• API Anthropic: il sottoprocesso legge ANTHROPIC_API_KEY dal suo ambiente. Forniscilo dal vostro gestore di segreti, oppure imposta ANTHROPIC_BASE_URL per instradare le chiamate del modello attraverso un proxy che inietta la chiave al di fuori del container. Vedere Gestione delle credenziali per il pattern del proxy e la Panoramica dell’SDK per i metodi di autenticazione supportati.
• In entrata: mettete l’autenticazione a un gateway davanti al container dell’agente. L’agente dovrebbe ricevere richieste pre-autenticate e non dovrebbe essere il componente che convalida i token dell’utente.
• Strumenti in uscita: mantenete le credenziali degli strumenti fuori dall’ambiente dell’agente. Instradare le chiamate in uscita attraverso un proxy che inietta le chiavi API dopo che la richiesta esce dal container. L’agente effettua la chiamata; il proxy aggiunge la credenziale.

​

Scalabilità e concorrenza

agenti per host = (RAM host - overhead) / (limite massimo RAM per sessione)

​

Costo

​

Isolamento multi-tenant

• Passate settingSources: [] in TypeScript o setting_sources=[] in Python in modo che nessuna impostazione del filesystem venga caricata.
• Impostate CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env. La memoria automatica in ~/.claude/projects/<project>/memory/ viene caricata nel prompt di sistema indipendentemente da settingSources. Vedere Cosa settingSources non controlla per gli altri input che vengono caricati incondizionatamente.
• Puntate CLAUDE_CONFIG_DIR a una directory per tenant in modo che i tenant non condividano la configurazione globale ~/.claude.json.
• Utilizzate una directory di lavoro per tenant. Passate cwd esplicitamente su ogni chiamata query().
• Applicate regole di uscita per tenant al vostro proxy, come IP in uscita distinti, credenziali o elenchi di domini consentiti, in modo che un tenant compromesso non possa esfiltare dati tramite la politica in uscita di un altro tenant.

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",
    },
  },
})) {
  // ...
}

​

Limitazioni note

​

Passaggi successivi

• Hosting cookbook: procedura dettagliata del notebook con codice distribuibile per Docker, Modal e Kubernetes.
• Session storage: mantieni i transcript tra gli host con un adattatore SessionStore.
• Observability: esporta tracce OTEL, metriche e log al tuo collector.
• Secure deployment: controlli di rete, gestione delle credenziali e indurimento dell’isolamento.
• Cost tracking: contabilità dei token e dei costi per sessione.