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. Si vous n'en avez pas, inscrivez-vous ici.

Configuration

mkdir my-agent
cd my-agent

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

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

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

export ANTHROPIC_API_KEY=your-api-key

$env: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. 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 :

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, l'exécution des outils, la gestion du contexte et les 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

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 :

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"

Chacun de ces extraits définit des champs sur le même objet options. Pour plus d'informations, consultez Configurer votre agent.

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. Le SDK évalue le mode actif avec vos règles d'autorisation et de refus dans un ordre fixe, décrit dans Comment les permissions sont évaluées. Pour la liste complète des modes, leur comportement et quand utiliser chacun, consultez Mode de permission dans Comment fonctionne la boucle de l'agent.

Étapes suivantes

Maintenant que vous avez créé votre premier agent, apprenez à étendre ses capacités et à l'adapter à votre cas d'usage :

• Configurer votre agent : composez l'objet options et trouvez la page qui couvre chaque paramètre
• 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
• Dépannage : corrigez les erreurs quand l'interface de ligne de commande ne démarre pas ou se ferme, ou quand un résultat arrive sans sortie structurée