El SDK se mudó, el nombre se quedó

El rename toca el nombre del paquete, la ruta de import y (en Python) el nombre de una clase. Mapea tu línea vieja a la nueva y la mayor parte de tu código sigue funcionando.

Versiones actuales al escribir: @anthropic-ai/claude-agent-sdk está en 0.3.x, claude-agent-sdk en PyPI en 0.2.x. Los paquetes viejos congelados están en claude-code-sdk 0.0.25 (Python) y @anthropic-ai/claude-code es ahora el CLI en 2.1.x.

El SDK se mudó de @anthropic-ai/claude-code, pero ese nombre de paquete se quedó vivo como la herramienta CLI, así que la instalación funciona y la import falla. Ese desajuste es la mayor fuente de confusión de esta migración, así que vale la pena ser preciso sobre quién es dueño de cada nombre ahora.

Así que npm install @anthropic-ai/claude-code no falla. Instala el CLI. Después tu import { query } from "@anthropic-ai/claude-code" falla porque ese paquete ya no exporta símbolos del SDK. El mensaje de error apunta a la import, pero el problema real es el paquete que instalaste.

El rename refleja alcance. El SDK arrancó como un helper de código y creció hasta un framework general para construir agentes — bots de soporte, agentes de revisión, asistentes de finanzas — así que "Agent SDK" lo describe mejor que "Code SDK".

Cada mensaje de abajo mapea a una causa raíz: estás apuntando a un nombre viejo. Encuentra tu mensaje exacto, aplica el arreglo.

La mayoría colapsan al mismo movimiento: apuntar la instalación y la import al nuevo nombre de paquete. Los últimos dos no son problemas de rename de import — uno es un desajuste de intérprete, el otro un default de comportamiento — y son los que sobreviven después de que el build está verde.

Desinstala el paquete viejo, instala el nuevo y reescribe la cadena de import. Los nombres de símbolos (query, tool, createSdkMcpServer) no cambiaron, así que la import es la única edición en la mayoría de los archivos.

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

Actualiza cada import

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

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

Si fijaste la dependencia, actualiza también la clave

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

Desinstala claude-code-sdk, instala claude-agent-sdk, luego cambia el módulo de import y el nombre de la clase de opciones. Los argumentos del constructor son idénticos, así que model, permission_mode y similares pasan sin cambios.

pip uninstall claude-code-sdk
pip install claude-agent-sdk

Reescribe la import y la clase

# Antes
from claude_code_sdk import query, ClaudeCodeOptions

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

# Después
from claude_agent_sdk import query, ClaudeAgentOptions

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

python -c "import sys; print(sys.version)"
python -c "import claude_agent_sdk; print(claude_agent_sdk.__file__)"

El system prompt por defecto se fue en v0.1.0 y posteriores, así que tu agente se comporta distinto incluso después de que las imports compilan. Es el único cambio que arregla tu build pero altera el comportamiento en silencio, así que muerde a la gente una semana después de que la migración parece lista.

Las versiones viejas del SDK inyectaban automáticamente el system prompt enfocado en CLI de Claude Code. Desde v0.1.0 el SDK trae un default mínimo. Para restaurar el comportamiento viejo, activa el preset:

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

// Restaura el comportamiento viejo de Claude Code:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions

# Restaura el comportamiento viejo de Claude Code:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    print(message)

O pasa una cadena plana (systemPrompt: "You are a helpful coding assistant" en TS, system_prompt="..." en Python) para definir la tuya. Para agentes desplegados este es el mejor default, ya que normalmente no quieres instrucciones con sabor a CLI filtrándose en un bot de soporte.

Si tu agente depende de definiciones de tools, el cambio de prompt puede alterar cómo se seleccionan las tools.

Aplica el arreglo del rename cuando tu error sea un módulo faltante, un export faltante o una clase renombrada. Salta a otro arreglo cuando el síntoma sea uno de estos.

El Claude Agent SDK es la herramienta correcta cuando quieres el harness nativo de Anthropic. Cuando quieres hacer A/B entre proveedores sin reescribir el código del cliente, el SDK es la capa equivocada — un gateway compatible con OpenAI es la correcta.

Un gateway compatible con OpenAI expone una base URL y una key para muchos modelos, así que puedes correr el mismo bucle de tool-use contra Claude, GPT, Gemini o el modelo que elijas, y cambiar de modelo con un solo cambio de cadena en vez de re-plumear SDKs:

from openai import OpenAI

# apunta a cualquier gateway compatible con OpenAI que elijas
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://your-gateway.example/v1")
resp = client.chat.completions.create(
    model="anthropic/claude-opus-4.8",   # cambia esta cadena para cambiar de modelo
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Esto no reemplaza al Agent SDK — se senta a su lado. Usa el harness nativo cuando quieres las features de agente integradas de Anthropic, soporte MCP y el preset claude_code. Usa un gateway cuando la portabilidad entre proveedores es el objetivo. Los dos no compiten; responden a preguntas distintas, y tus controles de seguridad y config se mantengan sin importar por cuál enrutes.

Las opciones honestas, en orden de cuándo es cada una la llamada correcta.

La mayoría de equipos debería aterrizar en la primera o la segunda. El paquete congelado es un parche temporal, no un destino — una dependencia que ya no recibe arreglos es un pasivo desde el momento en que está en un camino de producción.

El arreglo de arriba es una línea. La lección es que el nombre viejo aún instala algo, y eso es un fallo de diseño que puedes diseñar alrededor.

Puedes leer este break de dos formas. La estrecha: actualiza el nombre del paquete, actualiza la import, sigue. La útil: una dependencia cuyo nombre viejo aún resuelve a una instalación que funciona — solo que a la cosa equivocada — es una clase de fallo que te costará una tarde entera la primera vez que la pegues a ciegas.

Vemos esto en casi todo stack de IA que auditamos: un equipo fija un paquete por nombre, el vendor lo divide o renombra, y la instalación sigue funcionando contra un nombre que ya no significa lo que ellos creen. El rename de Claude Code → Agent SDK es una instancia limpia y documentada. El próximo puede que no traiga guía de migración.

Cuando el nombre viejo aún instala algo, el rename no está hecho hasta que tu comportamiento lo está — no tu build.