Migrazione a Claude Agent SDK
Guida per la migrazione dei Claude Code SDK TypeScript e Python a Claude Agent SDK
Panoramica
Claude Code SDK è stato rinominato in Claude Agent SDK e la sua documentazione è stata riorganizzata. Questo cambiamento riflette le capacità più ampie dell'SDK per la creazione di agenti AI oltre ai soli compiti di codifica.
Cosa è cambiato
| Aspetto | Precedente | Nuovo |
|---|---|---|
| Nome del pacchetto (TS/JS) | @anthropic-ai/claude-code |
@anthropic-ai/claude-agent-sdk |
| Pacchetto Python | claude-code-sdk |
claude-agent-sdk |
| Posizione della documentazione | Documentazione Claude Code | API Guide → Sezione Agent SDK |
Passaggi di migrazione
Per progetti TypeScript/JavaScript
1. Disinstallare il pacchetto precedente:
npm uninstall @anthropic-ai/claude-code
2. Installare il nuovo pacchetto:
npm install @anthropic-ai/claude-agent-sdk
3. Aggiornare gli import:
Modificare tutti gli import da @anthropic-ai/claude-code a @anthropic-ai/claude-agent-sdk:
// Prima
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
// Dopo
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
4. Aggiornare le dipendenze in package.json:
Se il pacchetto è elencato nel vostro package.json, aggiornarlo:
Prima:
{
"dependencies": {
"@anthropic-ai/claude-code": "^0.0.42"
}
}
Dopo:
{
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.2.0"
}
}
Questo è tutto! Non sono richieste altre modifiche al codice.
Per progetti Python
1. Disinstallare il pacchetto precedente:
pip uninstall claude-code-sdk
2. Installare il nuovo pacchetto:
pip install claude-agent-sdk
3. Aggiornare gli import:
Modificare tutti gli import da claude_code_sdk a claude_agent_sdk:
# Prima
from claude_code_sdk import query, ClaudeCodeOptions
# Dopo
from claude_agent_sdk import query, ClaudeAgentOptions
4. Aggiornare i nomi dei tipi:
Modificare ClaudeCodeOptions in ClaudeAgentOptions:
# Prima
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7")
# Dopo
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7")
5. Rivedere i cambiamenti significativi
Apportare le modifiche al codice necessarie per completare la migrazione.
Cambiamenti significativi
Python: ClaudeCodeOptions rinominato in ClaudeAgentOptions
Cosa è cambiato: Il tipo Python SDK ClaudeCodeOptions è stato rinominato in ClaudeAgentOptions.
Migrazione:
# PRIMA (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
# DOPO (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
Perché è cambiato: Il nome del tipo ora corrisponde al branding "Claude Agent SDK" e fornisce coerenza nelle convenzioni di denominazione dell'SDK.
System prompt non è più predefinito
Cosa è cambiato: L'SDK non utilizza più il system prompt di Claude Code per impostazione predefinita.
Migrazione:
// PRIMA (v0.0.x) - Utilizzava il system prompt di Claude Code per impostazione predefinita
const result = query({ prompt: "Hello" });
// DOPO (v0.1.0) - Utilizza un system prompt minimo per impostazione predefinita
// Per ottenere il comportamento precedente, richiedere esplicitamente il preset di Claude Code:
const result = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// Oppure utilizzare un system prompt personalizzato:
const result = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});
# PRIMA (v0.0.x) - Utilizzava il system prompt di Claude Code per impostazione predefinita
async for message in query(prompt="Hello"):
print(message)
# DOPO (v0.1.0) - Utilizza un system prompt minimo per impostazione predefinita
# Per ottenere il comportamento precedente, richiedere esplicitamente il preset di Claude Code:
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"} # Utilizzare il preset
),
):
print(message)
# Oppure utilizzare un system prompt personalizzato:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)
Perché è cambiato: Fornisce un migliore controllo e isolamento per le applicazioni SDK. Ora è possibile creare agenti con comportamento personalizzato senza ereditare le istruzioni focalizzate sulla CLI di Claude Code.
Impostazioni predefinite delle fonti
Questo valore predefinito è stato brevemente modificato in v0.1.0 e successivamente ripristinato, quindi non è necessaria alcuna azione di migrazione.
Comportamento attuale: Omettendo settingSources su query() vengono caricate le impostazioni dell'utente, del progetto e del file system locale, corrispondendo alla CLI. Questo include ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, file CLAUDE.md e comandi personalizzati.
Per eseguire l'isolamento dalle impostazioni del file system, passare un array vuoto:
const result = query({
prompt: "Hello",
options: {
settingSources: [] // Nessuna impostazione del file system caricata
}
});
// Oppure caricare solo fonti specifiche:
const result = query({
prompt: "Hello",
options: {
settingSources: ["project"] // Solo impostazioni del progetto
}
});
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]), # Nessuna impostazione del file system caricata
):
print(message)
# Oppure caricare solo fonti specifiche:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"] # Solo impostazioni del progetto
),
):
print(message)
L'isolamento è particolarmente importante per le pipeline CI/CD, le applicazioni distribuite, gli ambienti di test e i sistemi multi-tenant dove le personalizzazioni locali non dovrebbero infiltrarsi.
Perché il cambio di nome?
Claude Code SDK è stato originariamente progettato per compiti di codifica, ma si è evoluto in un framework potente per la creazione di tutti i tipi di agenti AI. Il nuovo nome "Claude Agent SDK" riflette meglio le sue capacità:
- Creazione di agenti aziendali (assistenti legali, consulenti finanziari, supporto clienti)
- Creazione di agenti di codifica specializzati (bot SRE, revisori di sicurezza, agenti di revisione del codice)
- Sviluppo di agenti personalizzati per qualsiasi dominio con utilizzo di strumenti, integrazione MCP e altro ancora
Ottenere aiuto
Se si incontrano problemi durante la migrazione:
Per TypeScript/JavaScript:
- Verificare che tutti gli import siano aggiornati per utilizzare
@anthropic-ai/claude-agent-sdk - Verificare che il vostro package.json abbia il nuovo nome del pacchetto
- Eseguire
npm installper assicurarsi che le dipendenze siano aggiornate
Per Python:
- Verificare che tutti gli import siano aggiornati per utilizzare
claude_agent_sdk - Verificare che il vostro requirements.txt o pyproject.toml abbia il nuovo nome del pacchetto
- Eseguire
pip install claude-agent-sdkper assicurarsi che il pacchetto sia installato
Passaggi successivi
- Esplorare la Panoramica di Agent SDK per conoscere le funzionalità disponibili
- Consultare il Riferimento SDK TypeScript per la documentazione dettagliata dell'API
- Rivedere il Riferimento SDK Python per la documentazione specifica di Python
- Scopri di più su Strumenti personalizzati e Integrazione MCP