Creare un agente AI con Claude su un VPS

Cosa significa creare un agente con Claude

Creare un agente con Claude significa usare Claude come nucleo di ragionamento, mantenendo il ciclo di esecuzione, gli strumenti e i dati sul proprio server. Claude decide cosa fare; il VPS esegue le operazioni. Si inviano a Claude l'attività e lo stato corrente. Claude risponde con una risposta oppure con una richiesta di usare uno degli strumenti disponibili. Il codice esegue lo strumento e invia nuovamente il risultato. Il ciclo continua fino al completamento dell'attività. L'intelligenza è un servizio che si richiama tramite Internet. Tutto ciò che lo circonda è sotto il proprio controllo.

Questa separazione è il principale vantaggio. Si ottiene un ragionamento di livello avanzato senza dover gestire un modello. Inoltre, si mantiene il controllo completo sulle risorse che l'agente può utilizzare, perché gli strumenti vengono eseguiti su hardware di proprietà. Se è già stato creato un primo programma con Claude, la guida al primo programma Claude su un VPS descrive le basi su cui si fonda questo tutorial.

Claude è il cervello: la Messages API

Ogni chiamata a Claude passa attraverso un unico endpoint, la Messages API. Si inviano la conversazione fino a quel momento e l’elenco degli strumenti che l’agente può usare; Claude restituisce il messaggio successivo. Quel messaggio è una risposta finale oppure una richiesta di chiamata a uno strumento. Nel percorso di implementazione autonoma non esiste una «agent API» separata: l’uso degli strumenti è una funzionalità di questo unico endpoint e il ciclo che lo gestisce deve essere eseguito dal tuo codice.

Claude è stateless tra una chiamata e l’altra, quindi non conserva autonomamente alcuna informazione. Ogni richiesta contiene l’intera conversazione. Il codice conserva la cronologia e la invia a ogni turno, ed è per questo che ogni turno di una sessione lunga consuma più token del precedente. Non si tratta tanto di una limitazione quanto di una scelta progettuale: poiché lo stato risiede sul tuo server, decidi esattamente quali informazioni Claude può vedere e nessun dato relativo all’attività viene memorizzato in luoghi che non controlli. Il prompt continua però a crescere e, sebbene la finestra di contesto di Claude lo gestisca senza difficoltà, un modello locale inserito nello stesso ciclo non può farlo; per questo è necessario aumentare num_ctx in Ollama prima che inizi a troncare i prompt lunghi.

L’uso degli strumenti è il ciclo dell’agente

Il ciclo dell’agente con Claude è semplice da descrivere. Si invia una richiesta che include gli strumenti disponibili. Claude legge l’attività e, se deve eseguire un’azione, risponde con una richiesta di utilizzo di uno strumento, indicando lo strumento e compilando i relativi input. Il codice esegue lo strumento, quindi invia il risultato a Claude nella richiesta successiva. Claude legge il risultato e chiede un altro strumento oppure scrive la risposta finale. Quando smette di chiedere strumenti, l’attività è completata.

È possibile scrivere manualmente questo ciclo in poche righe, e molti lo fanno perché è facile da comprendere e da controllare. Anche gli SDK ufficiali forniscono un tool runner che gestisce il ciclo al posto dell’applicazione: si forniscono le funzioni degli strumenti e l’SDK gestisce lo scambio di richieste, l’invocazione di Claude, l’esecuzione degli strumenti e l’invio dei risultati finché Claude non ha terminato. In entrambi i casi, la struttura è la stessa. Il runner evita semplicemente di dover scrivere il ciclo. Se il ciclo sembra ancora astratto, conviene scriverne prima una versione minima, invece di usare subito un runner; è il passaggio da cui dipende tutto il resto in questo percorso graduale per imparare da zero a creare agenti AI.

Tre modi per creare un agente e scegliere quello adatto a un VPS

Esistono tre modi per creare un agente Claude. La differenza riguarda la quantità di componenti che si eseguono direttamente.

Il primo consiste nello scrivere codice che chiama l'API di Claude con strumenti propri. Puoi scrivere il ciclo di esecuzione oppure usare il tool runner dell'SDK, quindi ospitare l'intero sistema sul tuo VPS. Questa è la scelta più comune, perché offre il controllo completo sugli strumenti, sui dati e sulla sicurezza. Il sistema viene eseguito come un normale programma sul server. La maggior parte di questa guida presuppone questo approccio.

Il secondo è Claude Agent SDK. Si tratta di Claude Code, l'agente per la programmazione, distribuito come libreria su cui puoi costruire il tuo sistema. Include un ciclo completo dell'agente e strumenti integrati per leggere e scrivere file, eseguire comandi shell ed effettuare ricerche. Non devi quindi assemblare questi componenti da zero. Viene inoltre eseguito sul tuo server, quindi è particolarmente adatto a un VPS quando vuoi un agente capace di lavorare con file e shell senza dover creare tu stesso l'harness. Un agente che legge file ed esegue comandi shell deve essere confinato prima di poter funzionare senza supervisione. La guida eseguire Claude Code in sicurezza su un server descrive il sistema di autorizzazioni, la sandbox e le opzioni di isolamento.

Il terzo è Managed Agents, in cui Anthropic esegue il ciclo dell'agente. Per impostazione predefinita, gli strumenti dell'agente vengono eseguiti in una sandbox ospitata da Anthropic. Lo spazio di lavoro dell'agente risiede quindi sull'infrastruttura di Anthropic e non sul tuo VPS. All'11 ottobre 2026, un'opzione sandbox self-hosted, ancora in beta, consente a un processo worker sul tuo server di eseguire le chiamate agli strumenti mentre il ciclo resta gestito da Anthropic. Scegli Managed Agents quando vuoi ridurre al minimo il lavoro operativo e non ti serve che il ciclo venga eseguito direttamente sulla tua macchina. Negli altri due casi, il tuo server ospita l'intero agente. È questo l'argomento del resto della guida.

Collegare gli strumenti con MCP

Qualunque percorso si scelga, sarà necessario collegare l’agente a sistemi reali. Il Model Context Protocol è il modo più ordinato per farlo. MCP è uno standard aperto per esporre strumenti e dati a un agente. Invece di codificare manualmente un’integrazione per ogni servizio, si configura Claude in modo che utilizzi un server MCP che presenta già queste funzionalità come strumenti. È possibile eseguire i server MCP come piccoli servizi sullo stesso VPS, assegnando a ciascuno soltanto gli accessi necessari. Questo argomento è trattato in eseguire server MCP su un VPS.

Scelta del modello

Claude è disponibile in diversi modelli. La scelta comporta un compromesso tra capacità, velocità e costo. All'11 ottobre 2026, l'offerta corrente comprende Claude Opus 5.5 (claude-opus-5-5), che Anthropic consiglia come punto di partenza per la maggior parte dei carichi di lavoro e progetta per attività di coding agentico di lunga durata e lavoro sulla conoscenza; Claude Sonnet 5.5 (claude-sonnet-5-5), un'opzione equilibrata, più economica e veloce; e Claude Haiku 5.5 (claude-haiku-5-5), il modello più veloce ed economico, adatto alle operazioni semplici e ad alto volume. Al di sopra di questi si colloca Claude Fable 5.1 (claude-fable-5-1), il modello più capace disponibile per tutti i clienti, destinato al ragionamento complesso e al lavoro agentico su orizzonti temporali estesi. I modelli precedenti, come Claude Opus 4.8 e Claude Fable 5, sono ancora disponibili, ma ora sono classificati come legacy. Nel codice usa l'identificatore esatto del modello, senza aggiungere la data.

Un approccio pratico consiste nel combinarli. Affida a un modello più economico le chiamate di routine agli strumenti e a un modello più potente le decisioni complesse. Poiché nella richiesta il modello è semplicemente una stringa, per cambiarlo basta modificare una riga. Inizia quindi con un modello predefinito capace e passa a uno meno potente nei casi in cui velocità o costo siano più importanti dell'ultimo margine di qualità.

Eseguilo come servizio hardened sul tuo VPS

Un agent è utile solo se resta in esecuzione ed è sicuro solo se viene isolato. Su un VPS, entrambe le condizioni si ottengono eseguendo l'agent come servizio di sistema hardened, invece di avviarlo manualmente in un terminale. Come servizio, si avvia al boot, si riavvia in caso di crash e scrive i log nel journal. In modalità hardened, viene eseguito con un utente non privilegiato e dispone soltanto degli accessi necessari. In questo modo, un bug o un'istruzione dannosa hanno un impatto limitato. Un'unità di servizio può limitare ciò che il processo può modificare e la quantità di memoria, CPU e task che può utilizzare. Non può però valutare cosa l'agent decida di fare con questi accessi. Questa parte deve quindi essere gestita all'interno dell'harness dell'agent. È il compito svolto dai plugin DeepSeek Harness da installare su uno stack diverso: limiti di spesa, regole di autorizzazione per ogni tool e rilevamento dei prompt injection.

La regola più importante è mantenere la chiave API di Claude lato server. La chiave autorizza e addebita ogni chiamata. Deve quindi essere archiviata in un file leggibile soltanto dall'utente dell'agent, caricata nel servizio come variabile d'ambiente e mai inserita nel codice, in un repository o in qualsiasi posizione raggiungibile da un browser. Genera qui un'unità di servizio completa e hardened per il tuo agent:

Completa quindi la configurazione del server. Configura SSH per accettare solo le chiavi e proteggi l'account da cui amministri il sistema, come descritto in Hardening di SSH su un VPS. Se preferisci controllare l'agent da una sessione interattiva mentre lo configuri, eseguire Claude Code su un VPS con tmux è un buon complemento. Dopo aver aperto una seconda sessione sullo stesso server, i due possono passarsi il lavoro invece di dover trasferire manualmente ogni istruzione da un riquadro all'altro. Se invece vuoi approfondire i concetti alla base di tutto questo senza vincolarli a un modello specifico, la guida complementare creare il tuo agent AI su un VPS illustra i fondamenti.

Se cerchi un assistente di coding da terminale, eseguire un agent AI di coding su un VPS tratta Aider e Goose.

FAQ

Quale modello Claude devo usare per creare un agent?

Inizia con Claude Opus 5.5 (claude-opus-5-5), che Anthropic raccomanda per la maggior parte dei carichi di lavoro, e modifica la scelta in base ai risultati. Claude Sonnet 5.5 (claude-sonnet-5-5) è più economico e veloce per la maggior parte delle attività, Claude Haiku 5.5 (claude-haiku-5-5) è indicato per i passaggi semplici e ad alto volume, mentre Claude Fable 5.1 (claude-fable-5-1) offre le prestazioni migliori per le attività più complesse. Un approccio comune consiste nell'usare un modello più economico per i passaggi ordinari e uno più potente per le decisioni difficili, perché il passaggio da un modello all'altro richiede una sola modifica di una riga.

Eseguo l'intero agent sul mio VPS o lo esegue Anthropic?

Dipende dall'approccio. Se scrivi un tuo loop usando la Claude API oppure usi Claude Agent SDK, l'agent viene eseguito interamente sul tuo VPS e soltanto le chiamate al modello vengono inviate ad Anthropic. Se usi Managed Agents, Anthropic esegue il loop e, per impostazione predefinita, ospita il sandbox in cui vengono eseguiti gli strumenti; quindi una parte minore dell'agent risiede sul tuo server. Un'opzione sandbox self-hosted, in beta all'11 ottobre 2026, sposta l'esecuzione degli strumenti sulla tua macchina, mentre il loop resta presso Anthropic. Per un agent eseguito interamente sulla tua macchina, usa una delle prime due opzioni.

Qual è la differenza tra Claude API e Claude Agent SDK?

Claude API è l'endpoint Messages di base: invii una conversazione e gli strumenti, quindi scrivi il loop dell'agent attorno a questi elementi oppure usi il tool runner dell'SDK per gestirlo. Claude Agent SDK è una libreria di livello più elevato, basata su Claude Code e distribuita per la creazione di applicazioni, che include un loop completo e strumenti integrati per file, shell e ricerca. Usa l'API quando vuoi definire tutto autonomamente. Usa Agent SDK quando vuoi un agent capace senza dover assemblare manualmente l'harness.

Come posso proteggere la mia chiave API di Claude su un server?

Conservala sul server e fuori dal codice. Memorizzala in un file leggibile soltanto dall'account con cui viene eseguito l'agent, caricala nel servizio come variabile d'ambiente e non inserirla mai in un repository né esporla a un browser. Poiché ogni richiesta a Claude viene inviata dal tuo server, la chiave non deve mai raggiungere il dispositivo dell'utente. Per questo un agent eseguito sul server è più semplice da proteggere rispetto a uno integrato in un'applicazione client.

Devo eseguire un modello in modalità self-hosted per creare un agent con Claude?

No. Con Claude, il modello è un servizio ospitato che chiami tramite API, quindi non devi eseguire nulla su una GPU. Il tuo VPS esegue il loop dell'agent, gli strumenti e la gestione dei dati, mentre il ragionamento avviene sul lato Anthropic. Questo consente a un server di dimensioni contenute di eseguire un agent capace. Se invece vuoi un modello completamente locale, devi seguire il percorso self-hosted descritto nella guida complementare sulla creazione di un tuo agent di intelligenza artificiale.