Migrer vers Claude Agent SDK
Guide pour migrer les SDK TypeScript et Python de Claude Code vers Claude Agent SDK
Aperçu
Le SDK Claude Code a été renommé en Claude Agent SDK et sa documentation a été réorganisée. Ce changement reflète les capacités plus larges du SDK pour construire des agents IA au-delà des simples tâches de codage.
Qu'est-ce qui a changé
| Aspect | Ancien | Nouveau |
|---|---|---|
| Nom du package (TS/JS) | @anthropic-ai/claude-code |
@anthropic-ai/claude-agent-sdk |
| Package Python | claude-code-sdk |
claude-agent-sdk |
| Emplacement de la documentation | Documentation Claude Code | Guide API → Section Agent SDK |
Étapes de migration
Pour les projets TypeScript/JavaScript
1. Désinstallez l'ancien package :
npm uninstall @anthropic-ai/claude-code
2. Installez le nouveau package :
npm install @anthropic-ai/claude-agent-sdk
3. Mettez à jour vos imports :
Modifiez tous les imports de @anthropic-ai/claude-code vers @anthropic-ai/claude-agent-sdk :
// Avant
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
// Après
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
4. Mettez à jour les dépendances package.json :
Si vous avez le package listé dans votre package.json, mettez-le à jour :
Avant :
{
"dependencies": {
"@anthropic-ai/claude-code": "^0.0.42"
}
}
Après :
{
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.2.0"
}
}
C'est tout ! Aucune autre modification de code n'est requise.
Pour les projets Python
1. Désinstallez l'ancien package :
pip uninstall claude-code-sdk
2. Installez le nouveau package :
pip install claude-agent-sdk
3. Mettez à jour vos imports :
Modifiez tous les imports de claude_code_sdk vers claude_agent_sdk :
# Avant
from claude_code_sdk import query, ClaudeCodeOptions
# Après
from claude_agent_sdk import query, ClaudeAgentOptions
4. Mettez à jour les noms de types :
Modifiez ClaudeCodeOptions en ClaudeAgentOptions :
# Avant
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7")
# Après
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7")
5. Consultez les modifications incompatibles
Effectuez les modifications de code nécessaires pour terminer la migration.
Modifications incompatibles
Python : ClaudeCodeOptions renommé en ClaudeAgentOptions
Qu'est-ce qui a changé : Le type SDK Python ClaudeCodeOptions a été renommé en ClaudeAgentOptions.
Migration :
# AVANT (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
# APRÈS (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
Pourquoi ce changement : Le nom du type correspond désormais à la marque « Claude Agent SDK » et assure la cohérence dans les conventions de nommage du SDK.
Le système prompt n'est plus par défaut
Qu'est-ce qui a changé : Le SDK n'utilise plus le système prompt de Claude Code par défaut.
Migration :
// AVANT (v0.0.x) - Utilisait le système prompt de Claude Code par défaut
const result = query({ prompt: "Hello" });
// APRÈS (v0.1.0) - Utilise un système prompt minimal par défaut
// Pour obtenir l'ancien comportement, demandez explicitement le préréglage de Claude Code :
const result = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// Ou utilisez un système prompt personnalisé :
const result = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});
# AVANT (v0.0.x) - Utilisait le système prompt de Claude Code par défaut
async for message in query(prompt="Hello"):
print(message)
# APRÈS (v0.1.0) - Utilise un système prompt minimal par défaut
# Pour obtenir l'ancien comportement, demandez explicitement le préréglage de Claude Code :
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"} # Utiliser le préréglage
),
):
print(message)
# Ou utilisez un système prompt personnalisé :
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)
Pourquoi ce changement : Fournit un meilleur contrôle et une meilleure isolation pour les applications SDK. Vous pouvez désormais construire des agents avec un comportement personnalisé sans hériter des instructions axées sur le CLI de Claude Code.
Défaut des sources de paramètres
Ce défaut a été brièvement modifié dans v0.1.0 puis annulé, donc aucune action de migration n'est nécessaire.
Comportement actuel : L'omission de settingSources sur query() charge les paramètres utilisateur, projet et système de fichiers local, correspondant au CLI. Cela inclut ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, les fichiers CLAUDE.md et les commandes personnalisées.
Pour s'exécuter isolé des paramètres du système de fichiers, passez un tableau vide :
const result = query({
prompt: "Hello",
options: {
settingSources: [] // Aucun paramètre du système de fichiers chargé
}
});
// Ou charger uniquement des sources spécifiques :
const result = query({
prompt: "Hello",
options: {
settingSources: ["project"] // Uniquement les paramètres du projet
}
});
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]), # Aucun paramètre du système de fichiers chargé
):
print(message)
# Ou charger uniquement des sources spécifiques :
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"] # Uniquement les paramètres du projet
),
):
print(message)
L'isolation est particulièrement importante pour les pipelines CI/CD, les applications déployées, les environnements de test et les systèmes multi-locataires où les personnalisations locales ne doivent pas s'infiltrer.
Pourquoi le changement de nom ?
Le SDK Claude Code a été conçu à l'origine pour les tâches de codage, mais il a évolué en un cadre puissant pour construire tous les types d'agents IA. Le nouveau nom « Claude Agent SDK » reflète mieux ses capacités :
- Construire des agents commerciaux (assistants juridiques, conseillers financiers, support client)
- Créer des agents de codage spécialisés (bots SRE, examinateurs de sécurité, agents d'examen de code)
- Développer des agents personnalisés pour n'importe quel domaine avec utilisation d'outils, intégration MCP et bien plus
Obtenir de l'aide
Si vous rencontrez des problèmes lors de la migration :
Pour TypeScript/JavaScript :
- Vérifiez que tous les imports sont mis à jour pour utiliser
@anthropic-ai/claude-agent-sdk - Vérifiez que votre package.json a le nouveau nom de package
- Exécutez
npm installpour vous assurer que les dépendances sont mises à jour
Pour Python :
- Vérifiez que tous les imports sont mis à jour pour utiliser
claude_agent_sdk - Vérifiez que votre requirements.txt ou pyproject.toml a le nouveau nom de package
- Exécutez
pip install claude-agent-sdkpour vous assurer que le package est installé
Prochaines étapes
- Explorez l'Aperçu d'Agent SDK pour en savoir plus sur les fonctionnalités disponibles
- Consultez la Référence SDK TypeScript pour la documentation API détaillée
- Consultez la Référence SDK Python pour la documentation spécifique à Python
- En savoir plus sur les Outils personnalisés et l'Intégration MCP