Claude Agent SDK : Comment créer des agents (2026)

TL;DR

• Le Claude Agent SDK est la bibliothèque d’Anthropic pour créer des agents IA dans votre propre code — le même moteur d’agent qui alimente Claude Code, exposé sous forme de claude-agent-sdk pour Python (3.10+) et de @anthropic-ai/claude-agent-sdk pour TypeScript.
• Il a été renommé depuis `claude-code-sdk` fin 2025 ; si un tutoriel mentionne ClaudeCodeOptions, il est obsolète — la classe s’appelle désormais ClaudeAgentOptions.
• Vous obtenez gratuitement la boucle d’agent complète : outils de fichiers, Bash, recherche web, outils personnalisés via @tool, serveurs MCP (c’est ainsi que vous connectez Jira ou Shopify), sous-agents, hooks et permissions. Vous ne payez que les tokens de l’API Claude.
• Il communique avec l’API Anthropic Messages, vous pouvez donc le faire pointer vers une passerelle avec ANTHROPIC_BASE_URL — nous l’avons testé avec l’endpoint /v1/messages de Velokey et il fonctionne avec une seule clé et une facturation au crédit.

Tout le monde crée des agents en ce moment, et la plupart des guides s’arrêtent au quickstart en dix lignes. Celui-ci couvre la suite : comment l’installer sans tomber dans le piège Node courant, comment connecter de vrais outils comme Jira et Shopify, ce que son exécution coûte réellement, et comment le router via une passerelle. Entrons dans le vif du sujet.

Qu’est-ce que le Claude Agent SDK ?

Le Claude Agent SDK est une bibliothèque qui donne à votre propre application la même boucle d’agent autonome que celle qui s’exécute dans Claude Code — lecture et écriture de fichiers, exécution de commandes, recherche sur le web et appel d’outils, sans que vous ayez à écrire vous-même la boucle d’appel d’outils. Anthropic le fournit pour Python et TypeScript, et selon la documentation officielle, c’est la méthode prise en charge pour créer des agents de production sur Claude.

Le contexte important que la plupart des gens manquent : il s’appelait auparavant le Claude Code SDK. Anthropic l’a renommé Claude Agent SDK fin 2025 pour indiquer qu’il sert à créer *n’importe quel* agent, pas seulement des outils de codage. Le package, les imports et une classe centrale ont tous changé — claude-code-sdk est devenu claude-agent-sdk, et ClaudeCodeOptions est devenu ClaudeAgentOptions. Beaucoup d’articles de blog et de réponses Stack Overflow font encore référence aux anciens noms ; donc si votre import échoue, c’est généralement pour cette raison.

Sous le capot, le SDK encapsule le Claude Code CLI en tant que sous-processus. Votre code Python ou TypeScript communique avec le SDK ; le SDK pilote le CLI intégré ; le CLI communique avec Claude. Cette architecture est importante pour deux raisons sur lesquelles nous reviendrons : le CLI est un binaire Node (vous devez donc avoir Node installé même pour le SDK Python), et le CLI effectue une mise en cache agressive des prompts sur son prompt système (ce qui modifie vos calculs de coûts).

Comment installer et utiliser le Claude Agent SDK ?

Installez le Claude Agent SDK depuis PyPI (ou npm), définissez votre clé API, puis appelez query() — un agent fonctionnel tient en une dizaine de lignes. Python nécessite la version 3.10 ou plus récente :

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

Voici l’agent minimal à exécution unique. query() renvoie un itérateur asynchrone de messages :

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List the Python files in this repo and summarize each."):
        print(message)

anyio.run(main)

Pour tout ce qui est interactif ou multi-tours, utilisez ClaudeSDKClient et configurez-le avec ClaudeAgentOptions :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

Deux pièges d’installation qui déroutent souvent les gens, et qui ne figurent pas dans le guide de démarrage rapide en dix lignes :

Que pouvez-vous construire avec le Claude Agent SDK ?

Vous pouvez construire n’importe quel agent qui a besoin d’un accès aux fichiers, de l’exécution de commandes ou de l’utilisation d’outils — d’un réviseur de code à un agent de triage du support client, en passant par un opérateur de pipeline de données. Le SDK vous fournit cinq blocs de construction, et toute la conception vise à contrôler ce que l’agent est autorisé à faire :

Les outils personnalisés sont la partie la plus élégante. Décorez une fonction et l’agent peut l’appeler directement — pas de processus séparé, pas de saut réseau :

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

Les hooks et les permissions sont ce qui transforme une démo en quelque chose que vous laisseriez fonctionner sans surveillance. Un hook PreToolUse peut bloquer une commande Bash qui correspond à un motif dangereux ; permission_mode détermine si l’agent s’interrompt pour demander une approbation ou accepte automatiquement les modifications. En production, la plupart des équipes commencent avec une liste allowed_tools stricte et l’élargissent à mesure qu’elles font confiance à l’agent — l’inverse du démarrage rapide grand ouvert.

Le sixième bloc, et celui vers lequel les gens se tournent dès qu’un agent unique devient lent, ce sont les sous-agents. Le SDK peut lancer un nouveau sous-agent avec son propre contexte pour gérer une sous-tâche délimitée, puis renvoyer le résultat — Claude Code utilise cela pour se déployer en éventail sur plusieurs fichiers. C’est la réponse intégrée à « peut-il travailler sur plusieurs choses en parallèle » et « comment éviter que le contexte principal ne se remplisse » : déléguez le travail bruyant (lire dix fichiers, exécuter une matrice de tests) aux sous-agents afin que l’agent principal reste concentré. Le fork de session est l’astuce connexe pour créer des branches dans une conversation en cours.

Comment intégrer Jira ou Shopify avec le Claude Agent SDK ?

Vous intégrez Jira, Shopify, ou tout système externe en ajoutant son serveur MCP à mcp_servers dans ClaudeAgentOptions — le SDK ne contient pas de code spécifique à Jira, il communique via le protocole ouvert Model Context Protocol, et Atlassian comme Shopify fournissent des serveurs MCP. C’est la réponse aux questions d’intégration les plus fréquentes (« comment connecter Jira/Shopify avec Claude Agent SDK ») : il n’y a pas de connecteur spécial, vous enregistrez un serveur MCP et autorisez ses outils.

Le modèle est le même pour les deux. Faites pointer le SDK vers le serveur MCP (une commande locale ou une URL distante), puis autorisez les outils qu’il expose :

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Find open bugs assigned to me and summarize them.")
    async for msg in client.receive_response():
        print(msg)

Remplacez le bloc serveur par @shopify/mcp-server (avec votre jeton Shopify) et le même agent peut lire des commandes ou mettre à jour des produits. Deux points sont essentiels : les noms des outils suivent la convention mcp__<server>__<tool>, donc vos entrées allowed_tools doivent correspondre exactement, et chaque serveur MCP a besoin de son propre identifiant dans env. Si l’agent indique qu’un outil n’est pas disponible, il s’agit presque toujours d’une incohérence de nom ou d’un jeton manquant, pas d’un bug du SDK.

Si le fournisseur héberge un serveur MCP distant au lieu d’une commande locale, enregistrez-le par URL plutôt que par command/args — {"jira": {"url": "https://mcp.atlassian.com/v1/sse"}} — et le SDK se connecte via le réseau. Les serveurs locaux (stdio) sont plus simples pour le développement et gardent le jeton sur votre machine ; les serveurs distants (URL) vous évitent d’installer quoi que ce soit. Dans les deux cas, les règles concernant allowed_tools et les identifiants propres à chaque serveur sont les mêmes.

Comment exécuter le Claude Agent SDK via une passerelle ?

Définissez ANTHROPIC_BASE_URL sur la racine de votre passerelle, et le SDK y enverra chaque requête au lieu de api.anthropic.com — sans changement de code. Le SDK respecte les variables d’environnement standard d’Anthropic, donc tout backend qui expose l’API Messages d’Anthropic (/v1/messages) fonctionne : un proxy d’entreprise, un pont régional ou une passerelle unifiée.

Nous avons testé cela avec [Velokey](https://api.velokey.ai), qui expose un endpoint /v1/messages compatible avec Anthropic. Une requête en direct envoyée à celui-ci a renvoyé une réponse Messages standard (stop_reason: end_turn, utilisation au format Anthropic), ce qui correspond exactement à ce que le SDK attend :

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-your-velokey-key"
# then run your agent as usual — set the model to one Velokey serves:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # or claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

Pourquoi faire passer un agent par une passerelle ? Une seule clé au lieu d’un compte Anthropic distinct, d’un niveau séparé et d’une configuration de conservation de 30 jours ; une facturation basée sur des crédits que vous pouvez plafonner ; et la même clé permet d’accéder à [Claude Opus 4.8](/model/claude-opus-4-8), [Claude Sonnet 5](/model/claude-sonnet-5) et à d’autres modèles que vous pourriez utiliser ailleurs. Si votre proxy veut un jeton bearer plutôt que l’en-tête x-api-key, définissez ANTHROPIC_AUTH_TOKEN plutôt que ANTHROPIC_API_KEY. C’est la même logique prête à l’emploi que lorsque l’on pointe un outil compatible OpenAI vers une passerelle — consultez notre guide Qwen CLI pour l’équivalent au format OpenAI.

Combien coûte le Claude Agent SDK ?

Le SDK lui-même est gratuit et open-source — vous payez les tokens de l’API Claude que l’agent consomme, et les agents en consomment beaucoup. À chaque tour, la conversation qui s’allonge est renvoyée, chaque résultat d’outil revient dans le contexte, et une simple tâche "corrige ce bug" peut nécessiter plus de dix tours. C’est là que le coût surprend : le code fait dix lignes, mais la facture en tokens augmente avec l’ampleur de l’exploration menée par l’agent.

Trois leviers permettent de le maîtriser, et le SDK intègre pour vous le plus important :

Cette dernière ligne est réelle, pas théorique : dans notre requête de test, la réponse indiquait des dizaines de milliers de cache_read_input_tokens, ce qui signifie que le grand prompt système a été servi depuis le cache à environ un dixième du prix d’entrée, plutôt que d’être refacturé à chaque tour. C’est la principale raison pour laquelle les coûts des agents ne sont pas aussi brutaux que le nombre de tours le laisse penser. Pour le détail complet des calculs de tokens par modèle, consultez notre guide de tarification de l’API Claude ; si vous voulez un appel unique fonctionnel à un modèle Claude avant de connecter un agent, comment appeler Claude avec une clé API couvre les bases.

Questions fréquentes

Qu’est-ce que le Claude Agent SDK ?

C’est la bibliothèque officielle d’Anthropic pour créer des agents IA en Python ou TypeScript, en utilisant la même boucle d’agent autonome qui alimente Claude Code. Elle gère pour vous la boucle d’appels d’outils, les opérations sur les fichiers, l’exécution de commandes et les intégrations MCP, afin que vous écriviez l’objectif et les outils, et non l’orchestration. Vous ne payez que les tokens de l’API Claude.

Le Claude Agent SDK est-il identique au Claude Code SDK ?

Oui — c’est la version renommée. Anthropic a renommé claude-code-sdk en claude-agent-sdk fin 2025, et ClaudeCodeOptions est devenu ClaudeAgentOptions. Les fonctionnalités ont été conservées ; seuls les noms du package et des classes ont changé. Si un tutoriel importe les anciens noms, il est antérieur au renommage et les imports échoueront avec le package actuel.

Comment installer le Claude Agent SDK ?

Exécutez pip install claude-agent-sdk (Python 3.10+) ou npm install @anthropic-ai/claude-agent-sdk pour TypeScript, puis définissez ANTHROPIC_API_KEY. Comme le SDK pilote le CLI Claude Code inclus en tant que sous-processus, Node.js doit également être installé, même pour le package Python — l’absence de Node est la cause d’échec d’installation la plus courante.

Comment connecter Jira ou Shopify à un agent Claude Agent SDK ?

Ajoutez le serveur MCP du fournisseur à mcp_servers dans ClaudeAgentOptions et autorisez ses outils. Atlassian (Jira) et Shopify publient tous deux des serveurs MCP, il n’y a donc pas de connecteur personnalisé à écrire — vous enregistrez le serveur avec son token d’API et listez ses outils (nommés mcp__<server>__<tool>) dans allowed_tools.

Le Claude Agent SDK fonctionne-t-il avec une passerelle ou un proxy ?

Oui. Il respecte la variable d’environnement ANTHROPIC_BASE_URL, ce qui lui permet d’acheminer les requêtes vers n’importe quel backend qui expose l’Anthropic Messages API (/v1/messages) sans modification du code. Nous avons vérifié une requête en direct avec le point de terminaison compatible Anthropic de Velokey. Utilisez ANTHROPIC_API_KEY pour les proxys x-api-key ou ANTHROPIC_AUTH_TOKEN pour ceux à token bearer.

Quels modèles le Claude Agent SDK utilise-t-il ?

Il utilise les modèles Claude via le point de terminaison vers lequel vous le dirigez — par défaut le plus récent d’Anthropic, et vous pouvez en définir un spécifique via l’option model (par exemple claude-sonnet-5 ou claude-opus-4-8). Via une passerelle, vous pouvez sélectionner n’importe quel modèle Claude servi par cette passerelle, ce qui est pratique pour utiliser un modèle moins coûteux lors d’exécutions d’agents routinières.

Le Claude Agent SDK est-il gratuit ?

Le SDK est gratuit et open-source, mais l’exécution d’un agent coûte des tokens de l’API Claude, et les boucles d’agents à plusieurs tours les consomment rapidement. Maîtrisez les dépenses en choisissant un modèle moins coûteux pour les tâches routinières, en définissant max_turns et en limitant l’accès aux outils — et appuyez-vous sur la mise en cache intégrée des prompts, qui sert le prompt système répété à environ un dixième du prix d’entrée.