Migrazione 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

Passaggi di Migrazione

Per Progetti TypeScript/JavaScript

1. Disinstallare il vecchio pacchetto:

npm uninstall @anthropic-ai/claude-code

2. Installare il nuovo pacchetto:

npm install @anthropic-ai/claude-agent-sdk

3. Aggiornare i tuoi import:

Cambia 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 di 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. Disinstallare il vecchio pacchetto:

pip uninstall claude-code-sdk

2. Installare il nuovo pacchetto:

pip install claude-agent-sdk

3. Aggiornare i tuoi import:

Cambia 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:

Cambia ClaudeCodeOptions a ClaudeAgentOptions:

# Prima
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-opus-4-6"
)

# Dopo
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-opus-4-6"
)

5. Rivedi breaking changes

Apporta le modifiche al codice necessarie per completare la migrazione.

Breaking changes

Python: ClaudeCodeOptions rinominato a ClaudeAgentOptions

Cosa è cambiato: Il tipo Python SDK ClaudeCodeOptions è stato rinominato a ClaudeAgentOptions.

Migrazione:

# PRIMA (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-opus-4-6",
    permission_mode="acceptEdits"
)

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

options = ClaudeAgentOptions(
    model="claude-opus-4-6",
    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, richiedi esplicitamente il preset di Claude Code:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Oppure usa 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 puoi creare agenti con comportamento personalizzato senza ereditare le istruzioni incentrate sulla CLI di Claude Code.

Le Origini delle Impostazioni Non Vengono Più Caricate per Impostazione Predefinita

Cosa è cambiato: L'SDK non legge più le impostazioni del filesystem (CLAUDE.md, settings.json, slash commands, ecc.) per impostazione predefinita.

Migrazione:

// PRIMA (v0.0.x) - Caricava tutte le impostazioni automaticamente
const result = query({ prompt: "Hello" });
// Leggerebbe da:
// - ~/.claude/settings.json (user)
// - .claude/settings.json (project)
// - .claude/settings.local.json (local)
// - File CLAUDE.md
// - Slash commands personalizzati

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

// Oppure carica solo fonti specifiche:
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"]  // Solo impostazioni di 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 gli utenti

Perché la Ridenominazione?

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 uso di strumenti, integrazione MCP e altro ancora

Ottenere Aiuto

Se riscontri problemi durante la migrazione:

Per TypeScript/JavaScript:

1. Verifica che tutti gli import siano aggiornati 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 tutti gli import siano aggiornati 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

Passaggi Successivi

• Esplora la Panoramica di Agent SDK per conoscere le funzionalità disponibili
• Consulta il Riferimento TypeScript SDK per la documentazione dettagliata dell'API
• Rivedi il Riferimento Python SDK per la documentazione specifica di Python
• Scopri di più su Strumenti Personalizzati e Integrazione MCP