Migrar a Claude Sonnet 5.5

Esta guía enumera los cambios de código necesarios para pasar a Claude Sonnet 5.5 desde Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet o Claude Haiku 4.5. Lee las dos primeras secciones y luego sigue leyendo hasta llegar a la sección de tu modelo actual. La lista de verificación de migración enumera cada cambio según el modelo de partida.

Claude Sonnet 5.5 tiene los mismos precios que Claude Sonnet 5. Consulta Precios de Claude. Para conocer su "context window" (ventana de contexto) y sus límites de salida, consulta la página del modelo Claude Sonnet 5.5. Para conocer las funciones y el prompting, consulta Novedades de Claude Sonnet 5.5 y Prompting para Claude Sonnet 5.5.

Envía una solicitud a Claude Sonnet 5.5

Esta solicitud funciona en Claude Sonnet 5.5 tal como está escrita. Establece un nivel de "effort" (esfuerzo), y las pestañas de los SDK leen la respuesta por tipo de bloque. Omite cinco configuraciones que devuelven un error 400: presupuestos de pensamiento, parámetros de muestreo, prefill del asistente, elección forzada de herramienta y thinking: {"type": "disabled"}.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

print(f"Stop reason: {response.stop_reason}")
for block in response.content:
    if block.type == "text":
        print(block.text)

El pensamiento se ejecuta de forma predeterminada

En Claude Sonnet 5.5, una solicitud sin campo thinking se ejecuta con "adaptive thinking" (pensamiento adaptativo), al igual que thinking: {"type": "adaptive"}. En Claude Sonnet 4.6 y modelos anteriores, y en Claude Haiku 4.5, esa solicitud se ejecutaba sin pensamiento. Para seguir ejecutando sin pensamiento inicial, consulta Desactiva el pensamiento inicial.

Gestiona el pensamiento en las respuestas

El código que se ejecutaba sin pensamiento necesita los tres elementos. El código que proviene de Claude Sonnet 5 probablemente ya tiene los dos primeros.

• Lee los bloques de contenido por type. Una respuesta puede comenzar con bloques thinking, por lo que el código que lee content[0].text falla.
• Devuelve los bloques thinking sin cambios en los bucles de "tool use" (uso de herramientas), incluidos los vacíos. Consulta Preservar bloques de pensamiento.
• Revisa max_tokens. Cubre el pensamiento más el texto, y los tokens de pensamiento se facturan como tokens de salida. Consulta Control de costos.

El texto del pensamiento se omite de forma predeterminada. Los bloques thinking llegan con un campo thinking vacío y una signature. Para obtener resúmenes legibles, establece display: "summarized", el valor predeterminado en Claude Sonnet 4.6 y modelos anteriores, y en Claude Haiku 4.5. Consulta Controlar la visualización del pensamiento.

Desactiva el pensamiento inicial

Para desactivar el pensamiento inicial en Claude Sonnet 5.5, envía thinking: {"type": "between_tools"}. Es la configuración de pensamiento más baja. Sus actualizaciones de progreso entre llamadas a herramientas siguen llegando como bloques thinking con su texto de resumen. Sin herramientas, la respuesta contiene solo texto. Claude Sonnet 5, en cambio, desactiva el pensamiento con thinking: {"type": "disabled"}, y los modelos anteriores se ejecutan sin pensamiento de forma predeterminada. En Claude Sonnet 5.5, disabled devuelve un error 400 invalid_request_error:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

between_tools funciona en todas las plataformas que ofrecen Claude Sonnet 5.5, sin encabezado beta. Se acepta con esfuerzo low, medium y high. Con xhigh o max, devuelve un error 400. Para ejecutar en esos niveles, usa pensamiento adaptativo: omite el campo thinking o envía thinking: {"type": "adaptive"}. between_tools no admite ningún otro campo: display, budget_tokens o block_binding enviados junto con él devuelven un error 400. Con el "server-side fallback" (respaldo del lado del servidor), una solicitud between_tools que recurre a Claude Sonnet 5 se ejecuta allí con thinking: {"type": "disabled"}.

Con between_tools, el esfuerzo no puede cambiar a mitad de la conversación: un output_config.effort por mensaje que difiera del nivel vigente devuelve un error 400. Para variar el esfuerzo en cada turno, usa pensamiento adaptativo. Para obtener orientación sobre prompting, consulta Ejecutar sin pensamiento inicial.

En las versiones del SDK que no definen between_tools, los ejemplos de Python y TypeScript fallan en la verificación de tipos. Actualiza el SDK o pasa el valor como JSON sin procesar, como hacen los ejemplos de C#, Go y Java.

Antes (Claude Sonnet 5):

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

Después (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

Lista de verificación de migración por modelo de partida

Recorre los grupos en orden y detente después del que nombra tu modelo. En Claude Haiku 4.5, aplica todos los grupos excepto "Claude Sonnet 4 o anterior", y termina con "Solo Claude Haiku 4.5".

Todos los modelos de partida

• Cambia el ID del modelo a claude-sonnet-5-5.
• Lee los bloques de contenido por type y devuelve los bloques thinking sin cambios.
• Para seguir ejecutando sin pensamiento inicial, envía la configuración de pensamiento más baja con esfuerzo high o inferior.
• Reemplaza el uso forzado de herramientas por auto y herramientas estrictas, o por auto solo en Amazon Bedrock.
• Mantén las conversaciones solo de anexado.
• En la API de Claude y Google Cloud, migra el uso de computadora al toolset, sin el encabezado beta fine-grained-tool-streaming-2025-05-14.
• Combina la herramienta advisor con un asesor compatible y espera consejos cifrados.
• Lee el texto entre llamadas a herramientas desde los bloques thinking.
• Maneja los rechazos y configura el fallback.
• Vuelve a ejecutar tu barrido de esfuerzo y restablece la línea base de costos.

Claude Sonnet 4.6 o anterior

• Espera pensamiento en las solicitudes sin campo thinking y revisa max_tokens.
• Reemplaza los presupuestos de pensamiento por un nivel de esfuerzo.
• Elimina los valores no predeterminados de temperature, top_p y top_k.
• Si muestras el texto del pensamiento, establece display: "summarized".
• Vuelve a contar los tokens y vuelve a presupuestar los tokens de imagen.

Claude Sonnet 4.5 o anterior

• Reemplaza los prefills del asistente.
• Analiza la entrada de las llamadas a herramientas con un analizador JSON estándar.
• En Amazon Bedrock, migra el uso de computadora de computer_20250124 a computer_20251124.
• Establece output_config.effort explícitamente.
• Elimina cualquier encabezado beta de ventana de contexto.
• Elimina interleaved-thinking-2025-05-14 y reemplaza fine-grained-tool-streaming-2025-05-14 por eager_input_streaming.
• Mueve output_format a output_config.format.

Claude Sonnet 4 o anterior

• Actualiza las versiones de herramientas a text_editor_20250728 y code_execution_20260521.
• Gestiona los motivos de detención refusal y model_context_window_exceeded.
• Revisa los parámetros de cadena de las herramientas en busca de saltos de línea finales.
• Elimina token-efficient-tools-2025-02-19 y output-128k-2025-02-19.
• Revisa tus prompts.

Solo Claude Haiku 4.5

• Reemplaza claude-haiku-4-5-20251001 o su alias.
• Restablece la línea base de costos con el precio por token más alto.
• Revisa los prompts que eran demasiado cortos para almacenarse en caché en Claude Haiku 4.5.

Migrar a Claude Sonnet 5.5 desde Claude Sonnet 5

Todos los modelos de partida necesitan los cambios de esta sección. Reemplaza tu ID de modelo por claude-sonnet-5-5, que no tiene sufijo de fecha. En otras plataformas, usa el ID indicado en Disponibilidad.

El uso forzado de herramientas no es compatible

Todos los modelos anteriores de esta página aceptan un tool_choice de tipo any o tool. Claude Sonnet 5.5 rechaza ambos con un error 400, incluso en el endpoint de conteo de tokens:

tool_choice: type "tool" and "any" are not supported for this model.

Envía tool_choice: {"type": "auto"} y marca la herramienta con strict: true para que su entrada coincida con el esquema. El modelo puede entonces responder sin llamar a la herramienta, así que indica en el prompt cuándo usarla. El uso estricto de herramientas admite un subconjunto de JSON Schema y requiere additionalProperties: false en cada objeto. Consulta Limitaciones de JSON Schema. En Amazon Bedrock, las salidas estructuradas, que incluyen el uso estricto de herramientas, no están disponibles para Claude Sonnet 5.5. Allí, envía auto sin strict, indica en el prompt cuándo llamar a la herramienta y valida la entrada de la herramienta en tu código.

Antes (Claude Sonnet 5):

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

Después (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    # uso de herramientas estricto: cada llamada coincide con el input_schema de la herramienta
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

El ejemplo marca como estrictas todas las herramientas de la lista. Una solicitud puede tener como máximo 20 herramientas estrictas, y las entradas de los conjuntos de herramientas de MCP, uso de computadora y uso de navegador no aceptan strict. En una lista de herramientas más larga, marca solo las herramientas que lo necesiten.

Los bloques de pensamiento están vinculados al modelo y a la conversación

Claude Sonnet 5.5 lee bloques de pensamiento de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 y modelos anteriores. No lee bloques de Claude Opus 5, Claude Opus 5.5 ni de ningún modelo Claude Fable o Claude Mythos. La API descarta los bloques que el modelo no puede leer. La solicitud sigue devolviendo 200, y los bloques descartados no se facturan. Consulta Cambiar de modelo a mitad de la conversación.

Cada bloque de pensamiento de Claude Sonnet 5.5 también está firmado sobre la conversación que lo precede. Para las cuentas creadas a partir del 31 de agosto de 2026, 00:00 UTC, la API aplica esto de forma predeterminada, en la API de Claude, Amazon Bedrock y Google Cloud. En esas cuentas, una solicitud que reproduce un bloque después de editar el historial anterior devuelve un error 400. Mantén las conversaciones en modo solo anexar y cambia las instrucciones o las herramientas con mensajes del sistema a mitad de la conversación. Los bloques de pensamiento que produce Claude Sonnet 5.5 solo funcionan en la cuenta que los produjo o en una cuenta vinculada a ella. Consulta Pensamiento preservado.

El uso de computadora requiere el conjunto de herramientas en la API de Claude y Google Cloud

En la API de Claude y Google Cloud, Claude Sonnet 5.5 admite el uso de computadora solo a través del conjunto de herramientas computer_toolset_20260801. Allí, computer_20251124 devuelve un error 400. Claude Sonnet 5.5 no acepta computer_20250124 en ninguna plataforma. Busca la versión que envías actualmente:

Si envías el encabezado beta fine-grained-tool-streaming-2025-05-14, elimínalo cuando migres al conjunto de herramientas. Junto a una entrada de conjunto de herramientas, devuelve un error 400. En su lugar, establece eager_input_streaming: true en cada herramienta que lo necesite.

El código que ya envía el conjunto de herramientas no necesita cambios. Migrar desde computer_20251124 enumera los cambios en la solicitud y en el bucle del agente. Para otras plataformas, consulta Compatibilidad.

La herramienta advisor acepta menos asesores

Con la herramienta advisor, un ejecutor Claude Sonnet 5.5 necesita uno de estos asesores: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5 o Claude Mythos 5.1. Los asesores Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 y Claude Sonnet 4.6 devuelven un error 400. El consejo llega cifrado como un bloque advisor_redacted_result, por lo que su texto no es legible en la respuesta. Consulta Compatibilidad de modelos.

El texto entre llamadas a herramientas se devuelve en bloques de pensamiento

En Claude Sonnet 5.5, las notas de más de una o dos oraciones que el modelo escribe entre llamadas a herramientas llegan como bloques thinking de actualización de progreso, vacíos con el display predeterminado. Los comentarios más cortos siguen siendo text. En Claude Sonnet 5 y modelos anteriores, todo el texto entre llamadas a herramientas llega como bloques text. Ninguna solicitud falla, pero una interfaz que muestra esas notas se queda en silencio.

Con pensamiento adaptativo, establece display en "updates" (beta, encabezado thinking-display-updates-2026-08-18) para obtener solo las actualizaciones, o en "summarized" para obtenerlas mezcladas con el razonamiento. Renderiza cada bloque thinking no vacío antes del bloque tool_use que lo sigue. Con between_tools, el texto llega sin display. Consulta Actualizaciones de progreso para el usuario.

Clasificadores de seguridad y respaldo

Claude Sonnet 5.5 rechaza solicitudes en más categorías que Claude Sonnet 5. Un rechazo devuelve stop_reason: "refusal", y su stop_details puede nombrar una de estas categorías:

• "cyber": La solicitud podría facilitar daños cibernéticos, como el desarrollo de malware o exploits.
• "bio": La solicitud podría facilitar daños biológicos, como métodos de laboratorio peligrosos.
• "frontier_llm": La solicitud podría ayudar al desarrollo de modelos de IA competidores.
• "reasoning_extraction": La solicitud pide al modelo que reproduzca su razonamiento interno en el texto de la respuesta.
• "general_harms": La solicitud corresponde a otra área de la política de uso. El trabajo benigno también puede activar esta categoría.

El respaldo del lado del servidor (fallbacks: "default", beta, solo en la API de Claude) reintenta los rechazos "cyber" y "frontier_llm" en Claude Sonnet 5. No reintenta los rechazos "bio", "reasoning_extraction" ni "general_harms". Consulta Rechazos y respaldo y Cómo se facturan los rechazos.

Las salvaguardas cibernéticas en tiempo real son nuevas para el código que proviene de Claude Sonnet 4.6, Claude Sonnet 4.5 y Claude Haiku 4.5. Para trabajo de seguridad legítimo, solicita acceso al Cyber Verification Program.

Otros cambios

• "Prompt caching" (almacenamiento en caché de prompts): El prompt mínimo almacenable en caché es de 512 tokens, frente a 1,024 en Claude Sonnet 5, Claude Sonnet 4.6 y Claude Sonnet 4.5. Consulta Almacenamiento en caché de prompts.
• Nuevas funciones: Para los mensajes del sistema a mitad de la conversación, los cambios de herramientas a mitad de la conversación y el esfuerzo por mensaje, consulta Novedades de Claude Sonnet 5.5. Con between_tools, el esfuerzo no puede cambiar a mitad de la conversación.

Cambios recomendados

Vuelve a ejecutar tu barrido de esfuerzo. Claude Sonnet 5.5 tiene cinco niveles de esfuerzo: low, medium, high, xhigh y max. El valor predeterminado en la API de Claude es high. Los niveles se han recalibrado, por lo que un nivel no produce la misma cantidad de pensamiento que en Claude Sonnet 5. Comienza con high, a menos que tu carga de trabajo sea agéntica o sensible a la "latency" (latencia). Para programación agéntica y uso de herramientas de varios pasos, comienza con medium para tareas bien especificadas y pasa a high para las más difíciles o largas. Para chat y otros trabajos sensibles a la latencia, comienza con medium o low. Establece el nivel en output_config.effort. Consulta Niveles de esfuerzo recomendados para Claude Sonnet 5.5. Luego, vuelve a evaluar las instrucciones de prompt específicas del modelo con respecto a Prompting para Claude Sonnet 5.5.

Migrar a Claude Sonnet 5.5 desde Claude Sonnet 4.6 y modelos Sonnet anteriores

Primero aplica todas las secciones anteriores, reemplazando claude-sonnet-4-6. Luego realiza estos cambios. En Claude Sonnet 4.5 o anterior, continúa con las subsecciones que siguen.

Cambios incompatibles

El pensamiento se ejecuta en las solicitudes que lo omitían. Consulta El pensamiento se ejecuta de forma predeterminada y Desactiva el pensamiento inicial.

Los presupuestos de pensamiento devuelven un error. Claude Sonnet 4.6 acepta thinking: {"type": "enabled", "budget_tokens": N} como configuración obsoleta. Claude Sonnet 4.5 y Claude Haiku 4.5 lo usan para todo el pensamiento. Claude Sonnet 5.5 devuelve un error 400:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Elimina el presupuesto y establece un nivel de esfuerzo. No existe una correspondencia fija entre un presupuesto y un nivel de esfuerzo, así que ejecuta tus evaluaciones en dos o tres niveles.

Antes (Claude Sonnet 4.6):

client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

Después (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

Los parámetros de muestreo devuelven un error. Claude Sonnet 4.6 y modelos anteriores, y Claude Haiku 4.5, aceptan temperature, top_p y top_k. En Claude Sonnet 5.5, un valor no predeterminado devuelve un error 400. Elimínalos.

El texto del pensamiento se omite de forma predeterminada. Consulta Gestiona el pensamiento en las respuestas.

Otros cambios

• Alrededor de un 30 % más de tokens: Claude Sonnet 5.5 usa el tokenizador de Claude Sonnet 5. En comparación con Claude Sonnet 4.6, Claude Sonnet 4.5 y Claude Haiku 4.5, el mismo texto produce alrededor de un 30 % más de tokens, según el contenido. Vuelve a contarlos con el conteo de tokens y revisa max_tokens y el costo.
• Esfuerzo: xhigh es nuevo, y los niveles se han recalibrado. Consulta Cambios recomendados.
• Imágenes: Claude Sonnet 5.5 usa el nivel de imagen de alta resolución, de hasta 2576 píxeles en el lado largo y 4,784 tokens visuales por imagen. Claude Sonnet 4.6, Claude Sonnet 4.5 y Claude Haiku 4.5 se limitan a 1568 píxeles y 1,568 tokens. Una imagen de 2000×1500 cuesta alrededor de 2.5 veces más tokens en Claude Sonnet 5.5. Consulta Resolución y costo en tokens.

Migrar desde Claude Sonnet 4.5 o anterior

En Claude Sonnet 4.5, Claude Sonnet 4 o Claude 3.7 Sonnet, primero aplica todas las secciones anteriores y luego estos cambios.

El prefill devuelve un error. Claude Sonnet 5.5 rechaza un último turno del asistente prellenado con un error 400, al igual que Claude Sonnet 4.6 y Claude Sonnet 5. Claude Sonnet 4.5, Claude Haiku 4.5 y los modelos más antiguos lo aceptan. El error dice:

This model does not support assistant message prefill. The conversation must end with a user message.

Reemplaza cada prefill según su propósito:

• Formato de salida: usa salidas estructuradas, o herramientas con campos enum para la clasificación.
• Preámbulos: pide en la indicación del sistema una respuesta directa.
• Rechazos no deseados: las instrucciones claras en el mensaje del usuario suelen ser suficientes.
• Continuaciones: muévelas al mensaje del usuario, por ejemplo: "Tu respuesta anterior se interrumpió y terminó con [previous_response]. Continúa desde donde lo dejaste."
• Recordatorios de contexto: colócalos en el turno del usuario.

Escape de la entrada de herramientas. El escape en los argumentos de las llamadas a herramientas puede variar. Analiza input con un analizador JSON estándar.

Uso de computadora. Claude Sonnet 5.5 no acepta computer_20250124. Consulta la tabla de uso de computadora.

Esfuerzo. Claude Sonnet 4.5 no tiene parámetro de esfuerzo. Establece un nivel de esfuerzo explícitamente, como se describe en Cambios recomendados.

Contexto y salida. Claude Sonnet 5.5 tiene una ventana de contexto más grande, sin encabezado beta, y un límite de salida más alto. Consulta la página del modelo. Elimina cualquier encabezado beta de ventana de contexto.

Encabezados beta. Elimina interleaved-thinking-2025-05-14, ya que el pensamiento adaptativo se intercala automáticamente. Reemplaza fine-grained-tool-streaming-2025-05-14 por eager_input_streaming: true en cada herramienta que lo necesite. Ese encabezado devuelve un error 400 junto a una entrada de conjunto de herramientas de uso de computadora o de uso de navegador. Consulta Streaming de herramientas detallado.

Salidas estructuradas. El parámetro output_format está obsoleto y se eliminará en el futuro. Para usarlo de todos modos, agrega el encabezado beta structured-outputs-2025-11-13. Sin él, la API devuelve un error 400. Usa output_config.format en su lugar.

Migrar desde Claude Sonnet 4 o anterior

Claude Sonnet 4 está retirado en la API de Claude y sigue disponible en Amazon Bedrock y Google Cloud. Claude 3.7 Sonnet está retirado. Desde cualquiera de los dos modelos, primero aplica todas las secciones anteriores y luego estos cambios:

• Versiones de herramientas: Usa text_editor_20250728, con el nombre de herramienta str_replace_based_edit_tool y sin el comando undo_edit. Usa code_execution_20260521. Consulta la herramienta de editor de texto y la herramienta de ejecución de código.
• Motivos de detención: Gestiona refusal. Claude 4.5 y los modelos posteriores también se detienen con model_context_window_exceeded al alcanzar el límite de la ventana de contexto. Consulta Gestionar los motivos de detención.
• Saltos de línea finales: Claude 4.5 y los modelos posteriores los conservan en los parámetros de cadena de las llamadas a herramientas.
• Encabezados beta heredados: Elimina token-efficient-tools-2025-02-19 y output-128k-2025-02-19.
• Prompts: Revísalos con respecto a las mejores prácticas de prompting.

Migrar a Claude Sonnet 5.5 desde Claude Haiku 4.5

Primero aplica todas las secciones hasta Migrar desde Claude Sonnet 4.5 o anterior, inclusive, omitiendo la subsección de Claude Sonnet 4. Luego realiza estos cambios:

• ID del modelo: Reemplaza claude-haiku-4-5-20251001, o el alias claude-haiku-4-5, por claude-sonnet-5-5.
• Costo: El precio por token es más alto, y el mismo texto produce más tokens. Vuelve a contar los tokens y restablece la línea base de costos. Consulta Precios de Claude.
• Almacenamiento en caché de prompts: El prompt mínimo almacenable en caché baja de 4,096 tokens al mínimo de Claude Sonnet 5.5.
• Pensamiento intercalado: El pensamiento adaptativo se ejecuta automáticamente entre llamadas a herramientas, sin encabezado beta.
• Enrutamiento: Claude Sonnet 5.5 lee los bloques de pensamiento de Claude Haiku 4.5. Una conversación que sube de modelo conserva su razonamiento. Una que vuelve a bajar a Claude Haiku 4.5 descarta los bloques de Claude Sonnet 5.5.