Creare un agent AI con Claude su VPS

Cosa significa costruire un agent con Claude

Costruire un agent con Claude significa utilizzare Claude come core di ragionamento, mentre il loop, i tool e i dati risiedono sul proprio server. Claude decide cosa fare; il proprio VPS esegue l'azione. Si invia a Claude il task e lo stato attuale; Claude risponde con una risposta o con una richiesta di utilizzare uno dei propri tool; il proprio codice esegue il tool e invia il risultato; il loop continua finché il lavoro non è completato. L'intelligenza è un servizio che si chiama tramite internet. Tutto il resto è sotto il proprio controllo.

Questa separazione è il punto di forza. Si ottiene un ragionamento di livello frontier senza dover gestire un modello, e si mantiene il controllo totale su ciò che l'agent può toccare, poiché i tool vengono eseguiti sull'hardware di proprietà. Se è già stato creato un primo programma con Claude, la guida al primo Claude app su un VPS copre le basi su cui si sviluppa questa guida.

Claude è il cervello: la Messages API

Ogni chiamata a Claude avviene tramite un unico endpoint, la Messages API. Si invia la conversazione attuale e l'elenco dei tool che l'agent può utilizzare; Claude restituisce il suo prossimo messaggio. Tale messaggio è una risposta finale o una richiesta di chiamare un tool. Per l'approccio "build-it-yourself" non esiste una "agent API" separata: l'uso dei tool è una funzione di questo singolo endpoint, e il loop che lo circonda deve essere gestito dall'utente.

Claude è stateless tra le chiamate, il che significa che non ricorda nulla autonomamente. Ogni richiesta contiene l'intera conversazione. Il proprio codice mantiene la cronologia e la invia a ogni turno, motivo per cui ogni turno in una sessione lunga costa più token dell'ultimo. Questa non è una limitazione ma una scelta di design: poiché lo stato risiede sul proprio server, si decide esattamente cosa vede Claude, e nulla del task viene memorizzato in un luogo non controllato dall'utente.

L'uso dei tool è l'agent loop

L'agent loop con Claude è semplice da descrivere. Si invia una richiesta che include i propri tool. Claude legge il task e, se deve agire, risponde con una richiesta di tool-use che specifica il tool e i relativi input. Il proprio codice esegue il tool e invia il risultato a Claude nella richiesta successiva. Claude legge il risultato e chiede un altro tool oppure scrive la risposta finale. Quando smette di richiedere tool, il task è completato.

È possibile scrivere questo loop manualmente in poche righe, come fanno molti, poiché è facile da visualizzare e controllare. Gli SDK ufficiali forniscono anche un tool runner che gestisce il loop automaticamente: si forniscono le funzioni dei tool e l'SDK gestisce l'interazione tra la chiamata a Claude, l'esecuzione dei tool e l'invio dei risultati fino al completamento. In entrambi i casi la struttura è la stessa. Il runner serve solo a evitare di dover scrivere il loop manualmente.

Tre modi per costruire, e quali sono adatti a un VPS

Esistono tre modi per costruire un agent Claude, che differiscono per la quantità di componenti gestiti dall'utente.

Il primo consiste nell'utilizzare il proprio codice per chiamare la Claude API con i propri tool. Si scrive il loop, o si usa il tool runner dell'SDK, e si ospita l'intero sistema sul proprio VPS. Questa è la scelta comune, poiché garantisce il controllo completo su tool, dati e sicurezza, ed è eseguibile come un normale programma sul server. La maggior parte di questa guida assume questo percorso.

Il secondo è il Claude Agent SDK. Si tratta di Claude Code, l'agent per la programmazione, fornito come libreria su cui è possibile costruire. Include un loop completo e tool integrati per leggere e scrivere file, eseguire comandi shell e effettuare ricerche, evitando di doverli assemblare da zero. Viene eseguito sul proprio server, il che lo rende ideale per un VPS quando si desidera un agent capace di gestire file e shell senza dover costruire l'infrastruttura manualmente. Un agent che legge file ed esegue comandi shell necessita di isolamento prima di operare in autonomia; eseguire Claude Code in sicurezza su un server descrive il sistema di permessi, il sandbox e le opzioni di isolamento.

Il terzo sono i Managed Agents, in cui Anthropic gestisce il loop e ospita un sandbox in cui i tool dell'agent vengono eseguiti. Questa è l'opzione senza gestione operativa: l'utente deve gestire molto meno componenti, ma lo workspace dell'agent risiede sull'infrastruttura di Anthropic invece che sul proprio VPS. Si sceglie questa opzione quando si desidera il minimo carico operativo e non è necessario che i tool girino sulla propria macchina. Per le prime due opzioni, il server dell'utente è la sede dell'agent, che è l'oggetto di questa guida.

Connettere i tool con MCP

Indipendentemente dal percorso scelto, sarà necessario connettere l'agent a sistemi reali; il Model Context Protocol è il metodo più ordinato per farlo. MCP è uno standard aperto per esporre tool e dati a un agent. Invece di scrivere manualmente un'integrazione per ogni servizio, si punta Claude verso un server MCP che presenta già tali capacità come tool. È possibile eseguire server MCP come piccoli servizi sullo stesso VPS, ciascuno con i soli permessi necessari, come descritto in eseguire server MCP su un VPS.

Scelta del modello

Claude è disponibile in diversi modelli; la scelta dipende dal compromesso tra capacità, velocità e costo. Al momento della scrittura, le scelte principali sono Claude Opus 4.8 (claude-opus-4-8), il default per ragionamenti complessi e sessioni agent lunghe; Claude Sonnet 5 (claude-sonnet-5), un'opzione bilanciata, più economica e veloce, pur rimanendo simile a Opus in molti task; e Claude Haiku 4.5 (claude-haiku-4-5), il più veloce ed economico, per passaggi semplici ad alto volume. Sopra di essi si trova Claude Fable 5 (claude-fable-5), il modello più capace per i lavori più impegnativi. Utilizzare l'identificativo esatto del modello nel codice, senza aggiungere date.

Un pattern pratico consiste nel mixare i modelli. Si può lasciare che un modello economico gestisca le chiamate ai tool di routine e uno più potente gestisca le decisioni complesse. Poiché il modello è solo una stringa nella richiesta, il cambio è una modifica di una riga; si può quindi iniziare con un default capace e scendere di livello dove la velocità o il costo sono prioritari rispetto alla qualità assoluta.

Eseguire l'agent come servizio protetto sul proprio VPS

Un agent è utile solo se rimane in esecuzione, ed è sicuro solo se è isolato. Su un VPS, ciò si ottiene eseguendo l'agent come un servizio di sistema protetto invece che come un programma avviato manualmente in una terminale. Come servizio, l'agent si avvia al boot, si riavvia in caso di crash e registra i log nel journal. Se protetto, viene eseguito come utente non privilegiato con solo i permessi necessari, limitando l'impatto di eventuali bug o istruzioni errate.

La regola più importante è mantenere la Claude API key sul lato server. La chiave paga e autorizza ogni chiamata, quindi deve essere salvata in un file leggibile solo dall'utente dell'agent, caricata nel servizio come variabile d'ambiente e mai inserita nel codice, in un repository o in luoghi accessibili da un browser. Generare qui un'unità di servizio completa e protetta per il proprio agent:

Successivamente, configurare il server. Configurare SSH solo tramite chiavi e limitare l'account da cui si amministra, come in SSH hardening su un VPS. Se si preferisce gestire l'agent da una sessione interattiva durante lo sviluppo, eseguire Claude Code su un VPS con tmux è un ottimo supporto. Se si desiderano i concetti alla base di tutto questo, senza legarli a un modello specifico, la guida correlata su costruire il proprio AI agent su un VPS espone le fondamenta.

Se si desidera un assistente alla programmazione via terminale, eseguire un coding AI agent su un VPS copre Aider e Goose.

FAQ

Quale modello Claude dovrei usare per costruire un agent?

Iniziare con Claude Opus 4.8 (claude-opus-4-8), il default capace, e regolare di conseguenza. Claude Sonnet 5 (claude-sonnet-5) è più economico e veloce per la maggior parte dei lavori, Claude Haiku 4.5 (claude-haiku-4-5) è ideale per passaggi semplici ad alto volume, e Claude Fable 5 (claude-fable-5) è il più capace per i task più difficili. Un pattern comune è usare un modello economico per i passaggi di routine e uno più potente per le decisioni complesse, dato che il cambio richiede solo una riga di codice.

L'agent viene eseguito interamente sul mio VPS o da Anthropic?

Dipende dall'approccio. Se si scrive il proprio loop tramite la Claude API o si usa il Claude Agent SDK, l'agent viene eseguito interamente sul proprio VPS e solo le chiamate al modello vengono inviate ad Anthropic. Se si utilizzano i Managed Agents, Anthropic gestisce il loop e ospita il sandbox dove vengono eseguiti i tool, quindi meno componenti risiedono sul proprio server. Per un agent che gira sulla propria macchina, utilizzare uno dei primi due metodi.

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

La Claude API è l'endpoint Messages grezzo: si invia una conversazione e i tool, e si scrive il loop dell'agent attorno ad essi, oppure si usa il tool runner dell'SDK per gestirlo. Il Claude Agent SDK è una libreria di livello superiore, ovvero Claude Code impacchettato per lo sviluppo, che include un loop completo e tool integrati per file, shell e ricerca. Utilizzare l'API quando si vuole definire tutto autonomamente, e l'Agent SDK quando si desidera un agent capace senza dover costruire l'infrastruttura.

Come posso mantenere sicura la mia Claude API key su un server?

Deve rimanere sul lato server e fuori dal codice. Salvala in un file leggibile solo dall'account che esegue l'agent, caricala nel servizio come variabile d'ambiente e non inviarla mai a un repository né esporla a un browser. Poiché ogni richiesta a Claude parte dal proprio server, la chiave non deve mai raggiungere il dispositivo dell'utente, rendendo un agent gestito su server più facile da proteggere rispetto a uno integrato in un'app client.

Devo ospitare un modello localmente per costruire un agent con Claude?

No. Con Claude il modello è un servizio ospitato che si chiama tramite API, quindi non è necessario eseguire nulla su una GPU. Il proprio VPS esegue il loop dell'agent, i tool e i dati, mentre il ragionamento avviene lato Anthropic. Questo permette a un server modesto di eseguire un agent capace. Se si desidera invece un modello completamente locale, si deve seguire il percorso di self-hosting descritto nella guida correlata sulla costruzione del proprio AI agent.