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 quali sono adatti a un VPS

Esistono tre modi per creare un agente Claude. La differenza riguarda la quantità di componenti che devi eseguire.

Il primo consiste nello scrivere codice che chiama Claude API con strumenti personalizzati. Puoi scrivere tu il ciclo di esecuzione oppure usare il tool runner dell'SDK, quindi ospitare tutto sul tuo VPS. È la scelta più comune, perché offre il pieno controllo sugli strumenti, sui dati e sulla sicurezza e viene eseguita 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 lo sviluppo software, distribuito come libreria su cui puoi costruire. Include un ciclo completo dell'agente e strumenti integrati per leggere e scrivere file, eseguire comandi shell ed effettuare ricerche, quindi non devi assemblare questi componenti da zero. Viene eseguito inoltre sul tuo server, quindi è particolarmente adatto a un VPS quando vuoi un agente capace di operare su file e shell senza doverne sviluppare tu l'infrastruttura di esecuzione. Un agente che legge file ed esegue comandi shell deve essere confinato prima di poter funzionare senza supervisione; eseguire Claude Code in sicurezza su un server illustra il sistema di autorizzazioni, la sandbox e le opzioni di isolamento.

Il terzo è Managed Agents, in cui Anthropic esegue il ciclo dell'agente e ospita una sandbox nella quale vengono eseguiti gli strumenti dell'agente. È l'opzione che richiede meno gestione: devi occuparti di molti meno componenti, ma l'area di lavoro dell'agente risiede sull'infrastruttura di Anthropic e non sul tuo VPS. Sceglila quando vuoi ridurre al minimo il lavoro operativo e non hai bisogno che gli strumenti vengano eseguiti sulla tua macchina. Negli altri due casi, il server ospita l'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 costi. Al momento, le opzioni principali sono Claude Opus 4.8 (claude-opus-4-8), il modello predefinito più capace per il ragionamento complesso e le esecuzioni agentiche prolungate; Claude Sonnet 5 (claude-sonnet-5), un'opzione equilibrata, più economica e veloce, che per molte attività resta vicina a Opus; e Claude Haiku 4.5 (claude-haiku-4-5), il modello più veloce ed economico, adatto alle operazioni semplici e ad alto volume. Al di sopra di questi modelli si trova Claude Fable 5 (claude-fable-5), il modello più capace, destinato alle attività più impegnative. 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é il modello è soltanto una stringa nella richiesta, cambiarlo richiede una sola modifica di riga. Inizia quindi con un modello predefinito capace e passa a un modello più economico nei casi in cui velocità o costi siano più importanti dell'ultimo livello di qualità.

Eseguilo come servizio protetto sul tuo VPS

Un agente è utile solo se rimane in esecuzione ed è sicuro solo se viene isolato. Su un VPS, entrambe le condizioni si ottengono eseguendo l’agente come servizio di sistema protetto, invece di avviarlo manualmente in un terminale. Come servizio, viene avviato al boot, viene riavviato in caso di arresto anomalo e scrive i log nel journal. In modalità protetta, 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 solo ciò che il processo è autorizzato a utilizzare. Il resto deve essere gestito all’interno dell’harness dell’agente. È questo il compito dei plugin DeepSeek Harness da installare su un altro stack: limiti di spesa, regole di autorizzazione per ogni strumento e scansione contro il prompt injection.

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

Completa quindi la configurazione del server. Configura SSH per accettare soltanto chiavi e limita l’account da cui amministri il server, come descritto in Protezione di SSH su un VPS. Se preferisci gestire l’agente da una sessione interattiva durante la configurazione, eseguire Claude Code su un VPS con tmux è un buon complemento. Dopo aver aperto una seconda sessione sulla stessa macchina, i due agenti possono passarsi il lavoro invece di costringerti a trasferire manualmente ogni istruzione da un pannello all’altro. Se vuoi comprendere i concetti alla base di tutto questo senza associarli a un modello specifico, la guida complementare su creare il proprio agente AI su un VPS illustra i fondamenti.

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

FAQ

Quale modello Claude devo usare per creare un agent?

Inizia con Claude Opus 4.8 (claude-opus-4-8), il modello predefinito più capace, e adatta la scelta in base ai risultati. Claude Sonnet 5 (claude-sonnet-5) è più economico e veloce per la maggior parte delle attività, Claude Haiku 4.5 (claude-haiku-4-5) è indicato per i passaggi semplici e ad alto volume, mentre Claude Fable 5 (claude-fable-5) è il più capace per le attività più complesse. Un approccio comune consiste nell'usare un modello più economico per i passaggi di routine e uno più potente per le decisioni difficili, perché il modello si cambia con una sola riga.

Eseguo l'intero agent sul mio VPS o se ne occupa Anthropic?

Dipende dall'approccio. Se scrivi un tuo loop usando Claude API o usi Claude Agent SDK, l'agent viene eseguito interamente sul tuo VPS e solo le chiamate al modello vengono inviate ad Anthropic. Se usi Managed Agents, Anthropic esegue il loop e ospita la sandbox in cui vengono eseguiti gli strumenti, quindi una parte minore dell'agent risiede sul tuo server. Per un agent eseguito 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 basso livello: invii una conversazione e gli strumenti, quindi scrivi il loop dell'agent oppure usi il tool runner dell'SDK per gestirlo. Claude Agent SDK è una libreria di livello superiore, basata su Claude Code e progettata per lo sviluppo, che include un loop completo e strumenti integrati per file, shell e ricerca. Usa API quando vuoi definire autonomamente ogni componente e Agent SDK quando vuoi un agent capace senza dover assemblare il relativo harness.

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

Mantienila sul server e fuori dal codice. Salvala in un file leggibile solo 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 parte 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 incorporato in un'applicazione client.

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

No. Con Claude, il modello è un servizio ospitato che viene chiamato tramite API, quindi non c'è nulla da eseguire su una GPU. Il tuo VPS esegue il loop dell'agent, gli strumenti e la gestione dei dati, mentre l'elaborazione avviene sul lato Anthropic. Questo permette a un server con risorse contenute di eseguire un agent capace. Se invece vuoi un modello completamente locale, devi seguire l'approccio self-hosted descritto nella guida complementare sulla creazione di un tuo agent AI.