Passer au contenu principal
Utilisez le SDK Agent pour créer un agent IA qui lit votre code, trouve les bugs et les corrige, tout sans intervention manuelle. Ce que vous allez faire :
  1. Configurer un projet avec le SDK Agent
  2. Créer un fichier avec du code contenant des bugs
  3. Exécuter un agent qui trouve et corrige les bugs automatiquement

Prérequis

Configuration

1

Créer un dossier de projet

Créez un nouveau répertoire pour ce démarrage rapide :
Pour vos propres projets, vous pouvez exécuter le SDK à partir de n’importe quel dossier ; il aura accès aux fichiers de ce répertoire et de ses sous-répertoires par défaut.
2

Installer le SDK

Installez le package du SDK Agent pour votre langage :
Définir "type": "module" dans package.json permet à votre script d’agent d’utiliser await au niveau supérieur, et tsx exécute les fichiers TypeScript directement.
Le SDK TypeScript regroupe un binaire Claude Code natif pour votre plateforme en tant que dépendance optionnelle, vous n’avez donc pas besoin d’installer Claude Code séparément.
3

Définir votre clé API

Obtenez une clé API à partir de la Console Claude, puis définissez-la comme variable d’environnement dans le shell où vous exécuterez votre agent :
Le SDK lit la clé à partir de l’environnement du processus qui exécute votre agent ; il ne charge pas les fichiers .env automatiquement. Si vous conservez la clé dans un fichier .env, chargez-la vous-même, par exemple avec le package dotenv, avant d’appeler le SDK.Le SDK prend également en charge l’authentification via des fournisseurs d’API tiers :
  • Amazon Bedrock : définissez la variable d’environnement CLAUDE_CODE_USE_BEDROCK=1 et configurez les identifiants AWS
  • Claude Platform on AWS : définissez CLAUDE_CODE_USE_ANTHROPIC_AWS=1 et ANTHROPIC_AWS_WORKSPACE_ID, puis configurez les identifiants AWS
  • Google Cloud’s Agent Platform : définissez la variable d’environnement CLAUDE_CODE_USE_VERTEX=1 et configurez les identifiants Google Cloud
  • Microsoft Azure : définissez la variable d’environnement CLAUDE_CODE_USE_FOUNDRY=1 et configurez les identifiants Azure
Consultez les guides de configuration pour Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, ou Microsoft Foundry pour plus de détails.
Sauf approbation préalable, Anthropic n’autorise pas les développeurs tiers à proposer la connexion claude.ai ou les limites de débit pour leurs produits, y compris les agents construits sur le SDK Agent Claude. Veuillez utiliser les méthodes d’authentification par clé API décrites dans ce document à la place.

Créer un fichier avec des bugs

Ce démarrage rapide vous guide dans la création d’un agent capable de trouver et corriger les bugs dans le code. D’abord, vous avez besoin d’un fichier avec quelques bugs intentionnels pour que l’agent les corrige. Créez utils.py dans le répertoire my-agent et collez le code suivant :
Ce code a deux bugs :
  1. calculate_average([]) plante avec une division par zéro
  2. get_user_name(None) plante avec une TypeError

Créer un agent qui trouve et corrige les bugs

Créez agent.py si vous utilisez le SDK Python, ou agent.ts pour TypeScript. Utilisez agent.mts à la place si votre projet existant utilise CommonJS :
Ce code a trois parties principales :
  1. query : le point d’entrée principal qui crée la boucle agentique. Il retourne un itérateur asynchrone, vous utilisez donc async for pour diffuser les messages au fur et à mesure que Claude travaille. Consultez l’API complète dans la référence du SDK Python ou TypeScript.
  2. prompt : ce que vous voulez que Claude fasse. Claude détermine les outils à utiliser en fonction de la tâche.
  3. options : configuration de l’agent. Cet exemple utilise allowedTools pour pré-approuver Read, Edit et Glob, et permissionMode: "acceptEdits" pour approuver automatiquement les modifications de fichiers. Les autres options incluent systemPrompt, mcpServers et bien d’autres. Consultez toutes les options pour Python ou TypeScript.
La boucle async for continue de s’exécuter tandis que Claude réfléchit, appelle des outils, observe les résultats et décide de la prochaine étape. Chaque itération produit un message : le raisonnement de Claude, un appel d’outil, un résultat d’outil ou le résultat final. Le SDK gère l’orchestration (exécution des outils, gestion du contexte, tentatives) afin que vous consommiez simplement le flux. La boucle se termine lorsque Claude termine la tâche ou rencontre une erreur. La gestion des messages à l’intérieur de la boucle filtre la sortie lisible par l’homme. Sans filtrage, vous verriez des objets de message bruts incluant l’initialisation du système et l’état interne, ce qui est utile pour le débogage mais bruyant autrement.
Cet exemple utilise la diffusion en continu pour afficher la progression en temps réel. Si vous n’avez pas besoin de sortie en direct (par exemple, pour les tâches en arrière-plan ou les pipelines CI), vous pouvez collecter tous les messages à la fois. Consultez Mode diffusion en continu vs. mode à tour unique pour plus de détails.

Exécuter votre agent

Votre agent est prêt. Exécutez-le avec la commande suivante :
Si vous avez nommé votre script agent.mts, exécutez npx tsx agent.mts à la place.
Au fur et à mesure qu’il travaille, l’agent imprime son raisonnement et chaque outil qu’il appelle, se terminant par Done: success. Après l’exécution, vérifiez utils.py. Vous verrez du code défensif gérant les listes vides et les utilisateurs nuls. Votre agent a autonomement :
  1. Lu utils.py pour comprendre le code
  2. Analysé la logique et identifié les cas limites qui causeraient un plantage
  3. Modifié le fichier pour ajouter une gestion d’erreur appropriée
C’est ce qui rend le SDK Agent différent : Claude exécute les outils directement au lieu de vous demander de les implémenter.
Si vous voyez ’ API key not found ’, assurez-vous d’avoir défini la variable d’environnement ANTHROPIC_API_KEY dans le shell où vous exécutez votre agent. Le SDK ne charge pas les fichiers .env automatiquement. Consultez le guide de dépannage complet pour plus d’aide.

Essayer d’autres invites

Maintenant que votre agent est configuré, essayez quelques invites différentes :
  • "Add docstrings to all functions in utils.py"
  • "Add type hints to all functions in utils.py"
  • "Create a README.md documenting the functions in utils.py"

Personnaliser votre agent

Vous pouvez modifier le comportement de votre agent en changeant les options. Voici quelques exemples : Ajouter la capacité de recherche web :
Donner à Claude une invite système personnalisée :
Exécuter des commandes dans le terminal :
Avec Bash activé, essayez : "Write unit tests for utils.py, run them, and fix any failures"

Concepts clés

Les outils contrôlent ce que votre agent peut faire : Les modes de permission contrôlent le niveau de surveillance humaine que vous souhaitez : L’exemple ci-dessus utilise le mode acceptEdits, qui approuve automatiquement les opérations de fichiers afin que l’agent puisse s’exécuter sans invites interactives. Si vous souhaitez inviter les utilisateurs à approuver, utilisez le mode default et fournissez un rappel canUseTool qui collecte l’entrée de l’utilisateur. Pour plus de contrôle, consultez Permissions.

Étapes suivantes

Maintenant que vous avez créé votre premier agent, apprenez à étendre ses capacités et à l’adapter à votre cas d’usage :
  • Permissions : contrôlez ce que votre agent peut faire et quand il a besoin d’approbation
  • Hooks : exécutez du code personnalisé avant ou après les appels d’outils
  • Sessions : créez des agents multi-tours qui maintiennent le contexte
  • Serveurs MCP : connectez-vous à des bases de données, des navigateurs, des API et d’autres systèmes externes
  • Hébergement : déployez des agents sur Docker, le cloud et CI/CD
  • Agents d’exemple : consultez des exemples complets : assistant e-mail, agent de recherche et bien d’autres