Créer un agent IA avec Claude sur un VPS

Ce que signifie créer un agent avec Claude

Créer un agent avec Claude consiste à utiliser Claude comme cœur de raisonnement, tandis que la boucle d’exécution, les outils et les données résident sur votre propre serveur. Claude décide des actions à effectuer ; votre VPS les exécute. Vous envoyez la tâche et l’état actuel à Claude. Claude renvoie soit une réponse, soit une demande d’utilisation de l’un de vos outils. Votre code exécute l’outil et renvoie le résultat. La boucle continue jusqu’à la fin de la tâche. L’intelligence est fournie par un service que vous appelez sur Internet. Tout le reste vous appartient.

C’est l’intérêt de cette séparation. Vous bénéficiez d’un raisonnement de niveau avancé sans exploiter vous-même un modèle. Vous gardez aussi le contrôle complet de ce que l’agent peut utiliser, car les outils s’exécutent sur du matériel que vous possédez. Si vous avez déjà créé un premier programme Claude, le guide de la première application Claude sur un VPS présente les bases sur lesquelles s’appuie ce tutoriel.

Claude est le cerveau : l’API Messages

Chaque appel à Claude passe par un endpoint, l’API Messages. Vous envoyez la conversation en cours 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’appel d’un outil. Avec l’approche où vous construisez vous-même l’agent, il n’existe pas d’« API agent » distincte : l’utilisation des outils est une fonctionnalité de cet endpoint unique, et c’est à votre code d’exécuter la boucle autour de celui-ci.

Claude est sans état entre les appels : il ne mémorise donc rien de lui-même. Chaque requête contient la conversation complète. Votre code conserve l’historique et l’envoie à chaque tour, ce qui explique pourquoi chaque tour d’une longue session consomme plus de tokens que le précédent. Il s’agit moins d’une limitation que d’un choix d’architecture : puisque l’état réside sur votre serveur, vous décidez exactement ce que Claude voit, et aucune information sur la tâche n’est stockée à un endroit que vous ne contrôlez pas. En contrepartie, le prompt continue de s’allonger. La fenêtre de contexte de Claude le gère généralement sans difficulté, mais un modèle local exécuté dans la même boucle ne le pourra pas. C’est pourquoi il faut augmenter num_ctx dans Ollama avant qu’il ne tronque les prompts longs.

L’utilisation d’outils constitue 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 doit agir, répond avec une demande d’utilisation d’outil qui indique un outil et renseigne ses paramètres. Votre code exécute cet outil, puis envoie le résultat à Claude dans la requête suivante. Claude lit le résultat et demande soit un autre outil, soit rédige sa réponse finale. Lorsqu’il ne demande plus d’outil, la tâche est terminée.

Vous pouvez écrire cette boucle manuellement en quelques lignes, et beaucoup le font, car elle est facile à comprendre et à contrôler. Les SDK officiels fournissent également un exécuteur d’outils qui pilote la boucle à votre place : vous fournissez les fonctions des outils, et le SDK gère les échanges successifs avec Claude, l’exécution de vos outils et le renvoi des résultats jusqu’à ce que Claude ait terminé. Dans les deux cas, la structure est identique. L’exécuteur vous évite simplement d’écrire vous-même la boucle. Si la boucle vous semble encore abstraite, écrivez-en une version minimale avant d’utiliser un exécuteur. C’est l’étape sur laquelle repose tout le reste de ce parcours progressif pour apprendre les agents IA à partir de zéro.

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

Il existe trois façons de construire un agent Claude. Elles diffèrent par la quantité de composants que vous devez exécuter.

La première consiste à écrire votre propre code, qui appelle l’API Claude avec vos propres outils. Vous écrivez la boucle d’exécution ou utilisez le tool runner du SDK, puis vous hébergez l’ensemble sur votre VPS. C’est le choix le plus courant, car vous contrôlez entièrement les outils, les données et la sécurité. L’ensemble s’exécute comme un programme ordinaire sur votre serveur. La majeure partie de ce guide part de ce principe.

La deuxième est le Claude Agent SDK. Il s’agit de Claude Code, l’agent de développement, fourni sous forme de bibliothèque sur laquelle vous pouvez construire. Il fournit une boucle d’agent complète et des outils intégrés pour lire et écrire des fichiers, exécuter des commandes shell et effectuer des recherches. Vous n’avez donc pas à assembler ces composants vous-même. Il s’exécute également sur votre propre serveur. Il convient donc bien à un VPS si vous voulez un agent capable de manipuler des fichiers et d’exécuter des commandes shell sans développer vous-même le harness. Un agent qui lit des fichiers et exécute des commandes shell doit être confiné avant de fonctionner sans surveillance. La page exécuter Claude Code en toute sécurité sur un serveur présente le système de permissions, le sandbox et les options d’isolation.

La troisième est Managed Agents. Anthropic exécute alors la boucle et héberge un sandbox dans lequel les outils de l’agent s’exécutent. C’est l’option qui demande le moins d’exploitation : vous avez beaucoup moins de composants à gérer, mais l’espace de travail de l’agent se trouve sur l’infrastructure d’Anthropic plutôt que sur votre VPS. Choisissez cette option si vous voulez réduire au minimum le travail d’exploitation et si vous n’avez pas besoin que les outils s’exécutent sur votre propre machine. Pour les deux autres options, votre serveur héberge l’agent. C’est le sujet du reste de ce guide.

Connecter des outils avec MCP

Quelle que soit l’approche choisie, vous devrez connecter l’agent à des systèmes réels. Le Model Context Protocol est la méthode la plus propre pour y parvenir. MCP est un standard ouvert qui permet d’exposer des outils et des données à un agent. Au lieu de coder manuellement une intégration pour chaque service, vous indiquez à Claude un serveur MCP qui présente déjà ces fonctionnalités sous forme d’outils. Vous pouvez exécuter les serveurs MCP comme de petits services sur le même VPS, en accordant à chacun uniquement les accès nécessaires. Cette configuration est décrite dans exécuter des serveurs MCP sur un VPS.

Choisir un modèle

Claude existe en plusieurs modèles. Le choix dépend des capacités, de la vitesse et du coût. À la date de rédaction, les principaux choix sont Claude Opus 4.8 (claude-opus-4-8), le modèle par défaut capable de gérer les raisonnements complexes et les longues exécutions d’agents ; Claude Sonnet 5 (claude-sonnet-5), une option équilibrée, moins chère et plus rapide, qui reste proche d’Opus pour de nombreuses tâches ; et Claude Haiku 4.5 (claude-haiku-4-5), le modèle le plus rapide et le moins cher, adapté aux étapes simples exécutées en grand nombre. Claude Fable 5 (claude-fable-5) se situe au-dessus d’eux. C’est le modèle le plus capable, destiné aux tâches les plus exigeantes. Utilisez l’identifiant exact du modèle dans votre code, sans lui ajouter de date.

Une approche pratique consiste à les combiner. Confiez les appels d’outils courants à un modèle moins cher et les décisions complexes à un modèle plus puissant. Comme le modèle est simplement une chaîne de caractères dans votre requête, le remplacer ne demande qu’une modification d’une ligne. Commencez donc avec un modèle par défaut capable, puis utilisez un modèle moins puissant lorsque la vitesse ou le coût comptent davantage que le dernier gain de qualité.

Exécuter l’agent comme un service durci sur votre VPS

Un agent n’est utile que s’il reste en fonctionnement, et il n’est sûr que s’il est confiné. Sur un VPS, ces deux conditions sont réunies en exécutant l’agent comme un service système durci, plutôt que comme un programme lancé manuellement dans un terminal. En tant que service, il démarre au boot, redémarre s’il se termine de manière inattendue et écrit ses journaux dans le journal systemd. Une fois durci, il s’exécute avec un utilisateur non privilégié et dispose uniquement des accès nécessaires. Ainsi, un bug ou une instruction malveillante reste limité. Une unité de service peut uniquement restreindre ce que le processus est autorisé à manipuler. Le reste doit être géré par le harness de l’agent lui-même. C’est le rôle des plugins DeepSeek Harness à installer sur une autre stack : plafonds de dépenses, règles d’autorisation par outil et détection des prompt injections.

La règle la plus importante est de conserver votre clé API Claude côté serveur. Cette clé paie et autorise chaque appel. Elle doit donc se trouver dans un fichier lisible uniquement par l’utilisateur de l’agent, être chargée dans le service comme variable d’environnement et ne jamais être placée dans du code, un dépôt ou un emplacement accessible depuis un navigateur. Générez ici une unité de service complète et durcie pour votre agent :

Terminez ensuite la configuration du serveur lui-même. Configurez SSH pour n’accepter que les clés et sécurisez le compte depuis lequel vous administrez le serveur, comme indiqué dans Durcir SSH sur un VPS. Si vous préférez piloter l’agent depuis une session interactive pendant sa mise en place, exécuter Claude Code sur un VPS avec tmux constitue un bon complément. Une fois une deuxième session ouverte sur le même serveur, les deux peuvent se transmettre du travail au lieu de vous obliger à recopier chaque instruction d’un panneau à l’autre. Si vous souhaitez comprendre les concepts sous-jacents sans les associer à un modèle particulier, le guide complémentaire créer votre propre agent IA sur un VPS présente les bases.

Si vous cherchez un assistant de codage dans un terminal, exécuter un agent IA de codage sur un VPS présente Aider et Goose.

FAQ

Quel modèle Claude utiliser pour créer un agent ?

Commencez par Claude Opus 4.8 (claude-opus-4-8), le choix par défaut le plus capable, puis ajustez selon vos besoins. Claude Sonnet 5 (claude-sonnet-5) est moins cher et plus rapide pour la plupart des tâches, Claude Haiku 4.5 (claude-haiku-4-5) convient mieux aux étapes simples et exécutées à grande échelle, et Claude Fable 5 (claude-fable-5) est le plus capable pour les tâches les plus complexes. Une approche courante consiste à utiliser un modèle moins cher pour les étapes courantes et un modèle plus puissant pour les décisions difficiles, car le changement se fait sur une seule ligne.

L’agent s’exécute-t-il entièrement sur mon VPS ou chez Anthropic ?

Cela dépend de l’approche choisie. Si vous écrivez votre propre boucle avec l’API Claude ou si vous utilisez le Claude Agent SDK, l’agent s’exécute entièrement sur votre VPS et seuls les appels au modèle sont envoyés à Anthropic. Avec Managed Agents, Anthropic exécute la boucle et héberge le sandbox dans lequel les outils s’exécutent. Une plus petite partie de l’agent réside donc sur votre serveur. Pour un agent qui s’exécute 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 endpoint Messages brut : vous envoyez une conversation et des outils, puis vous écrivez la boucle de l’agent autour de ces éléments, ou vous utilisez le tool runner du SDK pour la piloter. Le Claude Agent SDK est une bibliothèque de plus haut niveau, basée sur Claude Code pour créer vos propres applications. Elle fournit une boucle complète ainsi que des outils intégrés pour les fichiers, le shell et la recherche. Utilisez l’API si vous voulez tout définir vous-même. Utilisez l’Agent SDK si vous voulez un agent capable sans assembler vous-même le harness.

Comment protéger ma clé API Claude sur un serveur ?

Conservez-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 comme variable d’environnement et ne la commitez jamais dans un dépôt ni ne l’exposez à un navigateur. Comme chaque requête vers Claude part de votre serveur, la clé n’a jamais besoin d’atteindre l’appareil de l’utilisateur. Un agent exécuté sur un serveur est ainsi plus facile à sécuriser qu’un agent intégré à une application cliente.

Dois-je héberger moi-même un modèle pour créer un agent avec Claude ?

Non. Avec Claude, le modèle est un service hébergé que vous appelez via l’API. Vous n’avez donc rien à exécuter sur un GPU. Votre VPS exécute la boucle de l’agent, les outils et les traitements de données, tandis que le raisonnement s’effectue chez Anthropic. C’est ce qui permet à un serveur modeste d’exécuter un agent capable. Si vous préférez utiliser un modèle entièrement local, choisissez la voie de l’auto-hébergement présentée dans le guide complémentaire consacré à la création de votre propre agent IA.