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

Migrer un projet TypeScript ou 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.

Migrer un projet 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

[!WARNING]

Pour améliorer l'isolation et la configuration explicite, Claude Agent SDK v0.1.0 introduit des changements majeurs pour les utilisateurs migrant depuis Claude Code SDK.

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.

[!NOTE]

Python SDK 0.1.59 et antérieures traitaient une liste vide de la même manière que l'omission de l'option, donc mettez à jour avant de vous fier à setting_sources=[]. Consultez Ce que settingSources ne contrôle pas pour les entrées qui sont lues même lorsque settingSources est [].

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