Guía de migración

Migración a Claude 4.6

Claude Opus 4.6 es un reemplazo casi directo para Claude 4.5, con algunos cambios importantes a tener en cuenta. Para una lista completa de nuevas características, consulta Novedades en Claude 4.6.

Actualiza el nombre de tu modelo

# Migración de Opus
model = "claude-opus-4-5"  # Antes
model = "claude-opus-4-6"  # Después

Cambios importantes

Eliminación de prefill: Rellenar previamente mensajes del asistente devuelve un error 400 en modelos Claude 4.6. Usa salidas estructuradas, instrucciones de indicación del sistema, u output_config.format en su lugar.
Entrecomillado de parámetros de herramientas: Los modelos Claude 4.6 pueden producir un escape JSON ligeramente diferente en argumentos de llamadas de herramientas (por ejemplo, manejo diferente de escapes Unicode o escape de barras inclinadas). Si analizas la input de llamadas de herramientas como una cadena sin procesar en lugar de usar un analizador JSON, verifica tu lógica de análisis. Los analizadores JSON estándar (como json.loads() o JSON.parse()) manejan estas diferencias automáticamente.

Cambios recomendados

Estos no son obligatorios pero mejorarán tu experiencia:

Migra al pensamiento adaptativo: thinking: {type: "enabled", budget_tokens: N} está deprecado en modelos Claude 4.6 y se eliminará en una versión futura del modelo. Cambia a thinking: {type: "adaptive"} y usa el parámetro effort para controlar la profundidad del pensamiento. Consulta Pensamiento adaptativo.

Migración de Claude 4.1 o anterior a Claude 4.6

Si estás migrando de Opus 4.1, Sonnet 4, o modelos anteriores directamente a Claude 4.6, aplica los cambios importantes de Claude 4.6 anteriores más los cambios adicionales en esta sección.

# De Opus 4.1
model = "claude-opus-4-1-20250805"  # Antes
model = "claude-opus-4-6"  # Después

# De Sonnet 4
model = "claude-sonnet-4-20250514"  # Antes
model = "claude-opus-4-6"  # Después

# De Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Antes
model = "claude-opus-4-6"  # Después

Cambios importantes adicionales

Actualiza parámetros de muestreo

Este es un cambio importante al migrar desde modelos Claude 3.x.

Usa solo temperature O top_p, no ambos:

# Antes - Esto generará un error en modelos Claude 4+
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # No puedes usar ambos
    # ...
)

# Después
response = client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,  # Usa temperature O top_p, no ambos
    # ...
)

Cambios recomendados adicionales

Elimina encabezados beta heredados: Elimina token-efficient-tools-2025-02-19 y output-128k-2025-02-19. Todos los modelos Claude 4+ tienen uso de herramientas eficiente en tokens integrado y estos encabezados no tienen efecto.

Lista de verificación de migración de Claude 4.6

Actualiza el ID del modelo a claude-opus-4-6
IMPORTANTE: Elimina prefills de mensajes del asistente (devuelve error 400); usa salidas estructuradas u output_config.format en su lugar
Recomendado: Migra de thinking: {type: "enabled", budget_tokens: N} a thinking: {type: "adaptive"} con el parámetro effort (budget_tokens está deprecado y se eliminará en una versión futura)
Verifica que el análisis JSON de llamadas de herramientas use un analizador JSON estándar
Elimina el encabezado beta effort-2025-11-24 (effort ahora es GA)
Elimina el encabezado beta fine-grained-tool-streaming-2025-05-14

Migración a Claude Sonnet 4.6

Claude Sonnet 4.6 combina una inteligencia sólida con un rendimiento rápido, con capacidades mejoradas de búsqueda agéntica y ejecución de código gratuita cuando se usa con búsqueda web o búsqueda web. Es ideal para tareas cotidianas de codificación, análisis y contenido.

Para una descripción general completa de las capacidades, consulta la descripción general de modelos.

El precio de Sonnet 4.6 es de $3 por millón de tokens de entrada, $15 por millón de tokens de salida. Consulta Precios de Claude para obtener detalles.

Actualiza el nombre de tu modelo:

# De Sonnet 4.5
model = "claude-sonnet-4-5"  # Antes
model = "claude-sonnet-4-6"  # Después

# De Sonnet 4
model = "claude-sonnet-4-20250514"  # Antes
model = "claude-sonnet-4-6"  # Después

Cambios importantes

Al migrar de Sonnet 4.5

Ya no se admite rellenar previamente mensajes del asistente

Este es un cambio importante al migrar desde Sonnet 4.5 o anterior.

Rellenar previamente mensajes del asistente devuelve un error 400 en Sonnet 4.6. Usa salidas estructuradas, instrucciones de indicación del sistema, u output_config.format en su lugar.

Casos de uso comunes de prefill y migraciones:
- Controlar el formato de salida (forzar salida JSON/YAML): Usa salidas estructuradas o herramientas con campos enum para tareas de clasificación.
- Eliminar preámbulos (eliminar frases "Aquí está..."): Agrega instrucciones directas en la indicación del sistema: "Responde directamente sin preámbulo. No comiences con frases como 'Aquí está...', 'Basado en...', etc."
- Evitar rechazos malos: Claude es mucho mejor en rechazos apropiados ahora. Las indicaciones claras en el mensaje del usuario sin prefill deberían ser suficientes.

Al migrar de Claude 3.x

Actualiza parámetros de muestreo

Este es un cambio importante al migrar desde modelos Claude 3.x.

Usa solo temperature O top_p, no ambos.
Actualiza versiones de herramientas

Este es un cambio importante al migrar desde modelos Claude 3.x.

Actualiza a las últimas versiones de herramientas (text_editor_20250728, code_execution_20250825). Elimina cualquier código que use el comando undo_edit.
Maneja la razón de parada refusal

Actualiza tu aplicación para manejar razones de parada refusal.

Cambios recomendados

Elimina el encabezado beta fine-grained-tool-streaming-2025-05-14 — La transmisión de herramientas de grano fino ahora es GA en Sonnet 4.6 y ya no requiere un encabezado beta.
Migra output_format a output_config.format — El parámetro output_format está deprecado. Usa output_config.format en su lugar.

Migración de Sonnet 4.5

Te recomendamos encarecidamente migrar de Sonnet 4.5 a Sonnet 4.6, que ofrece más inteligencia al mismo precio.

Sonnet 4.6 tiene un nivel de effort predeterminado de high, en contraste con Sonnet 4.5 que no tenía parámetro de effort. Te recomendamos ajustar el parámetro effort mientras migras de Sonnet 4.5 a Sonnet 4.6. Si no se establece explícitamente, puedes experimentar una latencia más alta con el nivel de effort predeterminado.

Si no estás usando pensamiento extendido

Si no estás usando pensamiento extendido en Sonnet 4.5, puedes continuar sin él en Sonnet 4.6. Debes establecer explícitamente el effort al nivel apropiado para tu caso de uso. Con effort low y pensamiento deshabilitado, puedes esperar un rendimiento similar o mejor en relación con Sonnet 4.5 sin pensamiento extendido.

Si estás usando pensamiento extendido

Si estás usando pensamiento extendido en Sonnet 4.5, continúa siendo soportado en Sonnet 4.6 sin cambios necesarios en tu configuración de pensamiento. Te recomendamos mantener un presupuesto de pensamiento alrededor de 16k tokens. En la práctica, la mayoría de las tareas no usan tanto, pero proporciona espacio para problemas más difíciles sin riesgo de uso descontrolado de tokens.

Casos de uso de codificación y agénticos

Para codificación agéntica, diseño frontend, flujos de trabajo con muchas herramientas y flujos de trabajo empresariales complejos, te recomendamos comenzar con effort medium. Si encuentras que la latencia es demasiado alta, considera reducir el effort a low. Si necesitas una inteligencia más alta, considera aumentar el effort a high o migrar a Opus 4.6.

Casos de uso de chat y no codificación

Para chat, generación de contenido, búsqueda, clasificación y otras tareas no codificadas, te recomendamos comenzar con effort low con pensamiento extendido. Si necesitas más profundidad, aumenta el effort a medium.

Cuándo probar pensamiento adaptativo

Las rutas de migración anteriores usan pensamiento extendido con budget_tokens para uso de tokens predecible. Si tu carga de trabajo se ajusta a uno de los siguientes patrones, considera probar pensamiento adaptativo en su lugar:

Agentes autónomos de múltiples pasos: agentes de codificación que convierten requisitos en software funcional, canalizaciones de análisis de datos y búsqueda de errores donde el modelo se ejecuta independientemente en muchos pasos. El pensamiento adaptativo permite que el modelo calibre su razonamiento por paso, manteniéndose en el camino en trayectorias más largas. Para estas cargas de trabajo, comienza con effort high. Si la latencia o el uso de tokens es una preocupación, reduce a medium.
Agentes de uso de computadora: Sonnet 4.6 logró la mejor precisión en su clase en evaluaciones de uso de computadora usando modo adaptativo.
Cargas de trabajo bimodales: una mezcla de tareas fáciles y difíciles donde adaptativo omite el pensamiento en consultas simples y razona profundamente en las complejas.

Cuando uses pensamiento adaptativo, evalúa effort medium y high en tus tareas. El nivel correcto depende del equilibrio de tu carga de trabajo entre calidad, latencia y uso de tokens.

Si ves comportamiento inconsistente o regresiones de calidad con pensamiento adaptativo, cambia a pensamiento extendido con budget_tokens. Esto proporciona resultados más predecibles con un límite en los costos de pensamiento.

Lista de verificación de migración de Sonnet 4.6

Actualiza el ID del modelo a claude-sonnet-4-6
IMPORTANTE: Elimina el relleno previo de mensajes del asistente; usa salidas estructuradas u output_config.format en su lugar
IMPORTANTE: Verifica que el análisis JSON de parámetros de herramientas maneje diferencias de escape
IMPORTANTE: Actualiza versiones de herramientas a las últimas (text_editor_20250728, code_execution_20250825); las versiones heredadas no son compatibles (si estás migrando desde 3.x)
IMPORTANTE: Elimina cualquier código que use el comando undo_edit (si aplica)
IMPORTANTE: Actualiza parámetros de muestreo para usar solo temperature O top_p, no ambos (si estás migrando desde 3.x)

Migración a Claude Sonnet 4.5

Claude Sonnet 4.5 combina una inteligencia sólida con un rendimiento rápido, lo que lo hace ideal para tareas cotidianas de codificación, análisis y contenido.

Para una descripción general completa de las capacidades, consulta la descripción general de modelos.

El precio de Sonnet 4.5 es de $3 por millón de tokens de entrada, $15 por millón de tokens de salida. Consulta Precios de Claude para obtener detalles.

Actualiza el nombre de tu modelo:

# De Sonnet 4
model = "claude-sonnet-4-20250514"  # Antes
model = "claude-sonnet-4-5-20250929"  # Después

# De Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Antes
model = "claude-sonnet-4-5-20250929"  # Después

Cambios importantes

Estos cambios importantes se aplican al migrar desde modelos Claude 3.x Sonnet.

Actualiza parámetros de muestreo

Este es un cambio importante al migrar desde modelos Claude 3.x.

Usa solo temperature O top_p, no ambos.
Actualiza versiones de herramientas

Este es un cambio importante al migrar desde modelos Claude 3.x.

Actualiza a las últimas versiones de herramientas (text_editor_20250728, code_execution_20250825). Elimina cualquier código que use el comando undo_edit.
Maneja la razón de parada refusal

Actualiza tu aplicación para manejar razones de parada refusal.

Lista de verificación de migración de Sonnet 4.5

Actualiza el ID del modelo a claude-sonnet-4-5-20250929
IMPORTANTE: Actualiza versiones de herramientas a las últimas (text_editor_20250728, code_execution_20250825); las versiones heredadas no son compatibles (si estás migrando desde 3.x)
IMPORTANTE: Elimina cualquier código que use el comando undo_edit (si aplica)
IMPORTANTE: Actualiza parámetros de muestreo para usar solo temperature O top_p, no ambos (si estás migrando desde 3.x)
Maneja la nueva razón de parada refusal en tu aplicación
Revisa y actualiza indicaciones siguiendo mejores prácticas de indicaciones

Migración a Claude Haiku 4.5

Claude Haiku 4.5 es el modelo Haiku más rápido e inteligente con rendimiento casi de frontera, ofreciendo calidad de modelo premium para aplicaciones interactivas y procesamiento de alto volumen.

Para una descripción general completa de las capacidades, consulta la descripción general de modelos.

El precio de Haiku 4.5 es de $1 por millón de tokens de entrada, $5 por millón de tokens de salida. Consulta Precios de Claude para obtener detalles.

Actualiza el nombre de tu modelo:

# De Haiku 3.5
model = "claude-3-5-haiku-20241022"  # Antes
model = "claude-haiku-4-5-20251001"  # Después

Revisa los nuevos límites de velocidad: Haiku 4.5 tiene límites de velocidad separados de Haiku 3.5. Consulta Documentación de límites de velocidad para obtener detalles.

Para mejoras significativas de rendimiento en tareas de codificación y razonamiento, considera habilitar pensamiento extendido con thinking: {type: "enabled", budget_tokens: N}.

El pensamiento extendido impacta la eficiencia del almacenamiento en caché de indicaciones.

El pensamiento extendido está deprecado en modelos Claude 4.6 o más nuevos. Si usas modelos más nuevos, usa pensamiento adaptativo en su lugar.

Explora nuevas capacidades: Consulta la descripción general de modelos para obtener detalles sobre conciencia de contexto, capacidad de salida aumentada (64K tokens), inteligencia más alta y velocidad mejorada.

Cambios importantes

Estos cambios importantes se aplican al migrar desde modelos Claude 3.x Haiku.

Actualiza parámetros de muestreo

Este es un cambio importante al migrar desde modelos Claude 3.x.

Usa solo temperature O top_p, no ambos.
Actualiza versiones de herramientas

Este es un cambio importante al migrar desde modelos Claude 3.x.

Actualiza a las últimas versiones de herramientas (text_editor_20250728, code_execution_20250825). Elimina cualquier código que use el comando undo_edit.
Maneja la razón de parada refusal

Actualiza tu aplicación para manejar razones de parada refusal.

Lista de verificación de migración de Haiku 4.5

Actualiza el ID del modelo a claude-haiku-4-5-20251001
IMPORTANTE: Actualiza versiones de herramientas a las últimas (text_editor_20250728, code_execution_20250825); las versiones heredadas no son compatibles
IMPORTANTE: Elimina cualquier código que use el comando undo_edit (si aplica)
IMPORTANTE: Actualiza parámetros de muestreo para usar solo temperature O top_p, no ambos
Maneja la nueva razón de parada refusal en tu aplicación
Revisa y ajusta para nuevos límites de velocidad (separados de Haiku 3.5)
Revisa y actualiza indicaciones siguiendo

¿Necesitas ayuda?

Consulta la documentación de API para especificaciones detalladas
Revisa capacidades de modelos para comparaciones de rendimiento
Revisa notas de lanzamiento de API para actualizaciones de API
Contacta con soporte si encuentras algún problema durante la migración

response = client.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[...],
)

Actualiza versiones de herramientas

Este es un cambio importante al migrar desde modelos Claude 3.x.

Actualiza a las últimas versiones de herramientas. Elimina cualquier código que use el comando undo_edit.

# Antes
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# Después
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

Editor de texto: Usa text_editor_20250728 y str_replace_based_edit_tool. Consulta Documentación de la herramienta editor de texto para obtener detalles.
Ejecución de código: Actualiza a code_execution_20250825. Consulta Documentación de la herramienta de ejecución de código para obtener instrucciones de migración.

Maneja la razón de parada refusal

Actualiza tu aplicación para manejar razones de parada refusal:

response = client.messages.create(...)

if response.stop_reason == "refusal":
    # Maneja el rechazo apropiadamente
    pass

Maneja la razón de parada model_context_window_exceeded

Los modelos Claude 4.5+ devuelven una razón de parada model_context_window_exceeded cuando la generación se detiene debido a alcanzar el límite de la ventana de contexto, en lugar del límite max_tokens solicitado. Actualiza tu aplicación para manejar esta nueva razón de parada:

response = client.messages.create(...)

if response.stop_reason == "model_context_window_exceeded":
    # Maneja el límite de la ventana de contexto apropiadamente
    pass

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "medium"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "low"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)