Démarrage rapide

Commencez avec le SDK Agent Python ou TypeScript pour créer des agents IA qui fonctionnent de manière autonome

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

• Node.js 18+ ou Python 3.10+
• Un compte Anthropic (s'inscrire ici)

Configuration

mkdir my-agent
cd my-agent

npm install @anthropic-ai/claude-agent-sdk

uv init
uv add claude-agent-sdk

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

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

ANTHROPIC_API_KEY=your-api-key

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 :

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()

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 :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
# Agentic loop: streams messages as Claude works
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],  # Auto-approve these tools
permission_mode="acceptEdits",  # Auto-approve file edits
),
):
# Print human-readable output
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)  # Claude's reasoning
elif hasattr(block, "name"):
print(f"Tool: {block.name}")  # Tool being called
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

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

// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}

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.

Exécuter votre agent

Votre agent est prêt. Exécutez-le avec la commande suivante :

npx tsx agent.ts

uv run agent.py

python agent.py

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.

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 :

options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "acceptEdits"
}
};

Donner à Claude une invite système personnalisée :

options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};

Exécuter des commandes dans le terminal :

options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};

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.

Dépannage

Erreur API `thinking.type.enabled` n'est pas pris en charge pour ce modèle

Claude Opus 4.7 remplace thinking.type.enabled par thinking.type.adaptive. Les versions plus anciennes du SDK Agent échouent avec l'erreur API suivante lorsque vous sélectionnez claude-opus-4-7 :

API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

Mettez à niveau vers le SDK Agent v0.2.111 ou version ultérieure pour utiliser Opus 4.7.

É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