Migrar a Claude Agent SDK

Guía para migrar los SDK de TypeScript y Python de Claude Code al Claude Agent SDK

Descripción general

El SDK de Claude Code ha sido renombrado a Claude Agent SDK y su documentación ha sido reorganizada. Este cambio refleja las capacidades más amplias del SDK para construir agentes de IA más allá de solo tareas de codificación.

Qué ha cambiado

Aspecto	Anterior	Nuevo
Nombre del paquete (TS/JS)	`@anthropic-ai/claude-code`	`@anthropic-ai/claude-agent-sdk`
Paquete de Python	`claude-code-sdk`	`claude-agent-sdk`
Ubicación de la documentación	Documentación de Claude Code	API Guide → Sección Agent SDK

Pasos de migración

Para proyectos de TypeScript/JavaScript

1. Desinstale el paquete anterior:

npm uninstall @anthropic-ai/claude-code

2. Instale el nuevo paquete:

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

3. Actualice sus importaciones:

Cambie todas las importaciones de @anthropic-ai/claude-code a @anthropic-ai/claude-agent-sdk:

// Antes
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// Después
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. Actualice las dependencias de package.json:

Si tiene el paquete listado en su package.json, actualícelo:

Antes:

{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}

Después:

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}

5. Revise cambios importantes

Realice los cambios de código necesarios para completar la migración.

Para proyectos de Python

1. Desinstale el paquete anterior:

pip uninstall claude-code-sdk

2. Instale el nuevo paquete:

pip install claude-agent-sdk

3. Actualice sus importaciones:

Cambie todas las importaciones de claude_code_sdk a claude_agent_sdk:

# Antes
from claude_code_sdk import query, ClaudeCodeOptions

# Después
from claude_agent_sdk import query, ClaudeAgentOptions

4. Actualice los nombres de tipos:

Cambie ClaudeCodeOptions a ClaudeAgentOptions:

# Antes
from claude_code_sdk import query, ClaudeCodeOptions

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

# Después
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. Revise cambios importantes

Realice los cambios de código necesarios para completar la migración.

Cambios importantes

Python: ClaudeCodeOptions renombrado a ClaudeAgentOptions

Qué cambió: El tipo de SDK de Python ClaudeCodeOptions ha sido renombrado a ClaudeAgentOptions.

Migración:

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

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

# DESPUÉS (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

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

Por qué cambió: El nombre del tipo ahora coincide con la marca "Claude Agent SDK" y proporciona consistencia en las convenciones de nomenclatura del SDK.

El prompt del sistema ya no es predeterminado

Qué cambió: El SDK ya no utiliza el prompt del sistema de Claude Code de forma predeterminada.

Migración:

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

// ANTES (v0.0.x) - Utilizaba el prompt del sistema de Claude Code de forma predeterminada
const before = query({ prompt: "Hello" });

// DESPUÉS (v0.1.0) - Utiliza un prompt del sistema mínimo de forma predeterminada
// Para obtener el comportamiento anterior, solicite explícitamente el preset de Claude Code:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// O use un prompt del sistema personalizado:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

# ANTES (v0.0.x) - Utilizaba el prompt del sistema de Claude Code de forma predeterminada
async for message in query(prompt="Hello"):
print(message)

# DESPUÉS (v0.1.0) - Utiliza un prompt del sistema mínimo de forma predeterminada
# Para obtener el comportamiento anterior, solicite explícitamente el preset de 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"}  # Utilice el preset
),
):
print(message)

# O use un prompt del sistema personalizado:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)

Por qué cambió: Proporciona mejor control y aislamiento para aplicaciones SDK. Ahora puede construir agentes con comportamiento personalizado sin heredar las instrucciones enfocadas en CLI de Claude Code.

Predeterminado de fuentes de configuración

Este predeterminado fue brevemente cambiado en v0.1.0 y luego revertido, por lo que no se requiere acción de migración.

Comportamiento actual: Omitir settingSources en query() carga la configuración del usuario, proyecto y sistema de archivos local, coincidiendo con la CLI. Esto incluye ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, archivos CLAUDE.md y comandos personalizados.

Para ejecutar aislado de la configuración del sistema de archivos, pase una matriz vacía:

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

const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // No se carga configuración del sistema de archivos
}
});

// O cargue solo fuentes específicas:
const projectOnlyResult = query({
prompt: "Hello",
options: {
settingSources: ["project"] // Solo configuración del proyecto
}
});

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]),  # No se carga configuración del sistema de archivos
):
print(message)

# O cargue solo fuentes específicas:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"]  # Solo configuración del proyecto
),
):
print(message)

El aislamiento es especialmente importante para canalizaciones CI/CD, aplicaciones implementadas, entornos de prueba y sistemas multiinquilino donde las personalizaciones locales no deben filtrarse.

¿Por qué el cambio de nombre?

El SDK de Claude Code fue diseñado originalmente para tareas de codificación, pero ha evolucionado hacia un marco poderoso para construir todo tipo de agentes de IA. El nuevo nombre "Claude Agent SDK" refleja mejor sus capacidades:

Construir agentes empresariales (asistentes legales, asesores financieros, soporte al cliente)
Crear agentes de codificación especializados (bots SRE, revisores de seguridad, agentes de revisión de código)
Desarrollar agentes personalizados para cualquier dominio con uso de herramientas, integración MCP y más

Obtener ayuda

Si encuentra algún problema durante la migración:

Para TypeScript/JavaScript:

Verifique que todas las importaciones se actualicen para usar @anthropic-ai/claude-agent-sdk
Verifique que su package.json tenga el nuevo nombre de paquete
Ejecute npm install para asegurar que las dependencias se actualicen

Para Python:

Verifique que todas las importaciones se actualicen para usar claude_agent_sdk
Verifique que su requirements.txt o pyproject.toml tenga el nuevo nombre de paquete
Ejecute pip install claude-agent-sdk para asegurar que el paquete esté instalado

Próximos pasos

Explore la Descripción general de Agent SDK para aprender sobre las características disponibles
Consulte la Referencia de SDK de TypeScript para documentación detallada de la API
Revise la Referencia de SDK de Python para documentación específica de Python
Aprenda sobre Herramientas personalizadas e Integración MCP

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

12 12

13El SDK de Claude Code ha sido renombrado a **Claude Agent SDK** y su documentación ha sido reorganizada. Este cambio refleja las capacidades más amplias del SDK para construir agentes de IA más allá de solo tareas de codificación.13El SDK de Claude Code ha sido renombrado a **Claude Agent SDK** y su documentación ha sido reorganizada. Este cambio refleja las capacidades más amplias del SDK para construir agentes de IA más allá de solo tareas de codificación.

14 14

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

16 Qué ha cambiado16 Qué ha cambiado

17</h2>17</h2>

18 18

82}82}

83```83```

84 84

~~85¡Eso es todo! No se requieren otros cambios de código.~~85**5. Revise [cambios importantes](#breaking-changes)**

87Realice los cambios de código necesarios para completar la migración.

86 88

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

88 Para proyectos de Python90 Para proyectos de 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 // ANTES (v0.0.x) - Utilizaba el prompt del sistema de Claude Code de forma predeterminada179 // ANTES (v0.0.x) - Utilizaba el prompt del sistema de Claude Code de forma predeterminada

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

177 181

178 // DESPUÉS (v0.1.0) - Utiliza un prompt del sistema mínimo de forma predeterminada182 // DESPUÉS (v0.1.0) - Utiliza un prompt del sistema mínimo de forma predeterminada

179 // Para obtener el comportamiento anterior, solicite explícitamente el preset de Claude Code:183 // Para obtener el comportamiento anterior, solicite explícitamente el preset de 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 // O use un prompt del sistema personalizado:191 // O use un prompt del sistema personalizado:

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: [] // No se carga configuración del sistema de archivos245 settingSources: [] // No se carga configuración del sistema de archivos

241 });247 });

242 248

243 // O cargue solo fuentes específicas:249 // O cargue solo fuentes específicas:

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

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

246 options: {252 options: {

247 settingSources: ["project"] // Solo configuración del proyecto253 settingSources: ["project"] // Solo configuración del proyecto

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

Migrar a Claude Agent SDK

Descripción general

Qué ha cambiado

Pasos de migración

Para proyectos de TypeScript/JavaScript

Para proyectos de Python

Cambios importantes

Python: ClaudeCodeOptions renombrado a ClaudeAgentOptions

El prompt del sistema ya no es predeterminado

Predeterminado de fuentes de configuración

¿Por qué el cambio de nombre?

Obtener ayuda

Próximos pasos