Tutoriel Claude Agent SDK : exemples en Python et TypeScript

Le Claude Agent SDK vous permet d’exécuter la même boucle d’agent que celle qui alimente Claude Code, depuis l’intérieur de votre propre programme Python ou TypeScript. Vous envoyez une seule consigne, et Claude lit des fichiers, exécute des commandes, modifie du code et appelle vos propres fonctions jusqu’à ce que la tâche soit terminée, en vous renvoyant chaque étape au fur et à mesure. Ce tutoriel construit le SDK par couches : une première requête dans chaque langage, des outils personnalisés, des subagents, des hooks, des limites de dépense et des sessions reprenables. Chaque extrait suit la documentation actuelle : vous pouvez le coller, définir une variable d’environnement et le lancer.

Ce que fait l’Agent SDK

Un agent est un programme qui décide lui-même de sa prochaine étape. Il lit une demande, choisit un outil, examine le résultat et continue jusqu’à ce que la tâche soit accomplie. L’Agent SDK vous fournit cette boucle toute prête : les mêmes outils intégrés, le même système de permissions, la même gestion du contexte et les mêmes hooks que ceux qui fonctionnent dans Claude Code, exposés sous forme de bibliothèque pour Python et TypeScript.

La différence concrète avec un simple appel à l’API tient à qui écrit la boucle. Avec le Client SDK, vous envoyez un message, vérifiez si Claude a demandé un outil, l’exécutez, renvoyez le résultat et recommencez. Avec l’Agent SDK, vous appelez query() une seule fois et vous parcourez les messages diffusés pendant que Claude travaille.

Chaque tour de cette boucle suit le même rythme. Claude reçoit la consigne et les définitions des outils, puis décide de répondre ou d’appeler un outil. Le SDK exécute l’outil et renvoie le résultat, et le cycle se répète jusqu’à ce que Claude n’ait plus rien à faire ou qu’une limite l’arrête. Chaque étape arrive dans votre code sous forme de message, ce qui explique pourquoi les exemples ci-dessous ressemblent à un traitement de flux plutôt qu’à un simple aller-retour. Cela signifie aussi que vous pouvez afficher la progression à un utilisateur, journaliser chaque appel d’outil ou arrêter l’agent plus tôt.

SDK, Client SDK ou CLI

Quatre options semblent proches. Ce tableau les classe selon la personne qui fait tourner l’agent.

💡 Astuce : Pour piloter la même boucle depuis un autre langage, lancez la CLI comme sous-processus avec l’option -p et --output-format json.

Ce qu’il vous faut d’abord

Trois éléments doivent être en place avant la première ligne de code :

• Python 3.10+ ou Node.js 18+
• Un compte Anthropic avec une clé d’API issue de la Claude Console
• Un dossier de code sur lequel l’agent va travailler, car par défaut il peut lire les fichiers de son répertoire de travail et de ses sous-répertoires

Les deux paquets intègrent un binaire natif de Claude Code, donc une installation normale ne nécessite rien d’autre. Deux situations posent problème : pip qui se replie sur la distribution source (Windows ARM64 est le cas typique) et une installation npm qui ignore les dépendances optionnelles. Dans les deux cas, installez Claude Code en natif et le SDK le trouvera.

Installer et s’authentifier

Installer le paquet

Pour Python, créez un environnement virtuel et installez le paquet :

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Copier le prompt

Sous Windows PowerShell, la ligne d’activation est .venv\Scripts\Activate.ps1. Pour TypeScript, initialisez un projet et ajoutez le paquet ainsi que tsx :

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

Copier le prompt

Définir "type": "module" permet d’utiliser await au niveau supérieur de votre script, et tsx exécute les fichiers TypeScript sans étape de compilation.

Configurer vos identifiants

Le SDK lit votre identifiant dans une variable d’environnement du shell qui lance l’agent :

export ANTHROPIC_API_KEY=your-api-key

Copier le prompt

$env:ANTHROPIC_API_KEY = "your-api-key"

Copier le prompt

Le SDK ne charge pas seul les fichiers .env. Si vous conservez votre identifiant dans un tel fichier, chargez-le d’abord avec python-dotenv ou le paquet dotenv. Les fournisseurs cloud fonctionnent aussi : définissez CLAUDE_CODE_USE_BEDROCK=1 pour Amazon Bedrock, CLAUDE_CODE_USE_VERTEX=1 pour Google Cloud ou CLAUDE_CODE_USE_FOUNDRY=1 pour Microsoft Foundry, puis configurez les identifiants de ce fournisseur.

💡 Note sur la politique d’utilisation : Sauf approbation préalable d’Anthropic, les produits tiers construits sur le SDK ne peuvent pas proposer la connexion à claude.ai ni ses limites de débit. Utilisez des identifiants d’API pour tout ce que vous livrez.

Votre premier agent dans deux langages

Créez un fichier nommé utils.py contenant deux bogues volontaires. Une liste vide fait planter la moyenne, et un utilisateur absent fait planter la recherche de nom :

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

Copier le prompt

L’agent ci-dessous est en lecture seule. Il peut examiner le fichier, mais il n’a pas la permission de modifier quoi que ce soit.

La version Python

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    AssistantMessage,
    ResultMessage,
    TextBlock,
)


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You review Python code and report crash risks in plain language.",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
    )

    async for message in query(
        prompt="Look at utils.py and list every input that would crash it.",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Finished: {message.subtype}, cost: ${message.total_cost_usd}")


asyncio.run(main())

Copier le prompt

Voici le rôle de chaque partie :

• query() renvoie un itérateur asynchrone, donc vous bouclez avec async for pendant que Claude réfléchit, appelle des outils et lit les résultats
• allowed_tools pré-approuve Read, Glob et Grep, trois outils qui peuvent inspecter des fichiers sans jamais les modifier
• Les blocs AssistantMessage transportent le texte de Claude et ses appels d’outils, donc filtrer sur TextBlock vous donne une sortie lisible
• ResultMessage arrive en dernier, avec subtype, total_cost_usd, num_turns et session_id

La version TypeScript

Enregistrez ceci sous agent.ts et lancez-le avec npx tsx agent.ts :

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Look at utils.py and list every input that would crash it.",
  options: {
    systemPrompt: "You review Python code and report crash risks in plain language.",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8
  }
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  } else if (message.type === "result") {
    console.log(`Finished: ${message.subtype}, cost: $${message.total_cost_usd}`);
  }
}

Copier le prompt

Lancez l’un ou l’autre script et vous devriez voir Claude lire utils.py, décrire les deux plantages (la division par zéro sur une liste vide et le TypeError sur un utilisateur absent) et terminer par une ligne du type Finished: success. Si vous voyez une erreur d’authentification du type Not logged in, la variable d’environnement est absente du shell qui a lancé le script, ce qui est l’erreur la plus courante au premier lancement.

La logique est identique dans les deux langages, mais la casse des noms d’options change. Gardez ce tableau à portée de main, car il explique la plupart des moments « pourquoi ça ne marche pas » lorsque vous portez du code d’un SDK à l’autre.

Les listes d’outils permettent de régler le niveau d’autonomie, à la hausse ou à la baisse :

💡 Deux comportements à anticiper : Un query() en un seul appel lève une exception après avoir renvoyé un résultat d’erreur, par exemple lorsque la limite de tours est atteinte. Enveloppez donc la boucle dans try/except ou try/catch lorsque le script doit continuer à tourner. Par ailleurs, par défaut le SDK lit le dossier .claude/ de votre projet et ~/.claude/, comme le fait la CLI. Les paramètres, compétences et hooks définis à cet endroit s’appliquent donc aussi à votre agent.

Créer des outils personnalisés

Les outils intégrés gèrent les fichiers et le shell. Votre propre logique, comme une recherche dans une base de données ou un appel à une API interne, relève d’un outil personnalisé : une fonction encapsulée dans un serveur MCP en processus qui s’exécute à l’intérieur de votre application, et non dans un processus séparé.

Un outil comporte quatre éléments : un nom, une description que Claude lit pour décider quand l’appeler, un schéma d’entrée et un handler asynchrone qui renvoie un tableau content. Rédigez la description comme si vous briefiez un nouveau collègue.

Vous enregistrez le serveur via mcp_servers (mcpServers en TypeScript). Le nom que vous donnez au serveur dans ce dictionnaire fait partie du nom complet de l’outil, selon le modèle mcp__{server}__{tool}. Placez ce nom complet dans vos outils autorisés et l’appel s’exécute sans demande de permission.

Un outil en Python

import asyncio
from typing import Any
from claude_agent_sdk import (
    tool,
    create_sdk_mcp_server,
    query,
    ClaudeAgentOptions,
    ResultMessage,
)

ORDERS = {"A100": "shipped", "A101": "packing"}


@tool("get_order_status", "Look up the status of an order by its id", {"order_id": str})
async def get_order_status(args: dict[str, Any]) -> dict[str, Any]:
    status = ORDERS.get(args["order_id"])
    if status is None:
        return {
            "content": [{"type": "text", "text": f"No order {args['order_id']}"}],
            "is_error": True,
        }
    return {"content": [{"type": "text", "text": f"Order {args['order_id']}: {status}"}]}


shop_server = create_sdk_mcp_server(
    name="shop", version="1.0.0", tools=[get_order_status]
)


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"shop": shop_server},
        allowed_tools=["mcp__shop__get_order_status"],
    )
    async for message in query(prompt="Where is order A100?", options=options):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

Copier le prompt

Un outil en TypeScript

TypeScript décrit les entrées des outils avec Zod, donc installez npm install zod d’abord :

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const orders: Record<string, string> = { A100: "shipped", A101: "packing" };

const getOrderStatus = tool(
  "get_order_status",
  "Look up the status of an order by its id",
  { order_id: z.string().describe("Order id such as A100") },
  async (args) => {
    const status = orders[args.order_id];
    if (!status) {
      return {
        content: [{ type: "text", text: `No order ${args.order_id}` }],
        isError: true
      };
    }
    return { content: [{ type: "text", text: `Order ${args.order_id}: ${status}` }] };
  }
);

const shopServer = createSdkMcpServer({
  name: "shop",
  version: "1.0.0",
  tools: [getOrderStatus]
});

for await (const message of query({
  prompt: "Where is order A100?",
  options: {
    mcpServers: { shop: shopServer },
    allowedTools: ["mcp__shop__get_order_status"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Copier le prompt

💡 Astuce : Pour les échecs prévisibles, comme un numéro de commande inconnu, renvoyez is_error: True (isError: true en TypeScript) avec votre propre message. Claude lit ce message et peut réessayer ou expliquer, au lieu de recevoir une simple chaîne d’exception.

Subagents, hooks et limites

Un agent opérationnel est un bon début. Trois fonctionnalités permettent de garder prévisible un agent plus ambitieux : les subagents répartissent le travail, les hooks contrôlent chaque appel d’outil, et les limites arrêtent une session qui s’emballe.

Déléguer à des subagents

Un subagent est une instance d’agent distincte que votre agent principal lance pour une tâche ciblée. Chacun démarre avec un contexte neuf, si bien qu’un relecteur peut lire des dizaines de fichiers sans alourdir la conversation principale, et seul son message final remonte au parent. Vous les définissez avec l’option agents et ajoutez Agent aux outils autorisés.

Chaque définition nécessite une description (quand Claude doit l’utiliser) et une prompt (son comportement). Les champs facultatifs incluent tools, qui restreint ce à quoi il peut accéder, et model, qui accepte les alias sonnet, opus, haiku, fable et inherit, ou un identifiant de modèle complet.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Glob", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Reviews code for security and maintainability problems.",
                prompt="You are a careful reviewer. Report concrete problems with file names.",
                tools=["Read", "Grep", "Glob"],
                model="sonnet",
            ),
            "test-runner": AgentDefinition(
                description="Runs the test suite and summarizes failures.",
                prompt="Run the tests, then list each failing test with its error.",
                tools=["Bash", "Read", "Grep"],
            ),
        },
    )
    async for message in query(
        prompt="Use the code-reviewer agent to check the auth module",
        options=options,
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Copier le prompt

La version TypeScript utilise des objets simples :

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the code-reviewer agent to check the auth module",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Agent"],
    agents: {
      "code-reviewer": {
        description: "Reviews code for security and maintainability problems.",
        prompt: "You are a careful reviewer. Report concrete problems with file names.",
        tools: ["Read", "Grep", "Glob"],
        model: "sonnet"
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Copier le prompt

Nommer le subagent dans votre prompt, comme ci-dessus, garantit que Claude l’utilise. Sans cela, Claude compare la tâche à chaque description, si bien que des descriptions vagues entraînent des délégations manquées.

💡 Note sur les versions : L’outil apparaît sous le nom Agent dans les blocs d’utilisation d’outils. Les anciennes versions l’appelaient Task, et la liste d’outils du message d’initialisation utilise toujours ce nom. Vérifiez donc les deux noms lorsque vous détectez les appels de subagents dans le flux de messages.

Bloquer les appels risqués avec des hooks

Les hooks sont des callbacks exécutés à des points fixes de la boucle de l’agent. Le plus utile est PreToolUse, qui se déclenche avant l’exécution d’un outil et peut la refuser. Un matcher filtre par nom d’outil, par exemple Bash ou Write|Edit. Renvoyez {} pour autoriser l’appel.

Ce hook Python refuse toute commande shell contenant une suppression récursive :

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher


async def block_destructive_bash(input_data, tool_use_id, context):
    command = input_data["tool_input"].get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Recursive deletes are blocked",
            }
        }
    return {}


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Bash", "Read"],
        hooks={
            "PreToolUse": [HookMatcher(matcher="Bash", hooks=[block_destructive_bash])]
        },
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Clean up the build folder")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Copier le prompt

Et la même protection en TypeScript :

import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

const blockDestructiveBash: HookCallback = async (input) => {
  const pre = input as PreToolUseHookInput;
  const toolInput = pre.tool_input as Record<string, unknown>;
  const command = String(toolInput?.command ?? "");

  if (command.includes("rm -rf")) {
    return {
      hookSpecificOutput: {
        hookEventName: pre.hook_event_name,
        permissionDecision: "deny",
        permissionDecisionReason: "Recursive deletes are blocked"
      }
    };
  }
  return {};
};

for await (const message of query({
  prompt: "Clean up the build folder",
  options: {
    allowedTools: ["Bash", "Read"],
    hooks: { PreToolUse: [{ matcher: "Bash", hooks: [blockDestructiveBash] }] }
  }
})) {
  if (message.type === "result") console.log(message.subtype);
}

Copier le prompt

Lorsque plusieurs hooks correspondent, ils s’exécutent en parallèle et la réponse la plus stricte l’emporte. Un seul deny bloque l’appel quoi que renvoient les autres, donc écrivez chaque hook pour qu’il fonctionne de manière autonome.

Plafonner les tours et les dépenses

Les modes de permission définissent le niveau de confiance par défaut. Choisissez-en un avec permission_mode ou permissionMode :

Deux limites numériques protègent votre budget. max_turns (maxTurns) plafonne les tours agentiques, et max_budget_usd (maxBudgetUsd) plafonne la dépense estimée. Les atteindre met fin à la requête avec les sous-types de résultat error_max_turns ou error_max_budget_usd. Les requêtes des subagents comptent dans la même total_cost_usd, donc une consigne qui se répartit en de nombreux subagents reste soumise au même plafond.

💡 Astuce pour les tâches sans surveillance : Combinez dontAsk avec une liste explicite d’outils autorisés. Tout ce qui ne figure pas dans la liste est refusé immédiatement, au lieu d’attendre un humain qui n’est pas là.

Trois erreurs reviennent sans cesse dans les premiers agents :

• Accorder Bash trop tôt. Commencez avec des outils en lecture seule et ajoutez Edit ou Bash seulement lorsque la tâche l’exige.
• Des descriptions de subagents vagues. Claude délègue en fonction du texte de description, donc un « agent d’aide » est ignoré alors que « Analyse le code à la recherche de problèmes de sécurité » est utilisé.
• Aucune limite lors d’un premier lancement. Définissez max_turns et max_budget_usd avant de diriger l’agent vers un grand dépôt.

Conserver le contexte entre les sessions

Chaque appel à query() démarre une nouvelle session. Lorsqu’un suivi doit se souvenir de ce que l’agent a déjà lu et décidé, il faut un moyen de poursuivre la session.

Multi-tours en Python

ClaudeSDKClient gère la session à votre place. Chaque client.query() poursuit la même conversation :

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Glob", "Grep"])

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Inspect the auth module")
        async for message in client.receive_response():
            print(message)

        # Same session, so the agent remembers the first answer
        await client.query("Now refactor it to use JWT")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Copier le prompt

Reprendre en TypeScript

TypeScript n’a pas d’objet client, donc vous récupérez le session_id depuis le message de résultat et le renvoyez via resume :

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;

for await (const message of query({
  prompt: "Inspect the auth module",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result") sessionId = message.session_id;
}

for await (const message of query({
  prompt: "Now propose a refactor based on what you found",
  options: { resume: sessionId, allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Copier le prompt

Python accepte la même idée sous la forme resume=session_id. Les deux langages prennent aussi en charge continue_conversation=True / continue: true pour reprendre la session la plus récente du dossier, et fork_session=True / forkSession: true pour créer une copie de l’historique afin d’essayer une autre approche sans perdre l’original.

Deux limites comptent dans la pratique. Les sessions conservent la conversation, pas vos fichiers : un agent bifurqué qui modifie du code change donc les vrais fichiers. Et les fichiers de session résident sur la machine qui les a créés, donc reprendre une session sur un autre hôte nécessite un adaptateur de stockage de sessions ou une transcription copiée.

Utiliser Claude Sonnet 5 sur PicassoIA

L’Agent SDK fonctionne sur votre machine avec vos propres identifiants, donc PicassoIA ne le remplace pas. Là où PicassoIA aide, c’est à l’étape de rédaction. La formulation d’un prompt système, d’une description de subagent ou d’un outil détermine la qualité du comportement d’un agent, et tester une formulation dans une interface de chat est plus rapide que relancer un script dix fois.

Rédiger les prompts avant de coder

Claude Sonnet 5 est conçu pour les tâches de programmation en plusieurs étapes et l’usage d’outils, ce qui en fait un bon substitut pour répéter les instructions d’un agent. Suivez ces étapes :

1. Ouvrez la page Claude Sonnet 5 sur PicassoIA.
2. Collez vos instructions d’agent provisoires dans le champ System Prompt.
3. Saisissez une tâche réaliste dans Prompt, par exemple le contenu de utils.py suivi de « liste toutes les entrées qui le feraient planter ».
4. Réglez effort. La valeur par défaut est low, qui désactive la réflexion pour obtenir la réponse la plus rapide et la moins chère. Montez à high ou max pour les bogues qui touchent plusieurs fichiers.
5. Laissez max_tokens sur la valeur par défaut de 8192, suffisante pour du code ou un texte détaillé dans une seule réponse.
6. Vous pouvez joindre une capture d’écran d’erreur via l’entrée image, puisque le modèle sait la lire.
7. Lancez l’essai, affinez la formulation jusqu’à obtenir la réponse souhaitée, puis copiez le texte final dans system_prompt ou dans le prompt d’un subagent.

💡 À retenir : Cette étape ne sert qu’à répéter la formulation. Les outils de fichiers, les hooks et la boucle d’agent viennent toujours du SDK sur votre machine.

Choisir le bon modèle Claude

PicassoIA propose plusieurs modèles Claude, et chacun convient à un type de rédaction différent :

Dans le SDK lui-même, le champ model accepte les alias décrits plus haut. Vous pouvez donc utiliser un modèle économique pour les subagents courants et un modèle plus puissant pour le fil principal.

Créer vos propres images avec PicassoIA

Vous disposez maintenant d’un agent fonctionnel et de l’habitude de tester chaque élément avant de le mettre en production. Cette même habitude améliore la génération d’images, et PicassoIA est un endroit rapide pour s’y entraîner.

Ouvrez Seedream 4.5 ou GPT Image 2 et rédigez un prompt avec la même structure que celle utilisée pour les photos de cet article : le sujet et son action, le décor, la direction de la lumière, l’objectif et une ou deux textures de surface. Une phrase comme « mains tapant sur un clavier à un bureau en bois, lumière douce de fenêtre venant de la droite, objectif 85 mm, faible profondeur de champ, poussière visible sur le grain du bois » donne au modèle bien plus à travailler que « un programmeur qui tape ».

Essayez-le sur le prochain en-tête de blog, la prochaine photo produit ou la prochaine bannière de documentation dont vous avez besoin. Modifiez un seul détail à chaque essai, comparez les résultats côte à côte et conservez le prompt qui fonctionne. Pour découvrir ce qui est disponible, parcourez tous les modèles sur picassoia.com/en/all-models et lancez votre première génération dès aujourd’hui.