Migrer vers Claude Agent SDK

Guide pour migrer les SDK TypeScript et Python de Claude Code vers Claude Agent SDK

Aperçu

Le Claude Code SDK 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.

Vous migrez depuis le SDK OpenAI Agents ? La recette de migration du SDK OpenAI Agents mappe chaque primitive sur le Claude Agent SDK à travers un seul exemple travaillé.

Ce qui a changé

É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 package.json :

Si @anthropic-ai/claude-code est toujours listé dans votre package.json, remplacez-le par @anthropic-ai/claude-agent-sdk et mettez à jour la plage de version également, par exemple de "^0.0.42" à "^0.3.0".

5. Consultez les modifications incompatibles

Effectuez les modifications de code nécessaires pour terminer la migration.

Pour les projets Python

1. Désinstallez l'ancien package :

pip uninstall -y claude-code-sdk

Si l'ancien package n'est pas installé, pip affiche WARNING: Skipping claude-code-sdk as it is not installed. C'est normal et vous pouvez passer à l'étape suivante.

2. Installez le nouveau package :

pip install claude-agent-sdk

Si claude-code-sdk est listé dans votre requirements.txt ou pyproject.toml, remplacez-le par 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. Consultez les modifications incompatibles

Effectuez les modifications de code nécessaires pour terminer la migration.

Changements majeurs

Python : ClaudeCodeOptions renommé en ClaudeAgentOptions

Ce qui a changé : Le type Python SDK 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")

Le système de prompt n'est plus défini par défaut

Ce qui a changé : Le SDK n'utilise plus le système de prompt de Claude Code par défaut.

Migration :

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

// AVANT (v0.0.x) - Utilisait le système de prompt de Claude Code par défaut
const before = query({ prompt: "Hello" });

// APRÈS (v0.1.0) - Utilise un système de prompt minimal par défaut
// Pour obtenir l'ancien comportement, demandez explicitement le préréglage de Claude Code :
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Ou utilisez un système de prompt personnalisé :
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
# AVANT (v0.0.x) - Utilisait le système de 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 de prompt minimal par défaut
# Pour obtenir l'ancien comportement, demandez explicitement le préréglage de Claude Code :
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}  # Use the preset
),
):
print(message)

# Ou utilisez un système de prompt personnalisé :
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)


asyncio.run(main())

Défaut des sources de paramètres

Ce défaut a été brièvement modifié dans v0.1.0 pour ne charger aucun paramètre du système de fichiers, puis a été rétabli, donc aucune action de migration n'est nécessaire.

Comportement actuel : Omettre settingSources sur query() charge les paramètres utilisateur, projet et système de fichiers local, correspondant à la CLI. Cela inclut ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, les fichiers CLAUDE.md et les commandes personnalisées.

Pour fonctionner isolé des paramètres du système de fichiers, passez settingSources: [], ou setting_sources=[] en Python. Consultez Contrôler les paramètres du système de fichiers avec settingSources pour savoir ce que charge chaque source.

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'échapper.

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