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

Requisiti di Hosting

Sandboxing Basato su Container

Per la sicurezza e l'isolamento, l'SDK dovrebbe essere eseguito all'interno di un ambiente container sandboxato. Questo fornisce isolamento dei processi, limiti di risorse, controllo di rete e filesystem effimeri.

L'SDK supporta anche configurazione sandbox programmatica per l'esecuzione dei comandi.

Requisiti di Sistema

Ogni istanza SDK richiede:

• Dipendenze di 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 di risorse

  • Consigliato: 1GiB RAM, 5GiB di disco e 1 CPU (varia questo in base alle tue esigenze)

• Accesso di rete

  • HTTPS in uscita a api.anthropic.com
  • Opzionale: Accesso ai server MCP o strumenti esterni

Comprensione dell'Architettura SDK

A differenza delle chiamate API senza stato, Claude Agent SDK opera come un processo a lunga esecuzione che:

• Esegue comandi in un ambiente shell persistente
• Gestisce operazioni su file all'interno di una directory di lavoro
• Gestisce l'esecuzione di strumenti con contesto dalle interazioni precedenti

Opzioni di Provider Sandbox

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

• Modal Sandbox - demo implementation
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

Per opzioni self-hosted (Docker, gVisor, Firecracker) e configurazione dettagliata dell'isolamento, vedi Isolation Technologies.

Pattern di Distribuzione in Produzione

Pattern 1: Sessioni Effimere

Crea un nuovo container per ogni attività dell'utente, quindi distruggilo al completamento.

Ideale per attività una tantum, l'utente può ancora interagire con l'AI mentre l'attività è in corso, ma una volta completata il container viene distrutto.

Esempi:

• Bug Investigation & Fix: Esegui il debug e risolvi un problema specifico con il contesto rilevante
• Invoice Processing: Estrai e struttura i dati da ricevute/fatture per i sistemi contabili
• Translation Tasks: Traduci documenti o batch di contenuti tra lingue
• Image/Video Processing: Applica trasformazioni, ottimizzazioni o estrai metadati da file multimediali

Pattern 2: Sessioni a Lunga Esecuzione

Mantieni istanze di container persistenti per attività a lunga esecuzione. Spesso esegui più processi Claude Agent all'interno del container in base alla domanda.

Ideale per agenti proattivi che agiscono senza l'input dell'utente, agenti che servono contenuti o agenti che elaborano grandi quantità di messaggi.

Esempi:

• Email Agent: Monitora i messaggi di posta in arrivo e autonomamente li smista, risponde o intraprende azioni in base al contenuto
• Site Builder: Ospita siti web personalizzati per utente con capacità di modifica in tempo reale servite attraverso porte container
• High-Frequency Chat Bots: Gestisce flussi di messaggi continui da piattaforme come Slack dove i tempi di risposta rapidi sono critici

Pattern 3: Sessioni Ibride

Container effimeri che vengono idratati con cronologia e stato, possibilmente da un database o dalle funzionalità di ripresa della sessione dell'SDK.

Ideale per container con interazione intermittente dall'utente che avvia il lavoro e si spegne quando il lavoro è completato ma può essere continuato.

Esempi:

• Personal Project Manager: Aiuta a gestire progetti in corso con check-in intermittenti, mantiene il contesto di attività, decisioni e progressi
• Deep Research: Conduce attività di ricerca multi-ora, salva i risultati e riprende l'indagine quando l'utente ritorna
• Customer Support Agent: Gestisce ticket di supporto che si estendono su più interazioni, carica la cronologia dei ticket e il contesto del cliente

Pattern 4: Container Singoli

Esegui più processi Claude Agent SDK in un container globale.

Ideale per agenti che devono collaborare strettamente insieme. Questo è probabilmente il pattern meno popolare perché dovrai impedire agli agenti di sovrascrivere l'uno l'altro.

Esempi:

• Simulations: Agenti che interagiscono tra loro in simulazioni come videogiochi.

FAQ

Come comunico con i miei sandbox?

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

Qual è il costo dell'hosting di un container?

Abbiamo scoperto che il costo dominante della gestione degli agenti è i token, i container variano in base a quello che provisioni ma un costo minimo è approssimativamente 5 centesimi all'ora di esecuzione.

Quando dovrei spegnere i container inattivi rispetto a mantenerli caldi?

Questo è probabilmente dipendente dal provider, diversi provider sandbox ti permetteranno di impostare criteri diversi per i timeout di inattività dopo i quali un sandbox potrebbe spegnersi. Vorrai sintonizzare questo timeout in base a quanto frequentemente pensi che la risposta dell'utente potrebbe essere.

Con quale frequenza dovrei aggiornare Claude Code CLI?

Claude Code CLI è versionato con semver, quindi eventuali modifiche di rottura saranno versionate.

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

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

Quanto tempo può durare una sessione di agente prima del timeout?

Una sessione di agente non andrà in timeout, ma consigliamo di impostare una proprietà 'maxTurns' per impedire a Claude di rimanere bloccato in un ciclo.

Passaggi Successivi

• Secure Deployment - Controlli di rete, gestione delle credenziali e indurimento dell'isolamento
• TypeScript SDK - Sandbox Settings - Configura sandbox programmaticamente
• Sessions Guide - Scopri la gestione delle sessioni
• Permissions - Configura i permessi degli strumenti
• Cost Tracking - Monitora l'utilizzo dell'API
• MCP Integration - Estendi con strumenti personalizzati