​
Hosting dell’Agent SDK

Il Claude Agent SDK differisce dalle tradizionali API LLM stateless in quanto mantiene lo stato conversazionale ed esegue comandi in un ambiente persistente. Questa guida copre l’architettura, le considerazioni di hosting e le migliori pratiche per distribuire agenti basati su SDK in produzione.

​
Comprendere l’Architettura SDK

​
Modello di Processo Long-Running

A differenza delle chiamate API stateless, il Claude Agent SDK opera come un processo long-running che:
  • Esegue comandi in un ambiente shell persistente
  • Gestisce operazioni sui file all’interno di una directory di lavoro
  • Gestisce l’esecuzione di strumenti con contesto dalle interazioni precedenti

​
Requisiti di Hosting

​
Sandboxing Basato su Container

Per sicurezza e isolamento, l’SDK dovrebbe essere eseguito all’interno di un ambiente container sandboxed. Questo fornisce:
  • Isolamento dei processi - Ambiente di esecuzione separato per sessione
  • Limiti delle risorse - Vincoli di CPU, memoria e storage
  • Controllo di rete - Limitare le connessioni in uscita
  • Filesystem effimeri - Stato pulito per ogni sessione

​
Requisiti di Sistema

Ogni istanza SDK richiede:
  • Dipendenze runtime
    • Python 3.10+ (per Python SDK) o Node.js 18+ (per TypeScript SDK)
    • Node.js (richiesto da Claude Code CLI)
    • Claude Code CLI: npm install -g @anthropic-ai/claude-code
  • Allocazione delle risorse
    • Raccomandato: 1GiB RAM, 5GiB di disco, e 1 CPU (varia questo in base al tuo compito secondo necessità)
  • Accesso di rete
    • HTTPS in uscita verso api.anthropic.com
    • Opzionale: Accesso a server MCP o strumenti esterni

​
Opzioni Provider Sandbox

Diversi provider si specializzano in ambienti container sicuri per l’esecuzione di codice AI:

​
Pattern di Distribuzione in Produzione

​
Pattern 1: Sessioni Effimere

Crea un nuovo container per ogni compito utente, poi distruggilo quando completato. Migliore per compiti una tantum, l’utente può ancora interagire con l’AI mentre il compito si sta completando, ma una volta completato il container viene distrutto. Esempi:
  • Investigazione e Risoluzione Bug: Debug e risoluzione di un problema specifico con contesto rilevante
  • Elaborazione Fatture: Estrazione e strutturazione dati da ricevute/fatture per sistemi contabili
  • Compiti di Traduzione: Traduzione di documenti o lotti di contenuti tra lingue
  • Elaborazione Immagini/Video: Applicazione di trasformazioni, ottimizzazioni, o estrazione metadati da file media

​
Pattern 2: Sessioni Long-Running

Mantieni istanze container persistenti per compiti long running. Spesso eseguendo multipli processi Claude Agent all’interno del container basati sulla domanda. Migliore per agenti proattivi che intraprendono azioni senza input dell’utente, agenti che servono contenuti o agenti che elaborano grandi quantità di messaggi. Esempi:
  • Agente Email: Monitora email in arrivo e autonomamente smista, risponde, o intraprende azioni basate sul contenuto
  • Site Builder: Ospita siti web personalizzati per utente con capacità di editing live servite attraverso porte container
  • Chat Bot ad Alta Frequenza: Gestisce flussi continui di messaggi da piattaforme come Slack dove tempi di risposta rapidi sono critici

​
Pattern 3: Sessioni Ibride

Container effimeri che sono idratati con cronologia e stato, possibilmente da un database o dalle funzionalità di ripresa sessione dell’SDK. Migliore per container con interazione intermittente dall’utente che avvia lavoro e si spegne quando il lavoro è completato ma può essere continuato. Esempi:
  • Manager Progetto Personale: Aiuta a gestire progetti in corso con check-in intermittenti, mantiene contesto di compiti, decisioni e progressi
  • Ricerca Approfondita: Conduce compiti di ricerca multi-ora, salva scoperte e riprende investigazione quando l’utente ritorna
  • Agente Supporto Clienti: Gestisce ticket di supporto che si estendono su multiple interazioni, carica cronologia ticket e contesto cliente

​
Pattern 4: Container Singoli

Esegui multipli processi Claude Agent SDK in un container globale. Migliore per agenti che devono collaborare strettamente insieme. Questo è probabilmente il pattern meno popolare perché dovrai prevenire che gli agenti si sovrascrivano a vicenda. Esempi:
  • Simulazioni: Agenti che interagiscono tra loro in simulazioni come videogiochi.

​
FAQ

​
Come comunico con i miei sandbox?

Quando ospiti in container, esponi porte per comunicare con le tue istanze SDK. La tua applicazione può esporre endpoint HTTP/WebSocket per client esterni mentre l’SDK gira internamente all’interno del container.

​
Qual è il costo di hosting di un container?

Abbiamo scoperto che il costo dominante di servire agenti sono i token, i container variano basati su quello che provvedi ma un costo minimo è approssimativamente 5 centesimi per ora di esecuzione.

​
Quando dovrei spegnere container inattivi vs. mantenerli caldi?

Questo è probabilmente dipendente dal provider, diversi provider sandbox ti permetteranno di impostare diversi criteri per timeout di inattività dopo i quali un sandbox potrebbe spegnersi. Vorrai sintonizzare questo timeout basato su quanto frequente pensi che la risposta utente possa essere.

​
Quanto spesso dovrei aggiornare il Claude Code CLI?

Il Claude Code CLI è versionato con semver, quindi qualsiasi cambiamento breaking sarà versionato.

​
Come monitoro la salute del container e le prestazioni dell’agente?

Dato che i container sono solo server la stessa infrastruttura di logging che usi per il backend funzionerà per i container.

​
Quanto a lungo può durare una sessione agente prima del timeout?

Una sessione agente non andrà in timeout, ma raccomandiamo di impostare una proprietà ‘maxTurns’ per prevenire che Claude rimanga bloccato in un loop.

​
Prossimi Passi