​
Panoramica

Il 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 costruire agenti AI oltre ai semplici compiti di codifica.

​
Cosa è Cambiato

AspettoVecchioNuovo
Nome del Pacchetto (TS/JS)@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Pacchetto Pythonclaude-code-sdkclaude-agent-sdk
Posizione della DocumentazioneDocumentazione Claude Code → sezione SDKGuida API → sezione Agent SDK
Modifiche alla Documentazione: La documentazione dell’Agent SDK è stata spostata dalla documentazione Claude Code alla Guida API sotto una sezione dedicata Agent SDK. La documentazione Claude Code ora si concentra sullo strumento CLI e sulle funzionalità di automazione.

​
Passaggi di Migrazione

​
Per Progetti TypeScript/JavaScript

1. Disinstalla il vecchio pacchetto: 
npm uninstall @anthropic-ai/claude-code
2. Installa il nuovo pacchetto: 
npm install @anthropic-ai/claude-agent-sdk
3. Aggiorna le tue importazioni: Cambia tutte le importazioni 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. Aggiorna le dipendenze del package.json: Se hai il pacchetto elencato nel tuo package.json, aggiornalo: 
// Prima
{
  "dependencies": {
    "@anthropic-ai/claude-code": "^1.0.0"
  }
}

// Dopo
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
  }
}
Questo è tutto! Non sono richieste altre modifiche al codice.

​
Per Progetti Python

1. Disinstalla il vecchio pacchetto: 
pip uninstall claude-code-sdk
2. Installa il nuovo pacchetto: 
pip install claude-agent-sdk
3. Aggiorna le tue importazioni: Cambia tutte le importazioni 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. Aggiorna i nomi dei tipi: Cambia ClaudeCodeOptions in ClaudeAgentOptions: 
# Prima
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5"
)

# Dopo
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5"
)
5. Rivedi le modifiche che rompono la compatibilità Apporta le modifiche al codice necessarie per completare la migrazione.

​
Modifiche che rompono la compatibilità

Per migliorare l’isolamento e la configurazione esplicita, Claude Agent SDK v0.1.0 introduce modifiche che rompono la compatibilità per gli utenti che migrano da Claude Code SDK. Rivedi attentamente questa sezione prima di migrare.

​
Python: ClaudeCodeOptions rinominato in ClaudeAgentOptions

Cosa è cambiato: Il tipo ClaudeCodeOptions dell’SDK Python è stato rinominato in ClaudeAgentOptions. Migrazione: 
# PRIMA (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5",
    permission_mode="acceptEdits"
)

# DOPO (v0.1.0)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    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.

​
Il prompt di sistema non è più predefinito

Cosa è cambiato: L’SDK non utilizza più il prompt di sistema di Claude Code per impostazione predefinita. Migrazione: 
// PRIMA (v0.0.x) - Utilizzava il prompt di sistema di Claude Code per impostazione predefinita
const result = query({ prompt: "Ciao" });

// DOPO (v0.1.0) - Utilizza un prompt di sistema vuoto per impostazione predefinita
// Per ottenere il comportamento precedente, richiedi esplicitamente il preset di Claude Code:
const result = query({
  prompt: "Ciao",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Oppure usa un prompt di sistema personalizzato:
const result = query({
  prompt: "Ciao",
  options: {
    systemPrompt: "Sei un assistente di codifica utile"
  }
});
Perché è cambiato: Fornisce un migliore controllo e isolamento per le applicazioni SDK. Ora puoi costruire agenti con comportamenti personalizzati senza ereditare le istruzioni orientate alla CLI di Claude Code.

​
Le Sorgenti delle Impostazioni Non Vengono Più Caricate per Impostazione Predefinita

Cosa è cambiato: L’SDK non legge più dalle impostazioni del filesystem (CLAUDE.md, settings.json, comandi slash, ecc.) per impostazione predefinita. Migrazione: 
// PRIMA (v0.0.x) - Caricava tutte le impostazioni automaticamente
const result = query({ prompt: "Ciao" });
// Avrebbe letto da:
// - ~/.claude/settings.json (utente)
// - .claude/settings.json (progetto)
// - .claude/settings.local.json (locale)
// - File CLAUDE.md
// - Comandi slash personalizzati

// DOPO (v0.1.0) - Nessuna impostazione caricata per impostazione predefinita
// Per ottenere il comportamento precedente:
const result = query({
  prompt: "Ciao",
  options: {
    settingSources: ["user", "project", "local"]
  }
});

// Oppure carica solo sorgenti specifiche:
const result = query({
  prompt: "Ciao",
  options: {
    settingSources: ["project"]  // Solo impostazioni del progetto
  }
});
Perché è cambiato: Garantisce che le applicazioni SDK abbiano un comportamento prevedibile indipendente dalle configurazioni del filesystem locale. Questo è particolarmente importante per:
  • Ambienti CI/CD - Comportamento coerente senza personalizzazioni locali
  • Applicazioni distribuite - Nessuna dipendenza dalle impostazioni del filesystem
  • Test - Ambienti di test isolati
  • Sistemi multi-tenant - Prevenire la perdita di impostazioni tra utenti
Compatibilità all’indietro: Se la tua applicazione si basava sulle impostazioni del filesystem (comandi slash personalizzati, istruzioni CLAUDE.md, ecc.), aggiungi settingSources: ['user', 'project', 'local'] alle tue opzioni.

​
Perché la Ridenominazione?

Il Claude Code SDK era originariamente progettato per compiti di codifica, ma si è evoluto in un framework potente per costruire tutti i tipi di agenti AI. Il nuovo nome “Claude Agent SDK” riflette meglio le sue capacità:
  • Costruire agenti aziendali (assistenti legali, consulenti finanziari, supporto clienti)
  • Creare agenti di codifica specializzati (bot SRE, revisori di sicurezza, agenti di revisione del codice)
  • Sviluppare agenti personalizzati per qualsiasi dominio con uso di strumenti, integrazione MCP e altro

​
Ottenere Aiuto

Se incontri problemi durante la migrazione: Per TypeScript/JavaScript:
  1. Verifica che tutte le importazioni siano aggiornate per utilizzare @anthropic-ai/claude-agent-sdk
  2. Verifica che il tuo package.json abbia il nuovo nome del pacchetto
  3. Esegui npm install per assicurarti che le dipendenze siano aggiornate
Per Python:
  1. Verifica che tutte le importazioni siano aggiornate per utilizzare claude_agent_sdk
  2. Verifica che il tuo requirements.txt o pyproject.toml abbia il nuovo nome del pacchetto
  3. Esegui pip install claude-agent-sdk per assicurarti che il pacchetto sia installato
Consulta la guida Risoluzione dei Problemi per problemi comuni.

​
Prossimi Passi