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"
  }
}

5. Rivedere i cambiamenti significativi

Apportare le modifiche al codice necessarie per completare la migrazione.

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:

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

// PRIMA (v0.0.x) - Utilizzava il system prompt di Claude Code per impostazione predefinita
const before = 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 presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Oppure utilizzare un system prompt personalizzato:
const customResult = 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:

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

const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // Nessuna impostazione del file system caricata
}
});

// Oppure caricare solo fonti specifiche:
const projectOnlyResult = 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 install per 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-sdk per 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

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

12 12

13Claude 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.13Claude 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.

14 14

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

16 Cosa è cambiato16 Cosa è cambiato

17</h2>17</h2>

18 18

82}82}

83```83```

84 84

~~85Questo è tutto! Non sono richieste altre modifiche al codice.~~85**5. Rivedere i [cambiamenti significativi](#breaking-changes)**

87Apportare le modifiche al codice necessarie per completare la migrazione.

86 88

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

88 Per progetti Python90 Per progetti Python

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 // PRIMA (v0.0.x) - Utilizzava il system prompt di Claude Code per impostazione predefinita179 // PRIMA (v0.0.x) - Utilizzava il system prompt di Claude Code per impostazione predefinita

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

177 181

178 // DOPO (v0.1.0) - Utilizza un system prompt minimo per impostazione predefinita182 // DOPO (v0.1.0) - Utilizza un system prompt minimo per impostazione predefinita

179 // Per ottenere il comportamento precedente, richiedere esplicitamente il preset di Claude Code:183 // Per ottenere il comportamento precedente, richiedere esplicitamente il preset di Claude Code:

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 // Oppure utilizzare un system prompt personalizzato:191 // Oppure utilizzare un system prompt personalizzato:

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: [] // Nessuna impostazione del file system caricata245 settingSources: [] // Nessuna impostazione del file system caricata

241 });247 });

242 248

243 // Oppure caricare solo fonti specifiche:249 // Oppure caricare solo fonti specifiche:

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

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

246 options: {252 options: {

247 settingSources: ["project"] // Solo impostazioni del progetto253 settingSources: ["project"] // Solo impostazioni del progetto

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

Migrazione a Claude Agent SDK

Panoramica

Cosa è cambiato

Passaggi di migrazione

Per progetti TypeScript/JavaScript

Per progetti Python

Cambiamenti significativi

Python: ClaudeCodeOptions rinominato in ClaudeAgentOptions

System prompt non è più predefinito

Impostazioni predefinite delle fonti

Perché il cambio di nome?

Ottenere aiuto

Passaggi successivi