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 Claude Code SDK 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.

¿Está migrando desde el OpenAI Agents SDK? La receta de migración de OpenAI Agents SDK asigna cada primitiva al Claude Agent SDK a través de un único ejemplo trabajado.

Qué ha cambiado

Pasos de migración

Para proyectos de TypeScript/JavaScript

1. Desinstale el paquete antiguo:

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

Si @anthropic-ai/claude-code aún aparece en su package.json, reemplácelo con @anthropic-ai/claude-agent-sdk y actualice también el rango de versión, por ejemplo de "^0.0.42" a "^0.3.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 antiguo:

pip uninstall -y claude-code-sdk

Si el paquete antiguo no está instalado, pip imprime WARNING: Skipping claude-code-sdk as it is not installed. Esto es esperado y puede continuar al siguiente paso.

2. Instale el nuevo paquete:

pip install claude-agent-sdk

Si claude-code-sdk aparece en su requirements.txt o pyproject.toml, reemplácelo con 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. 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 ClaudeCodeOptions del SDK de Python 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")

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 utilice un prompt del sistema personalizado:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
# 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:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}  # Use the preset
),
):
print(message)

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


asyncio.run(main())

Predeterminado de fuentes de configuración

Este predeterminado fue brevemente cambiado en v0.1.0 para no cargar ninguna configuración del sistema de archivos y luego fue revertido, por lo que no se necesita ninguna 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 ejecutarse aislado de la configuración del sistema de archivos, pase settingSources: [], o setting_sources=[] en Python. Consulte Control filesystem settings with settingSources para ver qué carga cada fuente.

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

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