SpyBara
Go Premium

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

This page contains 36 additions and 136 deletions.

2026
Wed 9 22:58

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

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 Claude Code docs Claude Code docs → sección dedicada Agent SDK

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

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