SpyBara
Go Premium

agent-sdk/migration-guide.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 49 additions and 149 deletions.

2026
Wed 9 22:58

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.

State migrando da OpenAI Agents SDK? La ricetta di migrazione da OpenAI Agents SDK mappa ogni primitiva su Claude Agent SDK attraverso un singolo esempio pratico.

Cosa è Cambiato

Aspetto Precedente Nuovo
Nome Pacchetto (TS/JS) @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk
Pacchetto Python claude-code-sdk claude-agent-sdk
Posizione Documentazione Claude Code docs Claude Code docs → sezione dedicata Agent SDK

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 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 package.json:

Se @anthropic-ai/claude-code è ancora elencato nel vostro package.json, sostituirlo con @anthropic-ai/claude-agent-sdk e aggiornare anche l'intervallo di versione, ad esempio da "^0.0.42" a "^0.3.0".

5. Consultare le modifiche di rilievo

Apportare le modifiche al codice necessarie per completare la migrazione.

Per progetti Python

1. Disinstallare il vecchio pacchetto:

pip uninstall -y claude-code-sdk

Se il vecchio pacchetto non è installato, pip stampa WARNING: Skipping claude-code-sdk as it is not installed. Questo è previsto e potete continuare al passaggio successivo.

2. Installare il nuovo pacchetto:

pip install claude-agent-sdk

Se claude-code-sdk è elencato nel vostro requirements.txt o pyproject.toml, sostituirlo con 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. Consultare le modifiche di rilievo

Apportare le modifiche al codice necessarie per completare la migrazione.

Modifiche di rilievo

Python: ClaudeCodeOptions rinominato in ClaudeAgentOptions

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

Migrazione:

# BEFORE (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions

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

# AFTER (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

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

// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
const before = query({ prompt: "Hello" });

// AFTER (v0.1.0) - Uses minimal system prompt by default
// To get the old behavior, explicitly request Claude Code's preset:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Or use a custom system prompt:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

Impostazioni predefinite delle origini

Questa impostazione predefinita è stata brevemente modificata in v0.1.0 per non caricare alcuna impostazione del file system e successivamente ripristinata, quindi non è necessaria alcuna azione di migrazione.

Comportamento attuale: Omettendo settingSources su query() vengono caricate le impostazioni del file system dell'utente, del progetto e locale, corrispondendo alla CLI. Ciò 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 settingSources: [], oppure setting_sources=[] in Python. Vedere Control filesystem settings with settingSources per informazioni su cosa carica ogni origine.

L'isolamento è particolarmente importante per le pipeline CI/CD, le applicazioni distribuite, gli ambienti di test e i sistemi multi-tenant in cui le personalizzazioni locali non dovrebbero trapelare.

Passaggi successivi