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"
}
}
Das ist alles! Keine weiteren Codeänderungen sind erforderlich.
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:
// VORHER (v0.0.x) - Verwendete Claude Codes System-Prompt standardmäßig
const result = 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 result = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// Oder verwenden Sie einen benutzerdefinierten System-Prompt:
const result = 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:
const result = query({
prompt: "Hello",
options: {
settingSources: [] // Keine Dateisystem-Einstellungen geladen
}
});
// Oder laden Sie nur bestimmte Quellen:
const result = 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-sdkzu verwenden - Überprüfen Sie, dass Ihre package.json den neuen Paketnamen hat
- Führen Sie
npm installaus, um sicherzustellen, dass die Abhängigkeiten aktualisiert werden
Für Python:
- Überprüfen Sie, dass alle Importe aktualisiert wurden, um
claude_agent_sdkzu verwenden - Überprüfen Sie, dass Ihre requirements.txt oder pyproject.toml den neuen Paketnamen hat
- Führen Sie
pip install claude-agent-sdkaus, 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