Introduction au Claude Code Agent SDK — Construisez des agents autonomes rapidement

Qu’est-ce que l’Agent SDK ?

Le Claude Code Agent SDK est un framework permettant de construire des agents autonomes alimentés par les modèles Claude. Contrairement aux simples appels API, un agent reçoit un objectif, sélectionne ses outils de manière autonome, évalue les résultats et exécute une boucle de raisonnement multi-étapes pour parvenir à une solution.

Les chatbots traditionnels fonctionnent sur un cycle requête-réponse unique. Avec l’Agent SDK, vous pouvez accomplir des workflows complexes — lire des fichiers, identifier des problèmes, appliquer des corrections, exécuter des tests et rapporter les résultats — le tout à partir d’une seule instruction.

Configuration

Initialisez votre projet et installez le SDK.

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-code --save

Pour le développement en TypeScript, ajoutez également les définitions de types.

npm install typescript @types/node --save-dev
npx tsc --init

Configurez la variable d’environnement ANTHROPIC_API_KEY et vous êtes prêt.

export ANTHROPIC_API_KEY="sk-ant-..."

Un agent minimal

Voici un agent simple capable d’interagir avec le système de fichiers.

import { Claude } from "@anthropic-ai/claude-code";

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
});

async function main() {
  const result = await agent.run(
    "Liste tous les commentaires TODO dans le répertoire src et trie-les par priorité"
  );
  console.log(result.text);
}

main();

Le paramètre maxTurns limite le nombre maximum d’étapes que l’agent peut effectuer. Définissez-le toujours comme garde-fou contre les boucles infinies.

Définition d’outils personnalisés

La véritable puissance de l’Agent SDK réside dans les outils personnalisés. En donnant à l’agent l’accès à des API externes ou des bases de données, vous débloquez une automatisation bien plus pratique.

import { Claude, Tool } from "@anthropic-ai/claude-code";

const fetchIssueTool: Tool = {
  name: "fetch_github_issue",
  description: "Récupérer une issue GitHub",
  parameters: {
    type: "object",
    properties: {
      owner: { type: "string", description: "Propriétaire du dépôt" },
      repo: { type: "string", description: "Nom du dépôt" },
      number: { type: "number", description: "Numéro de l'issue" },
    },
    required: ["owner", "repo", "number"],
  },
  async execute({ owner, repo, number }) {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues/${number}`,
      { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
    );
    return await res.json();
  },
};

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool],
  maxTurns: 15,
});

Avec cette définition, l’agent appelle fetch_github_issue quand nécessaire et décide de son action suivante en fonction des informations récupérées.

Fonctionnement de l’exécution multi-étapes

En interne, l’Agent SDK exécute la boucle suivante :

1. Planification — Décomposer l’instruction de l’utilisateur en étapes nécessaires
2. Sélection d’outil — Choisir l’outil optimal parmi ceux disponibles
3. Exécution — Lancer l’outil et capturer les résultats
4. Évaluation — Vérifier si l’objectif a été atteint
5. Répéter ou terminer — Revenir à l’étape 1 si inachevé, ou générer la réponse finale

Cette boucle élimine le besoin de coder en dur chaque procédure à l’avance, permettant un traitement flexible qui s’adapte à la situation.

Exemple pratique : Agent de revue automatique de PRs

Construisons un cas d’usage concret — un agent de revue automatique de Pull Requests.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool, readFileTool, postCommentTool],
  maxTurns: 20,
  systemPrompt: `Vous êtes un expert en revue de code.
Lisez le diff de la PR et examinez-le selon :
- Les bugs potentiels
- Les risques de sécurité
- Les problèmes de performance
- Les suggestions d'amélioration`,
});

const result = await agent.run(
  "Examinez la PR #42 et laissez des commentaires s'il y a des problèmes"
);

En spécifiant le rôle de l’agent et les critères d’évaluation dans systemPrompt, vous obtenez des revues cohérentes et fiables.

Gestion des erreurs et tentatives

Une gestion robuste des erreurs est essentielle en environnement de production.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  onError: (error, context) => {
    console.error(`Erreur à l'étape ${context.turn} :`, error.message);
    if (context.turn >= 3) {
      return "abort"; // Abandonner après 3 échecs
    }
    return "retry"; // Réessayer sinon
  },
});

Résumé et prochaines étapes

Avec l’Agent SDK, vous pouvez automatiser des tâches complexes en plusieurs étapes au lieu de vous reposer sur des réponses IA ponctuelles. Commencez par de petites tâches comme l’organisation de fichiers ou l’analyse de logs, puis ajoutez progressivement des outils pour étendre les capacités de votre agent.

Pour les bases de Claude Code, consultez le Guide de démarrage. Pour le développement avec des APIs, voyez le Guide de développement d’APIs. Pour l’intégration CLI, référez-vous à Développement d’outils CLI.

Pour plus de détails, visitez la documentation officielle d’Anthropic et le dépôt GitHub de Claude Code.