Hosting dell'Agent SDK

​

Il modello subprocess

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

for await (const message of query({
  prompt: "Summarize the files in this directory",
  options: { cwd: "/work/session-a" },
})) {
  console.log(message);
}

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Summarize the files in this directory",
        options=ClaudeAgentOptions(cwd="/work/session-a"),
    ):
        print(message)


asyncio.run(main())

​

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

import asyncio
import os

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt=os.environ["TASK_PROMPT"],
        options=ClaudeAgentOptions(max_turns=20),
    ):
        print(message)


asyncio.run(main())

​

Sessioni a lunga durata

​

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

from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore
import asyncio

user_input: str = ...
session_id: str = ...              # looked up from your database by user
session_store: SessionStore = ...  # S3, Redis, Postgres, or your own adapter


async def main():
    async for message in query(
        prompt=user_input,
        options=ClaudeAgentOptions(
            resume=session_id,
            session_store=session_store,
        ),
    ):
        ...


asyncio.run(main())

​

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 modelli effimeri necessitano di avvii inferiori al secondo. I modelli a lunga durata tollerano di più.
• Archiviazione persistente: se il provider offre volumi durevoli o solo disco effimero. Il modello ibrido necessita di archiviazione durevole da qualche parte, sia nella sandbox che accanto ad essa.
• Modello di prezzo: fatturazione al secondo, per richiesta o a tariffa oraria fissa. La tariffazione al secondo si adatta bene ai carichi di lavoro effimeri bursty. La tariffa oraria si adatta bene alle sessioni a lunga durata.
• Networking: supporto per regole di egress personalizzate, proxy in uscita e peering VPC privato per ambienti regolamentati.

​

Dipendenze di runtime

• Python 3.10+ per l’SDK Python, o Node.js 18+ per l’SDK TypeScript
• Sia gli SDK TypeScript che Python includono un binario Claude Code nativo per la maggior parte delle installazioni, e la CLI generata non necessita di un’installazione separata di Node.js. Vedi la nota di installazione della guida rapida per le installazioni che necessitano di un’installazione separata di Claude Code nativo.

​

Risorse

​

Rete

​

Gestire i problemi 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 subprocess scrive prima su disco locale e l’SDK invia una copia di ogni batch all’archivio. La trascrizione locale di una sessione nuova sopravvive all’esecuzione; un’esecuzione ripresa dall’archivio elimina la sua copia locale alla fine, quindi l’archivio contiene l’unica copia durevole. Vedere Dual-write architecture.
• Messaggi mirror_error: quando l’SDK non riesce a consegnare un batch all’archivio, scarta il batch, emette un messaggio { type: "system", subtype: "mirror_error" } e continua la query. Avvertite su questi se la durabilità dell’archivio è importante. Vedere Mirror writes are best-effort per il comportamento di retry e timeout.

​

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

• Anthropic API: il subprocess 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 Credential management per il modello proxy e Setup in the SDK quickstart 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.

​

Scaling e concorrenza

agents per host = (host RAM - overhead) / (per-session RAM ceiling)

​

Costo

​

Isolamento multi-tenant

• Passate settingSources: [] in TypeScript o setting_sources=[] in Python per saltare le impostazioni utente, progetto e locali.
• Impostate CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env. Auto memory a ~/.claude/projects/<project>/memory/ si carica nel prompt di sistema indipendentemente da settingSources. Vedere What settingSources does not control per gli altri input che si caricano incondizionatamente.
• Puntate CLAUDE_CONFIG_DIR a una directory per tenant in modo che i tenant non condividano la configurazione globale ~/.claude.json. Quando ogni directory di configurazione serve una directory di lavoro e non condividete un SessionStore tra i tenant, potete anche impostare CLAUDE_CODE_PROJECT_DIR_NAME in env per mantenere i percorsi delle trascrizioni sotto di esso brevi. Richiede Agent SDK TypeScript v0.3.234 o successivo, oppure Agent SDK Python v0.2.140 o successivo.
• Utilizzate una directory di lavoro per tenant. Passate cwd esplicitamente su ogni chiamata query().
• Applicate regole di egress per tenant al vostro proxy, come IP in uscita distinti, credenziali o allowlist di domini, 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",
    },
  },
})) {
  // ...
}

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio

prompt: str = ...
tenant_dir: str = ...
config_dir: str = ...


async def main():
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(
            cwd=tenant_dir,
            setting_sources=[],
            env={
                "CLAUDE_CONFIG_DIR": config_dir,
                "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
            },
        ),
    ):
        ...


asyncio.run(main())

​

Limitazioni note

​

Risolvere i problemi di distribuzione

• CLI non trovata all’avvio del servizio: in Python, un contenitore o un gestore di servizi esegue la tua applicazione con un PATH diverso dalla tua shell, quindi un’installazione che funziona localmente non è visibile al processo. In TypeScript, la compilazione dell’immagine ha saltato le dipendenze opzionali dell’SDK, oppure pathToClaudeCodeExecutable punta a un file che non esiste nell’immagine. Vedi Claude Code non trovato.
• CLI presente nell’immagine ma non si avvia: Claude Code non può avviarsi da un binario che non corrisponde all’architettura del contenitore o a libc, oppure da un file che ha perso il permesso di esecuzione nella compilazione dell’immagine. Vedi Impossibile avviare Claude Code.
• Il processo Claude Code esce durante l’esecuzione: l’errore che la tua applicazione riceve dipende dal linguaggio dell’SDK e dal fatto che la CLI abbia segnalato un risultato di errore per primo. Le voci sotto Uscita del processo CLI coprono ogni messaggio.

​

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.