Vai al contenuto principale

​
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

AspettoPrecedenteNuovo
Nome del pacchetto (TS/JS)@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Pacchetto Pythonclaude-code-sdkclaude-agent-sdk
Posizione della documentazioneDocumentazione Claude CodeAPI Guide → Sezione Agent SDK
Modifiche alla documentazione: La documentazione di Agent SDK è stata spostata dalla documentazione di Claude Code alla API Guide in una sezione dedicata Agent SDK. La documentazione di Claude Code ora si concentra sullo strumento CLI e sulle funzionalità di automazione.

​
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

Per migliorare l’isolamento e la configurazione esplicita, Claude Agent SDK v0.1.0 introduce cambiamenti significativi per gli utenti che migrano da Claude Code SDK. Rivedere attentamente questa sezione prima di eseguire la migrazione.

​
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"
  }
});
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
  }
});
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.
SDK v0.1.0 ha brevemente impostato per impostazione predefinita nessuna impostazione caricata; questo è stato ripristinato nelle versioni successive. Python SDK 0.1.59 e versioni precedenti hanno trattato un elenco vuoto come l’omissione dell’opzione, quindi eseguire l’aggiornamento prima di fare affidamento su setting_sources=[]. Vedere Cosa settingSources non controlla per gli input che vengono letti anche quando settingSources è [].

​
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:
  1. Verificare che tutti gli import siano aggiornati per utilizzare @anthropic-ai/claude-agent-sdk
  2. Verificare che il vostro package.json abbia il nuovo nome del pacchetto
  3. Eseguire npm install per assicurarsi che le dipendenze siano aggiornate
Per Python:
  1. Verificare che tutti gli import siano aggiornati per utilizzare claude_agent_sdk
  2. Verificare che il vostro requirements.txt o pyproject.toml abbia il nuovo nome del pacchetto
  3. Eseguire pip install claude-agent-sdk per assicurarsi che il pacchetto sia installato

​
Passaggi successivi