Claude Code SDK

 (docs.anthropic.com)
1 points par GN⁺ 2025-05-20 | 1 commentaires | Partager sur WhatsApp
  • Claude Agent SDK permet de contrôler depuis du code Python ou TypeScript l’exécution d’outils, la boucle d’agent et la gestion du contexte de Claude Code, afin d’automatiser la lecture de fichiers, l’exécution de commandes, la recherche web et l’édition de code
  • Il fournit comme outils de base Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, ce qui permet de gérer l’exploration d’une base de code comme les questions de confirmation à l’utilisateur sans couche d’exécution séparée
  • En combinant hooks, sous-agents, MCP, permissions et sessions, on peut mettre en place des configurations comme un journal d’audit des modifications de fichiers, un sous-agent dédié à la revue de code, une automatisation de navigateur basée sur Playwright ou un agent d’analyse en lecture seule
  • L’installation se fait via @anthropic-ai/claude-agent-sdk ou claude-agent-sdk; Python nécessite la version 3.10 ou supérieure, et le SDK TypeScript inclut en dépendance optionnelle le binaire natif Claude Code pour la plateforme
  • Contrairement à l’Anthropic Client SDK, qui impose d’implémenter soi-même la boucle d’outils, l’Agent SDK fournit une exécution d’outils intégrée et s’exécute dans le processus et l’infrastructure de l’utilisateur, et non sur l’infrastructure Anthropic comme les Managed Agents

Ce que prend en charge Claude Agent SDK

  • Claude Agent SDK rend disponibles en Python et TypeScript les outils, la boucle d’agent et la gestion du contexte qui font fonctionner Claude Code
  • Les agents peuvent lire des fichiers, exécuter des commandes, rechercher sur le web et modifier du code
  • L’exécution d’outils intégrée permet à l’agent de commencer à travailler sans que l’utilisateur ait à créer lui-même une couche séparée d’exécution d’outils
  • L’exemple de base autorise les outils Read, Edit et Bash pour trouver et corriger un bug dans auth.py

Installation et flux d’authentification

  • L’installation se fait avec les paquets propres à chaque langage
    • TypeScript : npm install @anthropic-ai/claude-agent-sdk
    • Python : pip install claude-agent-sdk
  • Le paquet Python nécessite Python 3.10 ou supérieur
    • Si l’erreur No matching distribution found for claude-agent-sdk apparaît, l’interpréteur peut être dans une version antérieure à 3.10
    • Sur macOS ou Linux, vérifiez avec python3 --version; sur Windows, avec py --version
  • Le SDK TypeScript inclut en dépendance optionnelle le binaire Claude Code natif pour la plateforme, il n’est donc pas nécessaire d’installer Claude Code séparément
  • La clé API se récupère dans la Console et se définit dans la variable d’environnement ANTHROPIC_API_KEY
  • L’authentification auprès de fournisseurs d’API tiers est également prise en charge
    • Amazon Bedrock : définir CLAUDE_CODE_USE_BEDROCK=1, puis configurer les identifiants AWS
    • Claude Platform on AWS : définir CLAUDE_CODE_USE_ANTHROPIC_AWS=1 et ANTHROPIC_AWS_WORKSPACE_ID, puis configurer les identifiants AWS
    • Google Vertex AI : définir CLAUDE_CODE_USE_VERTEX=1, puis configurer les identifiants Google Cloud
    • Microsoft Azure : définir CLAUDE_CODE_USE_FOUNDRY=1, puis configurer les identifiants Azure
  • Sans approbation préalable, Anthropic n’autorise pas les développeurs tiers à proposer la connexion claude.ai ou des rate limits dans des produits basés sur Claude Agent SDK

Outils de base et fonctionnalités d’agent

  • Le SDK permet de manipuler depuis le code les principales fonctionnalités de Claude Code
    • Outils intégrés
    • Hooks
    • Sous-agents
    • MCP
    • Permissions
    • Sessions
  • Les principaux outils intégrés remplissent les rôles suivants
    • Read : lire des fichiers dans le répertoire de travail
    • Write : créer de nouveaux fichiers
    • Edit : appliquer des modifications précises à des fichiers existants
    • Bash : exécuter des commandes de terminal, des scripts et des opérations git
    • Monitor : surveiller des scripts en arrière-plan et réagir à chaque ligne de sortie sous forme d’événement
    • Glob : trouver des fichiers avec des motifs comme **/*.ts ou src/**/*.py
    • Grep : rechercher dans le contenu des fichiers avec des expressions régulières
    • WebSearch : rechercher sur le web des informations récentes
    • WebFetch : récupérer et analyser le contenu de pages web
    • AskUserQuestion : poser à l’utilisateur une question de confirmation avec des options à choix multiples
  • L’agent d’exemple autorise Read, Glob et Grep pour trouver et résumer les commentaires TODO dans une base de code

Hooks, sous-agents et MCP

  • Les hooks exécutent le code de l’utilisateur à des points clés du cycle de vie de l’agent
    • Des fonctions de rappel permettent de valider, consigner, bloquer ou transformer le comportement de l’agent
    • Les hooks disponibles incluent notamment PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd et UserPromptSubmit
    • L’exemple détecte les opérations Edit|Write dans PostToolUse et consigne les modifications de fichiers dans audit.log
  • Les sous-agents sont des agents spécialisés qui traitent des sous-tâches ciblées
    • L’agent principal délègue une tâche, et le sous-agent renvoie le résultat
    • Un agent personnalisé se définit par une description, un prompt et les outils à utiliser
    • Les sous-agents sont appelés via l’outil Agent; pour une approbation automatique, il faut donc inclure Agent dans allowedTools
    • Les messages dans le contexte d’un sous-agent incluent le champ parent_tool_use_id, ce qui permet de suivre à quelle exécution de sous-agent ils appartiennent
  • Le Model Context Protocol (MCP) permet de se connecter à des systèmes externes comme des bases de données, des navigateurs ou des API

Gestion des permissions et des sessions

  • La configuration des permissions limite les outils que l’agent peut utiliser
    • Elle peut autoriser les opérations sûres, bloquer les opérations risquées et demander une approbation pour les actions sensibles
    • L’exemple préapprouve uniquement Read, Glob et Grep afin de configurer un agent en lecture seule qui analyse le code sans le modifier
  • L’outil AskUserQuestion et les prompts d’approbation interactifs sont utilisés ensemble dans le flux de traitement des entrées utilisateur
  • Les sessions conservent le contexte sur plusieurs échanges
    • Claude se souvient des fichiers lus, des analyses effectuées et de l’historique de conversation
    • On peut ensuite reprendre la même session ou la forker pour explorer une autre approche
    • L’exemple récupère un session_id lors de la première requête, puis poursuit le même contexte avec resume=session_id lors de la deuxième requête

Prise en charge de la configuration de Claude Code

  • Le SDK prend en charge la configuration de Claude Code basée sur le système de fichiers
  • Avec les options par défaut, il charge la configuration depuis .claude/ dans le répertoire de travail et depuis ~/.claude/
  • Pour limiter les sources de configuration à charger, utilisez l’option setting_sources en Python et settingSources en TypeScript
  • Les fonctionnalités et emplacements pris en charge sont les suivants
    • Skills : capacités spécialisées que Claude utilise automatiquement ou appelle via /name, .claude/skills/*/SKILL.md
    • Commands : commandes personnalisées au format historique, .claude/commands/*.md
    • Memory : contexte et instructions du projet, CLAUDE.md ou .claude/CLAUDE.md
    • Plugins : extensions de skills, agents, hooks et serveurs MCP, configurées de manière programmatique avec l’option plugins

Différences avec les autres outils Claude

  • Anthropic Client SDK fournit un accès direct à l’API : l’utilisateur envoie les prompts et implémente lui-même l’exécution des outils
  • Avec Agent SDK, Claude prend en charge le traitement des outils de façon autonome
    • Avec le Client SDK, l’utilisateur implémente la boucle d’outils
    • L’Agent SDK fournit à Claude une exécution d’outils intégrée
  • Les critères de choix selon l’usage sont les suivants
    • Développement interactif : CLI
    • Pipelines CI/CD : SDK
    • Applications personnalisées : SDK
    • Tâches ponctuelles : CLI
    • Automatisation en production : SDK
  • De nombreuses équipes utilisent à la fois la CLI pour le développement quotidien et le SDK en production, les workflows pouvant être transférés directement de l’un à l’autre
  • Managed Agents est une API REST hébergée dans laquelle Anthropic exécute les agents et les sandboxes
  • Agent SDK est une bibliothèque qui exécute la boucle d’agent dans le processus de l’utilisateur
    • Lieu d’exécution : Agent SDK dans le processus et l’infrastructure de l’utilisateur, Managed Agents dans l’infrastructure gérée par Anthropic
    • Interface : Agent SDK sous forme de bibliothèque Python ou TypeScript, Managed Agents sous forme d’API REST
    • Cible des tâches : Agent SDK sur les fichiers de l’infrastructure de l’utilisateur, Managed Agents dans des sandboxes gérées par session
    • État de session : Agent SDK dans des fichiers JSONL du système de fichiers, Managed Agents dans un journal d’événements hébergé par Anthropic
    • Outils personnalisés : Agent SDK avec des fonctions Python ou TypeScript dans le processus, Managed Agents avec Claude qui déclenche l’outil et l’utilisateur qui renvoie le résultat d’exécution
    • Usages adaptés : Agent SDK pour le prototypage local et les agents ayant un accès direct au système de fichiers et aux services; Managed Agents pour les agents de production sans exploitation d’infrastructure de sandbox ou de session, ainsi que pour les sessions longues et asynchrones
  • Le parcours courant consiste à créer un prototype local avec Agent SDK, puis à le migrer vers Managed Agents en production

Changelog, signalement de bugs et branding

  • Les mises à jour du SDK, corrections de bugs et nouvelles fonctionnalités sont disponibles dans le changelog de chaque dépôt
  • Les bugs et problèmes se signalent sur GitHub
  • Lorsqu’un partenaire intègre Claude Agent SDK, l’utilisation du branding Claude est facultative
    • Autorisé : « Claude Agent », « Claude », « Powered by Claude »
    • Interdit : « Claude Code », « Claude Code Agent », l’art ASCII de la marque Claude Code ou des éléments visuels imitant Claude Code
    • Le produit doit conserver son propre branding et ne doit pas donner l’impression d’être Claude Code ou un produit Anthropic
  • L’utilisation de Claude Agent SDK est soumise aux Anthropic’s Commercial Terms of Service
    • Exception faite des cas où un composant ou une dépendance spécifique indique une autre licence dans le fichier LICENSE correspondant

À lire aussi

1 commentaires

 
GN⁺ 2025-05-20
Avis sur Hacker News

  • La direction que prend Claude Code correspond exactement à ce que j’attends d’un outil de codage agentique, et j’aime aussi sa philosophie « façon outil Unix »
    Je l’utilise depuis les tout débuts de la preview publique, et on voyait déjà cette orientation. À mon avis, l’état final idéal d’un agent de codage, c’est qu’on puisse lui donner une demande de fonctionnalité, comme un ticket Jira, et qu’il produise une PR à relire et commenter. En ce sens, les outils centrés sur l’éditeur local comme Cursor ou Windsurf sont proches d’une impasse, parce qu’ils ne peuvent pas tourner dans la CI. Si l’on prépare une base de code pour l’IA avec des règles, MCP, etc., il faut viser une technologie qui puisse aller jusqu’à un usage headless. Claude Code est facile à intégrer comme partie d’une automatisation via ses outils ; c’est donc devenu mon choix par défaut quand je pense aux agents de codage, et le package npm Codex est similaire. Cela dit, comme mon travail consiste à aider des entreprises à adapter leurs bases de code à l’usage d’agents, je peux être biaisé en faveur des outils faciles à configurer

    • J’ai du mal à adhérer à cet « état final idéal ». Ce que je veux, c’est être dans une pièce entouré de plusieurs écrans où des agents IA codent, conçoivent et testent, pendant que je reste au centre pour donner la direction et appliquer mes préférences
      Je m’attends à ce que tout se fasse par conversation, et à ne pas avoir besoin de toucher le clavier dans 99 % des cas
    • Je ne pense pas. L’état final « idéal » d’un agent de codage, c’est un agent de codage libre et open source qui tourne sur mon ordinateur ou sur la machine de mon choix
      Imaginez devoir payer à chaque fois que vous lancez des commandes comme ls, ps ou kill dans le terminal : ce serait absurde. C’est pareil pour les LLM. Je ne dis pas qu’il faut interdire les LLM propriétaires, mais les outils principaux des hackers d’autrefois devraient être libres et open source
    • Anthropic a aussi annoncé aujourd’hui en bêta une fonctionnalité qui va dans une direction similaire : https://docs.anthropic.com/en/docs/claude-code/github-action...
    • J’ai déjà fait ce genre de choses avec Cursor et MCP. Au bout d’environ une journée, je me suis heurté aux limites d’utilisation et je suis retombé sur le modèle le plus lent et le plus bête
      J’ai aussi essayé avec Claude, mais j’ai vite épuisé les limites. Les PR sont directement « bonnes à passer » dans environ 25 % des cas seulement, et il est souvent plus rapide de faire correctement le travail soi-même que de chercher où l’IA s’est plantée
    • Je comprends l’idée d’un état où l’on donne une demande de fonctionnalité et où l’on obtient une PR à relire, mais cela signifie qu’il ne reste que les tickets Jira, la partie la plus destructrice pour l’âme du travail logiciel, et c’est déprimant

  • Claude Code est la manière d’utiliser les LLM pour coder que je préfère
    Mais ce dont on a vraiment besoin, selon moi, c’est d’une version open source qui permette de brancher n’importe quel modèle et de comparer les réponses de plusieurs modèles. Aider et les autres alternatives ne me semblent pas aussi agréables à utiliser que Claude Code. Du point de vue d’Anthropic, ce n’est sans doute pas souhaitable, car cela ferait disparaître son moat, mais côté consommateur, on veut simplement utiliser le meilleur modèle sans être enfermé dans un écosystème donné. C’est probablement ce que les fournisseurs de modèles LLM redoutent le plus

    • OpenAI Codex est sans doute l’alternative la plus proche. Il est open source et peut utiliser le modèle de n’importe quel fournisseur
      Pour l’instant, il n’est pas aussi bon que Claude Code, mais je pense qu’il va vite rattraper son retard. https://github.com/openai/codex/tree/main
    • Le projet OpenCode pourrait correspondre à ce que vous cherchez : https://github.com/opencode-ai/opencode
      Il est encore en développement, mais semble prometteur
    • Je me demande ce que Claude Code fait mieux qu’Aider
    • J’ai certes fait un peu trop d’autopromo récemment, mais si vous regardez mes commentaires précédents, j’ai un service écrit en Go. Il vise exactement ce besoin
    • Je suis d’accord, mais les autres modèles ne devraient-ils pas aussi être entraînés à travailler avec des serveurs MCP ? Ou bien ce n’est pas un problème ?

  • Aider prend en charge Python et les scripts shell depuis longtemps [0]
    Récemment, lors de l’ajout de la prise en charge de 130 nouveaux langages de programmation, j’ai aussi réalisé un screencast montrant du scripting Bash improvisé avec Aider [1]. Cela peut donner une idée de la puissance de cette approche.
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • J’aime vraiment Aider. La prise en charge de MCP devrait bientôt arriver, et je teste la branche de développement
      Cela permettra de faire du développement de bout en bout avec un modèle de confiance, via des PR, des tickets, etc.
    • Je me demande à quel point on peut rapprocher Aider de Claude Code. L’expérience utilisateur de Claude Code m’a plu, mais je ne l’utilise pas parce que je préfère Gemini 2.5 Pro
      Je ne tiens pas particulièrement à ce qu’il fasse les commits ; c’est surtout le ressenti de Claude Code que j’apprécie
    • Aider pourrait beaucoup s’améliorer avec un workflow GitHub Actions bien peaufiné
      Il suffirait par exemple d’ajouter un seul fichier au dépôt pour pouvoir discuter avec n’importe quel modèle via les issues

  • Points abordés plus en détail par l’équipe Claude Code : http://latent.space/p/claude-code
    On peut se contenter de parcourir la transcription, mais personnellement, j’ai trouvé marquant que les employés d’Anthropic, tout en utilisant Claude en illimité, dépensent en moyenne environ 6 dollars par jour ; qu’ils voient Claude Code headless comme un utilitaire « Linux » utilisable partout dans la CI ; qu’ils le considèrent comme une plateforme extensible par les utilisateurs ; que le sandboxing, le branching et les fonctions de planification figurent sur la roadmap ; et qu’ils voient Sonnet 3.7 comme un modèle d’agent persistant

    • Le lien indique aussi qu’en interne chez Anthropic, il y a même eu un ingénieur qui a dépensé plus de 1 000 dollars en une journée
      Je serais curieux de connaître les P50, P75 et P95 des dépenses par employé
    • Peut-être que je m’en sers mal, mais deux heures d’utilisation de Claude Code font facilement partir plus de 20 dollars
      C’était trop cher pour mes projets personnels, donc j’ai arrêté de l’utiliser
    • Ces derniers temps, j’écoute vraiment avec plaisir le podcast latent space. Je pense qu’il y a très peu de personnes ou de podcasts capables de maintenir un rapport signal/bruit aussi élevé tout en produisant autant au global
      C’est impressionnant de voir que, sur les six derniers mois ou même ces dernières années, la quantité et la valeur de leur travail public ont continué d’augmenter tout en développant plusieurs activités. J’aimerais que d’autres puissent trouver une pente de productivité similaire. Ils partagent en gros ce qui fonctionne bien, mais ce n’est pas facile à reproduire. Je pense à des gens comme simonw ou gwern
    • Je me demande à quel point ce podcast était neutre, ou si c’était simplement une promotion commerciale pour ce produit

  • Si je créais un assistant de code IA, la toute dernière chose que je ferais serait de le lier à un fournisseur de modèle de fondation spécifique
    Pour que ce produit réussisse, il faut supposer que les performances des modèles viennent juste d’atteindre un plateau, que tous les modèles de fondation convergent vers quasiment les mêmes performances et capacités, et que les intégrateurs choisiront sur la base de petits conforts comme un SDK familier

    • À part les commandes et les arguments, il n’y a pas grand-chose qui vous attache. Ce ne sont que des entrées et des sorties
      Il suffit de remplacer par autre chose ou de mettre un wrapper. Il n’y a pas grand-chose de compliqué ici
    • À l’heure actuelle, Claude Code est un facteur de différenciation logiciel dans le domaine du codage agentique
      Je travaille sur quelque chose autour des assistants de code IA, et je bidouillais déjà la manière d’intégrer Claude Code. C’était la première chose sur laquelle nous voulions construire. Il est trop tôt pour s’inquiéter du lock-in ; nous avons besoin du meilleur, donc nous construirons uniquement autour du meilleur

  • Claude Code pouvait déjà être utilisé en mode non interactif, et donc intégré à d’autres apps comme n’importe quel autre utilitaire en ligne de commande Unix
    Ce SDK semble, pour l’instant, ne prendre en charge que l’usage en ligne de commande ; dans ce cas, n’est-ce pas la même chose que ce qui existait déjà ? Je ne vois pas ce qu’il y a vraiment de nouveau. Qu’est-ce que je rate ?

    • Je ne sais pas non plus. De mon point de vue, c’est étrange que presque personne n’en parle

  • Je recommande aussi Codebuff(https://www.codebuff.com/). C’est un excellent assistant de code en CLI, similaire à Claude Code, et il peut faire économiser beaucoup de coûts en tokens
    Je n’ai aucun lien avec ce projet, je suis juste utilisateur

  • Les conditions indiquent qu’on ne peut pas l’utiliser « pour développer un produit ou service concurrent des Services, pour développer ou entraîner des algorithmes ou modèles d’intelligence artificielle ou de machine learning, ni pour revendre les Services »
    Je me demande bien ce que pourrait être un produit ou service logiciel qui ne concurrence pas l’intelligence générale. Ils vendent de l’intelligence, et si l’on interprète strictement la clause juridique, cela revient à dire qu’on ne peut l’utiliser nulle part. Est-ce tellement vague que c’en est inapplicable ? Si on ne peut pas l’utiliser pour concurrencer l’intelligence générale, comment peut-on posséder les résultats produits ? Est-ce une approche du type « personne ne se soucie des conditions juridiques » ? Si personne ne s’en soucie, pourquoi mettre une interdiction générale sur l’utilisation du service ? Faut-il vraiment accepter une responsabilité en cas de procès perdu pour obtenir ce genre de résultats ? J’ai beaucoup trop de questions

    • C’est ce qui arrive quand on laisse les avocats écrire librement
    • Vous avez remplacé « artificial » par « general », donc le sens change évidemment

  • Le lock-in sur un modèle serait un gros désavantage à l’usage. Si quelqu’un sort le nouveau meilleur modèle du moment alors que vous avez déjà investi dans cette infrastructure, vous vous retrouvez coincé
    Même s’ils l’ouvrent plus tard, le modèle en question aura probablement été spécialement entraîné pour cette CLI, donc ça pourrait ne pas bien fonctionner. Il suffit de regarder Codex CLI : on peut bien utiliser Gemini 2.5 Pro, mais par rapport aux modèles OpenAI, il s’arrête ou échoue aléatoirement beaucoup plus souvent

  • La nouvelle GitHub Action correspond exactement à la fonctionnalité que je cherchais : https://docs.anthropic.com/en/docs/claude-code/github-action...
    En revanche, il ne semble pas y avoir de moyen de l’utiliser avec le plan Max de Claude Code. À ce que je vois, elle ne prend qu’une clé API