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 SDKs für die Erstellung von KI-Agenten über reine Codierungsaufgaben hinaus wider.

Was hat sich geändert

Aspekt	Alt	Neu
Paketname (TS/JS)	`@anthropic-ai/claude-code`	`@anthropic-ai/claude-agent-sdk`
Python-Paket	`claude-code-sdk`	`claude-agent-sdk`
Dokumentationsort	Claude Code-Dokumentation	API-Leitfaden → Agent SDK-Bereich

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 die package.json-Abhängigkeiten:

Wenn Sie das Paket in Ihrer package.json aufgelistet haben, aktualisieren Sie es:

Vorher:

{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}

Nachher:

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.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 claude-code-sdk

2. Installieren Sie das neue Paket:

pip install 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. Aktualisieren Sie die Typnamen:

Ändern Sie ClaudeCodeOptions zu ClaudeAgentOptions:

# Vorher
from claude_code_sdk import query, ClaudeCodeOptions

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

# Nachher
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. Überprüfen Sie Breaking Changes

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

Breaking Changes

Python: ClaudeCodeOptions in ClaudeAgentOptions umbenannt

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

Migration:

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

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

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

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

Warum sich das geändert hat: Der Typname entspricht nun dem Branding „Claude Agent SDK" und bietet Konsistenz in den Namenskonventionen des SDKs.

System-Prompt ist nicht mehr Standard

Was hat sich geändert: Das SDK verwendet nicht mehr standardmäßig Claude Codes System-Prompt.

Migration:

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

// VORHER (v0.0.x) - Verwendete Claude Codes System-Prompt standardmäßig
const before = query({ prompt: "Hello" });

// NACHHER (v0.1.0) - Verwendet standardmäßig minimalen System-Prompt
// Um das alte Verhalten zu erhalten, fordern Sie explizit Claude Codes Voreinstellung an:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Oder verwenden Sie einen benutzerdefinierten System-Prompt:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

# VORHER (v0.0.x) - Verwendete Claude Codes System-Prompt standardmäßig
async for message in query(prompt="Hello"):
print(message)

# NACHHER (v0.1.0) - Verwendet standardmäßig minimalen System-Prompt
# Um das alte Verhalten zu erhalten, fordern Sie explizit Claude Codes Voreinstellung an:
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}  # Verwenden Sie die Voreinstellung
),
):
print(message)

# Oder verwenden Sie einen benutzerdefinierten System-Prompt:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)

Warum sich das geändert hat: Bietet bessere Kontrolle und Isolation für SDK-Anwendungen. Sie können nun Agenten mit benutzerdefiniertem Verhalten erstellen, ohne Claude Codes CLI-fokussierte Anweisungen zu erben.

Einstellungsquellen-Standard

Dieser Standard wurde kurzzeitig in v0.1.0 geändert und dann rückgängig gemacht, daher ist keine Migrationsaktion erforderlich.

Aktuelles Verhalten: Das Weglassen von settingSources auf query() lädt Benutzer-, Projekt- und lokale Dateisystem-Einstellungen, was dem 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 ein leeres Array:

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

const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // Keine Dateisystem-Einstellungen geladen
}
});

// Oder laden Sie nur bestimmte Quellen:
const projectOnlyResult = query({
prompt: "Hello",
options: {
settingSources: ["project"] // Nur Projekteinstellungen
}
});

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]),  # Keine Dateisystem-Einstellungen geladen
):
print(message)

# Oder laden Sie nur bestimmte Quellen:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"]  # Nur Projekteinstellungen
),
):
print(message)

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

Warum die Umbenennung?

Das Claude Code SDK wurde ursprünglich für Codierungsaufgaben entwickelt, hat sich aber zu einem leistungsstarken Framework für die Erstellung aller Arten von KI-Agenten entwickelt. Der neue Name „Claude Agent SDK" spiegelt seine Funktionen besser wider:

Erstellung von Business-Agenten (Rechtsassistenten, Finanzberater, Kundensupport)
Erstellung spezialisierter Codierungs-Agenten (SRE-Bots, Sicherheitsprüfer, Code-Review-Agenten)
Entwicklung benutzerdefinierter Agenten für jede Domäne mit Tool-Nutzung, MCP-Integration und mehr

Hilfe erhalten

Wenn Sie während der Migration auf Probleme stoßen:

Für TypeScript/JavaScript:

Überprüfen Sie, dass alle Importe aktualisiert wurden, um @anthropic-ai/claude-agent-sdk zu verwenden
Überprüfen Sie, dass Ihre package.json den neuen Paketnamen hat
Führen Sie npm install aus, um sicherzustellen, dass die Abhängigkeiten aktualisiert werden

Für Python:

Überprüfen Sie, dass alle Importe aktualisiert wurden, um claude_agent_sdk zu verwenden
Überprüfen Sie, dass Ihre requirements.txt oder pyproject.toml den neuen Paketnamen hat
Führen Sie pip install claude-agent-sdk aus, um sicherzustellen, dass das Paket installiert ist

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

agent-sdk/migration-guide.md +13 −7

12 12

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

14 14

~~15<h2 id="what-s-changed">~~15<h2 id="what’s-changed">

16 Was hat sich geändert16 Was hat sich geändert

17</h2>17</h2>

18 18

82}82}

83```83```

84 84

~~85Das ist alles! Keine weiteren Codeänderungen sind erforderlich.~~85**5. Überprüfen Sie [Breaking Changes](#breaking-changes)**

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

86 88

87<h3 id="for-python-projects">89<h3 id="for-python-projects">

88 Für Python-Projekte90 Für Python-Projekte

172 174

173<CodeGroup>175<CodeGroup>

174 ```typescript TypeScript theme={null}176 ```typescript TypeScript theme={null}

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

178

175 // VORHER (v0.0.x) - Verwendete Claude Codes System-Prompt standardmäßig179 // VORHER (v0.0.x) - Verwendete Claude Codes System-Prompt standardmäßig

176 const result = query({ prompt: "Hello" });180 const before = query({ prompt: "Hello" });

177 181

178 // NACHHER (v0.1.0) - Verwendet standardmäßig minimalen System-Prompt182 // NACHHER (v0.1.0) - Verwendet standardmäßig minimalen System-Prompt

179 // Um das alte Verhalten zu erhalten, fordern Sie explizit Claude Codes Voreinstellung an:183 // Um das alte Verhalten zu erhalten, fordern Sie explizit Claude Codes Voreinstellung an:

180 const result = query({184 const presetResult = query({

181 prompt: "Hello",185 prompt: "Hello",

182 options: {186 options: {

183 systemPrompt: { type: "preset", preset: "claude_code" }187 systemPrompt: { type: "preset", preset: "claude_code" }

185 });189 });

186 190

187 // Oder verwenden Sie einen benutzerdefinierten System-Prompt:191 // Oder verwenden Sie einen benutzerdefinierten System-Prompt:

188 const result = query({192 const customResult = query({

189 prompt: "Hello",193 prompt: "Hello",

190 options: {194 options: {

191 systemPrompt: "You are a helpful coding assistant"195 systemPrompt: "You are a helpful coding assistant"

233 237

234<CodeGroup>238<CodeGroup>

235 ```typescript TypeScript theme={null}239 ```typescript TypeScript theme={null}

236 const result = query({240 import { query } from "@anthropic-ai/claude-agent-sdk";

241

242 const isolatedResult = query({

237 prompt: "Hello",243 prompt: "Hello",

238 options: {244 options: {

239 settingSources: [] // Keine Dateisystem-Einstellungen geladen245 settingSources: [] // Keine Dateisystem-Einstellungen geladen

241 });247 });

242 248

243 // Oder laden Sie nur bestimmte Quellen:249 // Oder laden Sie nur bestimmte Quellen:

244 const result = query({250 const projectOnlyResult = query({

245 prompt: "Hello",251 prompt: "Hello",

246 options: {252 options: {

247 settingSources: ["project"] // Nur Projekteinstellungen253 settingSources: ["project"] // Nur Projekteinstellungen

agent-sdk/migration-guide.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

Migrieren zum Claude Agent SDK

Übersicht

Was hat sich geändert

Migrationsschritte

Für TypeScript/JavaScript-Projekte

Für Python-Projekte

Breaking Changes

Python: ClaudeCodeOptions in ClaudeAgentOptions umbenannt

System-Prompt ist nicht mehr Standard

Einstellungsquellen-Standard

Warum die Umbenennung?

Hilfe erhalten

Nächste Schritte