Migrar a 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

Pasos de migración

Para proyectos de TypeScript/JavaScript

1. Desinstala el paquete anterior:

npm uninstall @anthropic-ai/claude-code

2. Instala el nuevo paquete:

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

3. Actualiza tus importaciones:

Cambia 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. Actualiza las dependencias de package.json:

Si tienes el paquete listado en tu package.json, actualízalo:

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

// Después
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
  }
}

¡Eso es todo! No se requieren otros cambios de código.

Para proyectos de Python

1. Desinstala el paquete anterior:

pip uninstall claude-code-sdk

2. Instala el nuevo paquete:

pip install claude-agent-sdk

3. Actualiza tus importaciones:

Cambia 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. Actualiza los nombres de tipos:

Cambia ClaudeCodeOptions a ClaudeAgentOptions:

# Antes
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5"
)

# Después
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5"
)

5. Revisa cambios importantes

Realiza 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 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5",
    permission_mode="acceptEdits"
)

# DESPUÉS (v0.1.0)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    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 mensaje del sistema ya no es predeterminado

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

Migración:

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

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

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

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

Las fuentes de configuración ya no se cargan de forma predeterminada

Qué cambió: El SDK ya no lee la configuración del sistema de archivos (CLAUDE.md, settings.json, comandos de barra, etc.) de forma predeterminada.

Migración:

// ANTES (v0.0.x) - Cargaba toda la configuración automáticamente
const result = query({ prompt: "Hello" });
// Leería desde:
// - ~/.claude/settings.json (usuario)
// - .claude/settings.json (proyecto)
// - .claude/settings.local.json (local)
// - Archivos CLAUDE.md
// - Comandos de barra personalizados

// DESPUÉS (v0.1.0) - No se carga configuración de forma predeterminada
// Para obtener el comportamiento anterior:
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["user", "project", "local"]
  }
});

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

Por qué cambió: Garantiza que las aplicaciones SDK tengan un comportamiento predecible independiente de las configuraciones del sistema de archivos local. Esto es especialmente importante para:

• Entornos CI/CD - Comportamiento consistente sin personalizaciones locales
• Aplicaciones implementadas - Sin dependencia de la configuración del sistema de archivos
• Pruebas - Entornos de prueba aislados
• Sistemas multiusuario - Prevenir fugas de configuración entre usuarios

¿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 encuentras problemas durante la migración:

Para TypeScript/JavaScript:

1. Verifica que todas las importaciones se actualicen para usar @anthropic-ai/claude-agent-sdk
2. Verifica que tu package.json tenga el nuevo nombre de paquete
3. Ejecuta npm install para asegurar que las dependencias se actualicen

Para Python:

1. Verifica que todas las importaciones se actualicen para usar claude_agent_sdk
2. Verifica que tu requirements.txt o pyproject.toml tenga el nuevo nombre de paquete
3. Ejecuta pip install claude-agent-sdk para asegurar que el paquete esté instalado

Próximos pasos

• Explora la Descripción general de Agent SDK para aprender sobre las características disponibles
• Consulta la Referencia del SDK de TypeScript para documentación detallada de la API
• Revisa la Referencia del SDK de Python para documentación específica de Python
• Aprende sobre Herramientas personalizadas e Integración MCP