Migrieren zum Claude Agent SDK

Leitfaden für die Migration der Claude Code TypeScript- und Python-SDKs zum Claude Agent SDK

Übersicht

Das Claude Code SDK wurde in das Claude Agent SDK umbenannt und seine Dokumentation wurde neu organisiert. Diese Änderung spiegelt die umfassenderen Funktionen des SDK für die Erstellung von KI-Agenten über reine Codierungsaufgaben hinaus wider.

Migrieren Sie stattdessen vom OpenAI Agents SDK? Das OpenAI Agents SDK-Migrationskochbuch ordnet jedes Primitive dem Claude Agent SDK durch ein einzelnes durchgearbeitetes Beispiel zu.

Was hat sich geändert

Migrationsschritte

Für TypeScript/JavaScript-Projekte

1. Deinstallieren Sie das alte Paket:

npm uninstall @anthropic-ai/claude-code

2. Installieren Sie das neue Paket:

npm install @anthropic-ai/claude-agent-sdk

3. Aktualisieren Sie Ihre Importe:

Ändern Sie alle Importe von @anthropic-ai/claude-code zu @anthropic-ai/claude-agent-sdk:

// Vorher
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// Nachher
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. Aktualisieren Sie package.json:

Wenn @anthropic-ai/claude-code noch in Ihrer package.json aufgelistet ist, ersetzen Sie es durch @anthropic-ai/claude-agent-sdk und aktualisieren Sie auch den Versionsbereich, zum Beispiel von "^0.0.42" zu "^0.3.0".

5. Überprüfen Sie Breaking Changes

Nehmen Sie alle erforderlichen Codeänderungen vor, um die Migration abzuschließen.

Für Python-Projekte

1. Deinstallieren Sie das alte Paket:

pip uninstall -y claude-code-sdk

Wenn das alte Paket nicht installiert ist, gibt pip WARNING: Skipping claude-code-sdk as it is not installed. aus. Das ist zu erwarten und Sie können zum nächsten Schritt übergehen.

2. Installieren Sie das neue Paket:

pip install claude-agent-sdk

Wenn claude-code-sdk in Ihrer requirements.txt oder pyproject.toml aufgelistet ist, ersetzen Sie es durch claude-agent-sdk.

3. Aktualisieren Sie Ihre Importe:

Ändern Sie alle Importe von claude_code_sdk zu claude_agent_sdk:

# Vorher
from claude_code_sdk import query, ClaudeCodeOptions

# Nachher
from claude_agent_sdk import query, ClaudeAgentOptions

4. Überprüfen Sie Breaking Changes

Nehmen Sie alle erforderlichen Codeänderungen vor, um die Migration abzuschließen.

Grundlegende Änderungen

Python: ClaudeCodeOptions in ClaudeAgentOptions umbenannt

Was hat sich geändert: Der Python SDK-Typ ClaudeCodeOptions wurde in ClaudeAgentOptions umbenannt.

Migration:

# BEFORE (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# AFTER (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

System-Eingabeaufforderung ist nicht mehr Standard

Was hat sich geändert: Das SDK verwendet nicht mehr standardmäßig die System-Eingabeaufforderung von Claude Code.

Migration:

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

// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
const before = query({ prompt: "Hello" });

// AFTER (v0.1.0) - Uses minimal system prompt by default
// To get the old behavior, explicitly request Claude Code's preset:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Or use a custom system prompt:
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():
# BEFORE (v0.0.x) - Used Claude Code's system prompt by default
async for message in query(prompt="Hello"):
print(message)

# AFTER (v0.1.0) - Uses minimal system prompt by default
# To get the old behavior, explicitly request Claude Code's preset:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}  # Use the preset
),
):
print(message)

# Or use a custom system prompt:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)


asyncio.run(main())

Standardwerte für Einstellungsquellen

Dieser Standard wurde in v0.1.0 kurzzeitig geändert, um keine Dateisystem-Einstellungen zu laden, und wurde dann zurückgesetzt, daher ist keine Migrationsaktion erforderlich.

Aktuelles Verhalten: Das Weglassen von settingSources bei query() lädt Benutzer-, Projekt- und lokale Dateisystem-Einstellungen, was der CLI entspricht. Dies umfasst ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md-Dateien und benutzerdefinierte Befehle.

Um isoliert von Dateisystem-Einstellungen zu laufen, übergeben Sie settingSources: [] oder setting_sources=[] in Python. Siehe Dateisystem-Einstellungen mit settingSources steuern, um zu erfahren, welche Quellen jeweils geladen werden.

Die Isolation ist besonders wichtig für CI/CD-Pipelines, bereitgestellte Anwendungen, Testumgebungen und Multi-Tenant-Systeme, in denen lokale Anpassungen nicht durchsickern sollten.

Nächste Schritte

• Erkunden Sie die Agent SDK-Übersicht, um mehr über verfügbare Funktionen zu erfahren
• Schauen Sie sich die TypeScript SDK-Referenz für detaillierte API-Dokumentation an
• Überprüfen Sie die Python SDK-Referenz für Python-spezifische Dokumentation
• Erfahren Sie mehr über Benutzerdefinierte Tools und MCP-Integration