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 :
- Configurer un projet avec le SDK Agent
- Créer un fichier avec du code contenant des bugs
- 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
Créer un dossier de projet
Créez un nouveau répertoire pour ce démarrage rapide :
mkdir my-agent
cd my-agent
Pour vos propres projets, vous pouvez exécuter le SDK à partir de n'importe quel dossier ; il aura accès aux fichiers de ce répertoire et de ses sous-répertoires par défaut.
Installer le SDK
Installez le package du SDK Agent pour votre langage :
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
Définir "type": "module" dans package.json permet à votre script d'agent d'utiliser await au niveau supérieur, et tsx exécute les fichiers TypeScript directement.
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
tsx exécute les fichiers TypeScript directement. Si votre projet utilise CommonJS, nommez votre script d'agent agent.mts au lieu de agent.ts. L'extension .mts fait que tsx traite le fichier comme un module ES, donc await au niveau supérieur fonctionne sans convertir tout votre projet en modules ES. Utilisez agent.mts à la place de agent.ts dans les étapes de création et d'exécution plus tard dans ce démarrage rapide.
uv est un gestionnaire de paquets Python rapide qui gère automatiquement les environnements virtuels :
uv init
uv add claude-agent-sdk
Créez et activez un environnement virtuel, puis installez le package.
Sur macOS ou Linux :
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
Sur Windows :
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk
Si PowerShell bloque Activate.ps1 avec une erreur de politique d'exécution, exécutez d'abord Set-ExecutionPolicy -Scope Process RemoteSigned.
Définir votre clé API
Obtenez une clé API à partir de la Console Claude, puis définissez-la comme variable d'environnement dans le shell où vous exécuterez votre agent :
export ANTHROPIC_API_KEY=your-api-key
$env:ANTHROPIC_API_KEY = "your-api-key"
Le SDK lit la clé à partir de l'environnement du processus qui exécute votre agent ; il ne charge pas les fichiers .env automatiquement. Si vous conservez la clé dans un fichier .env, chargez-la vous-même, par exemple avec le package dotenv, avant d'appeler le SDK.
Le SDK prend également en charge l'authentification via des fournisseurs d'API tiers :
- Amazon Bedrock : définissez la variable d'environnement
CLAUDE_CODE_USE_BEDROCK=1et configurez les identifiants AWS - Claude Platform on AWS : définissez
CLAUDE_CODE_USE_ANTHROPIC_AWS=1etANTHROPIC_AWS_WORKSPACE_ID, puis configurez les identifiants AWS - Google Vertex AI : définissez la variable d'environnement
CLAUDE_CODE_USE_VERTEX=1et configurez les identifiants Google Cloud - Microsoft Azure : définissez la variable d'environnement
CLAUDE_CODE_USE_FOUNDRY=1et configurez les identifiants Azure
Consultez les guides de configuration pour Bedrock, Claude Platform on AWS, Vertex AI ou Azure AI Foundry pour plus de détails.
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 :
calculate_average([])plante avec une division par zéroget_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. Utilisez agent.mts à la place si votre projet existant utilise CommonJS :
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 :
-
query: le point d'entrée principal qui crée la boucle agentique. Il retourne un itérateur asynchrone, vous utilisez doncasync forpour 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. -
prompt: ce que vous voulez que Claude fasse. Claude détermine les outils à utiliser en fonction de la tâche. -
options: configuration de l'agent. Cet exemple utiliseallowedToolspour pré-approuverRead,EditetGlob, etpermissionMode: "acceptEdits"pour approuver automatiquement les modifications de fichiers. Les autres options incluentsystemPrompt,mcpServerset 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
Si vous avez nommé votre script agent.mts, exécutez npx tsx agent.mts à la place.
uv run agent.py
Avec votre environnement virtuel toujours activé :
python agent.py
Au fur et à mesure qu'il travaille, l'agent imprime son raisonnement et chaque outil qu'il appelle, se terminant par Done: success. 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 :
- Lu
utils.pypour comprendre le code - Analysé la logique et identifié les cas limites qui causeraient un plantage
- 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 :
| Outils | Ce que l'agent peut faire |
|---|---|
Read, Glob, Grep |
Analyse en lecture seule |
Read, Edit, Glob |
Analyser et modifier le code |
Read, Edit, Bash, Glob, Grep |
Automatisation complète |
Les modes de permission contrôlent le niveau de surveillance humaine que vous souhaitez :
| Mode | Comportement | Cas d'usage |
|---|---|---|
acceptEdits |
Approuve automatiquement les modifications de fichiers et les commandes courantes du système de fichiers, demande les autres actions | Flux de travail de développement de confiance |
plan |
Exécute les outils en lecture seule ; les modifications de fichiers ne sont jamais approuvées automatiquement et atteignent votre rappel canUseTool |
Délimitation d'une tâche avant d'approuver l'exécution |
dontAsk |
Refuse tout ce qui n'est pas dans allowedTools |
Agents sans tête verrouillés |
auto (TypeScript uniquement) |
Un classificateur de modèle approuve ou refuse chaque appel d'outil | Agents autonomes avec garde-fous de sécurité |
bypassPermissions |
Exécute chaque outil sans invites, sauf si une règle ask explicite correspond |
CI en bac à sable, environnements entièrement de confiance |
default |
Nécessite un rappel canUseTool pour gérer l'approbation |
Flux d'approbation personnalisés |
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.
É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