Créer un agent IA avec Claude sur un VPS

Ce que signifie construire un agent avec Claude

Construire un agent avec Claude, c'est utiliser Claude comme cœur de raisonnement pendant que la boucle, les outils et les données vivent sur votre propre serveur. Claude décide quoi faire ; votre VPS l'exécute. Vous envoyez à Claude la tâche et l'état courant, Claude répond soit par une réponse, soit par une demande d'utiliser l'un de vos outils, votre code exécute l'outil et renvoie le résultat, et la boucle continue jusqu'à ce que le travail soit terminé. L'intelligence est un service que vous appelez sur internet. Tout ce qui l'entoure vous appartient.

Cette séparation fait tout l'intérêt. Vous obtenez un raisonnement de premier plan sans exploiter de modèle, et vous gardez le contrôle total de ce que l'agent peut toucher, car les outils s'exécutent sur du matériel qui vous appartient. Si vous avez déjà écrit un premier programme Claude, le guide de la première application Claude sur un VPS couvre les bases sur lesquelles celui-ci s'appuie.

Claude est le cerveau : l'API Messages

Chaque appel à Claude passe par un seul point d'accès, l'API Messages. Vous envoyez la conversation jusqu'ici et la liste des outils que l'agent peut utiliser ; Claude renvoie son message suivant. Ce message est soit une réponse finale, soit une demande d'appeler un outil. Pour l'approche « faites-le vous-même », il n'y a pas d'« API d'agent » distincte : l'utilisation d'outils est une fonctionnalité de ce point d'accès unique, et la boucle autour de lui, c'est à vous de la faire tourner.

Claude est sans état entre les appels, ce qui veut dire qu'il ne se souvient de rien tout seul. Chaque requête transporte l'ensemble de la conversation. Votre code conserve l'historique et l'envoie à chaque tour. Ce n'est pas tant une limite qu'un choix de conception : parce que l'état vit sur votre serveur, vous décidez exactement ce que Claude voit, et rien de la tâche n'est stocké quelque part que vous ne contrôlez pas.

L'utilisation d'outils est la boucle de l'agent

La boucle de l'agent avec Claude est simple à décrire. Vous envoyez une requête qui inclut vos outils. Claude lit la tâche et, s'il a besoin d'agir, répond par une demande d'utilisation d'outil qui nomme un outil et remplit ses entrées. Votre code exécute cet outil, puis renvoie le résultat à Claude dans la requête suivante. Claude lit le résultat et demande soit un autre outil, soit écrit sa réponse finale. Quand il cesse de demander des outils, la tâche est terminée.

Vous pouvez écrire cette boucle à la main en quelques lignes, et beaucoup le font, car elle est facile à voir et facile à contrôler. Les SDK officiels fournissent aussi un exécuteur d'outils qui pilote la boucle pour vous : vous fournissez les fonctions des outils, et le SDK gère les allers-retours consistant à appeler Claude, exécuter vos outils et réinjecter les résultats jusqu'à ce que Claude ait fini. Dans les deux cas, la forme est la même. L'exécuteur vous évite simplement d'écrire la boucle vous-même.

Trois façons de construire, et lesquelles conviennent à un VPS

Il y a trois façons de construire un agent Claude, et elles diffèrent par la part de la machinerie que vous faites tourner.

La première, c'est votre propre code qui appelle l'API Claude avec vos propres outils. Vous écrivez la boucle, ou utilisez l'exécuteur d'outils du SDK, et vous hébergez le tout sur votre VPS. C'est le choix courant, car il vous donne un contrôle complet sur les outils, les données et la sécurité, et il s'exécute comme un programme ordinaire sur votre serveur. La majeure partie de ce guide suppose cette approche.

La deuxième, c'est le Claude Agent SDK. Il s'agit de Claude Code, l'agent de codage, empaqueté comme une bibliothèque sur laquelle vous pouvez construire. Il livre une boucle d'agent complète et des outils intégrés pour lire et écrire des fichiers, exécuter des commandes shell et faire des recherches, si bien que vous n'assemblez pas tout cela de zéro. Il s'exécute lui aussi sur votre propre serveur, ce qui en fait un bon choix pour un VPS quand vous voulez un agent capable de manipuler fichiers et shell sans construire vous-même l'ossature. Un agent qui lit des fichiers et exécute des commandes shell a besoin d'être confiné avant de fonctionner sans surveillance, et exécuter Claude Code en toute sécurité sur un serveur couvre le système de permissions, le bac à sable et les options d'isolation.

La troisième, ce sont les Managed Agents, où Anthropic fait tourner la boucle et héberge un bac à sable dans lequel les outils de l'agent s'exécutent. C'est l'option sans les mains : il y a bien moins de choses à exploiter, mais l'espace de travail de l'agent vit sur l'infrastructure d'Anthropic plutôt que sur votre VPS. Choisissez-la quand vous voulez le moins de travail d'exploitation possible et que vous n'avez pas besoin que les outils s'exécutent sur votre propre machine. Pour les deux autres, votre serveur est le foyer de l'agent, ce qui est le sujet du reste de ce guide.

Connecter des outils avec le MCP

Quelle que soit l'approche choisie, vous voudrez connecter l'agent à de vrais systèmes, et le Model Context Protocol (MCP) est la manière soignée de le faire. Le MCP est une norme ouverte pour exposer des outils et des données à un agent. Plutôt que de coder à la main une intégration pour chaque service, vous pointez Claude vers un serveur MCP qui présente déjà ces capacités sous forme d'outils. Vous pouvez faire tourner des serveurs MCP comme de petits services sur le même VPS, chacun avec uniquement l'accès dont il a besoin, ce que je détaille dans exécuter des serveurs MCP sur un VPS.

Choisir un modèle

Claude existe en plusieurs modèles, et en choisir un est un compromis entre capacité, vitesse et coût. À l'heure où j'écris ces lignes, les choix courants sont Claude Opus 4.8 (claude-opus-4-8), la valeur par défaut capable pour le raisonnement difficile et les longues exécutions d'agent ; Claude Sonnet 5 (claude-sonnet-5), une option équilibrée, moins chère et plus rapide tout en restant proche d'Opus sur de nombreuses tâches ; et Claude Haiku 4.5 (claude-haiku-4-5), le plus rapide et le moins cher, pour les étapes simples à fort volume. Au-dessus se trouve Claude Fable 5 (claude-fable-5), le modèle le plus capable, pour les travaux les plus exigeants. Utilisez l'identifiant de modèle exact dans votre code, sans y ajouter de date.

Un schéma pratique consiste à les mélanger. Laissez un modèle moins cher gérer les appels d'outils de routine et un plus puissant gérer les décisions difficiles. Comme le modèle n'est qu'une chaîne de caractères dans votre requête, changer est une modification d'une seule ligne ; commencez donc par une valeur par défaut capable et réglez vers le bas là où la vitesse ou le coût comptent plus que le dernier gramme de qualité.

L'exécuter comme un service durci sur votre VPS

Un agent n'est utile que s'il continue de tourner, et il n'est sûr que s'il est confiné. Sur un VPS, ces deux qualités viennent du fait de faire tourner l'agent comme un service système durci plutôt que comme un programme lancé à la main dans un terminal. En tant que service, il démarre au démarrage, redémarre s'il plante, et écrit ses journaux dans le journal. Durci, il s'exécute sous un utilisateur non privilégié avec seulement l'accès dont il a besoin, si bien qu'un bug ou une mauvaise instruction a un plafond.

La règle la plus importante est de garder votre clé d'API Claude côté serveur. La clé paie et autorise chaque appel, elle a donc sa place dans un fichier lisible uniquement par l'utilisateur de l'agent, chargé dans le service sous forme de variable d'environnement, et jamais placée dans le code, dans un dépôt, ou où qu'un navigateur puisse l'atteindre. Générez ici une unité de service complète et durcie pour votre agent :

Ensuite, finissez le serveur lui-même. Mettez SSH en clés uniquement et verrouillez le compte depuis lequel vous administrez, comme dans le durcissement SSH sur un VPS. Si vous préférez piloter l'agent depuis une session interactive pendant que vous le construisez, exécuter Claude Code sur un VPS avec tmux est un bon compagnon. Et si vous voulez les concepts derrière tout cela, sans les lier à un seul modèle, le guide frère sur la construction de votre propre agent IA sur un VPS pose les fondations.

Si vous voulez un assistant de codage en terminal, exécuter un agent de codage IA sur un VPS couvre Aider et Goose.

FAQ

Quel modèle Claude utiliser pour construire un agent ?

Commencez par Claude Opus 4.8 (claude-opus-4-8), la valeur par défaut capable, et ajustez à partir de là. Claude Sonnet 5 (claude-sonnet-5) est moins cher et plus rapide pour la plupart des travaux, Claude Haiku 4.5 (claude-haiku-4-5) convient le mieux aux étapes simples à fort volume, et Claude Fable 5 (claude-fable-5) est le plus capable pour les tâches les plus difficiles. Un schéma courant consiste à utiliser un modèle moins cher pour les étapes de routine et un plus puissant pour les décisions difficiles, puisque changer est une modification d'une seule ligne.

Est-ce que je fais tourner tout l'agent sur mon VPS, ou est-ce Anthropic ?

Cela dépend de l'approche. Si vous écrivez votre propre boucle sur l'API Claude, ou utilisez le Claude Agent SDK, l'agent s'exécute entièrement sur votre VPS et seuls les appels au modèle partent vers Anthropic. Si vous utilisez les Managed Agents, Anthropic fait tourner la boucle et héberge le bac à sable où les outils s'exécutent, donc une moins grande partie vit sur votre serveur. Pour un agent qui tourne sur votre propre machine, utilisez l'une des deux premières approches.

Quelle est la différence entre l'API Claude et le Claude Agent SDK ?

L'API Claude est le point d'accès Messages brut : vous envoyez une conversation et des outils, et vous écrivez la boucle de l'agent autour, ou utilisez l'exécuteur d'outils du SDK pour la piloter. Le Claude Agent SDK est une bibliothèque de plus haut niveau, Claude Code empaqueté pour construire dessus, qui livre une boucle complète et des outils intégrés de fichiers, de shell et de recherche. Utilisez l'API quand vous voulez tout définir vous-même, et l'Agent SDK quand vous voulez un agent capable sans assembler l'ossature.

Comment garder ma clé d'API Claude en sécurité sur un serveur ?

Gardez-la côté serveur et hors de votre code. Stockez-la dans un fichier lisible uniquement par le compte sous lequel l'agent s'exécute, chargez-la dans le service sous forme de variable d'environnement, et ne la validez jamais dans un dépôt ni ne l'exposez à un navigateur. Comme chaque requête à Claude part de votre serveur, la clé n'a jamais besoin d'atteindre l'appareil d'un utilisateur, ce qui rend un agent exécuté sur serveur plus facile à sécuriser qu'un agent intégré à une application cliente.

Ai-je besoin d'auto-héberger un modèle pour construire un agent avec Claude ?

Non. Avec Claude, le modèle est un service hébergé que vous appelez via l'API, il n'y a donc rien à faire tourner sur un GPU. Votre VPS fait tourner la boucle de l'agent, les outils et les données, et le raisonnement se produit du côté d'Anthropic. C'est ce qui permet à un serveur modeste de faire tourner un agent capable. Si vous voulez plutôt un modèle entièrement local, c'est l'approche auto-hébergée couverte dans le guide compagnon sur la construction de votre propre agent IA.