Guía de migración 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 continúa hasta 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, excepto por las lecturas de la caché de prompts, que cuestan $0.10 USD por millón de tokens, la mitad de la tarifa de Claude Sonnet 5. Consulta Precios. 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 cómo escribir prompts, consulta Novedades de Claude Sonnet 5.5 y Cómo escribir prompts 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 esfuerzo y 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.

Maneja el pensamiento en las respuestas

El código que se ejecutaba sin pensamiento necesita los tres elementos. El código proveniente 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 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:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

between_tools funciona en todas las plataformas que ofrecen Claude Sonnet 5.5. Se acepta con esfuerzo low, medium y high. Con xhigh o max, devuelve un error 400. Para ejecutar en esos niveles, usa el pensamiento adaptativo: omite el campo thinking o envía thinking: {"type": "adaptive"}. between_tools no admite ningún otro campo: si se envía display, budget_tokens o block_binding junto con él, se devuelve un error 400. Con el fallback 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 el pensamiento adaptativo. Para obtener orientación sobre prompts, consulta Ejecutar sin pensamiento inicial.

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 mencione tu modelo. En Claude Haiku 4.5, aplica todos los grupos excepto “Claude Sonnet 4 o anterior”, terminando 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 ejecutándolo sin pensamiento inicial, envía la configuración de pensamiento más baja con esfuerzo high o inferior.
• Reemplaza el “forced tool use” (uso forzado de herramientas) por auto y herramientas estrictas.
• Mantén las conversaciones en modo “append-only” (solo anexar).
• Mueve el “computer use” (uso del ordenador) al conjunto de herramientas, sin el encabezado beta fine-grained-tool-streaming-2025-05-14. En Amazon Bedrock, computer_20251124 también funciona.
• Combina la herramienta de asesor con un asesor compatible y espera recibir consejos cifrados.
• Lee el texto entre llamadas a herramientas desde los bloques thinking.
• Gestiona los rechazos y configura una alternativa de respaldo.
• Vuelve a ejecutar tu barrido de esfuerzo y restablece la referencia 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 temperature, top_p y top_k.
• Si muestras el texto del pensamiento, establece display: "summarized".
• Vuelve a contar los tokens y reajusta el presupuesto de tokens de imágenes.

Claude Sonnet 4.5 o anterior

• Reemplaza los “assistant prefills” (prellenados del asistente).
• Analiza la entrada de las llamadas a herramientas con un analizador JSON estándar.
• Establece output_config.effort de forma explícita.
• 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.
• Maneja 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 el ID de tu modelo por claude-sonnet-5-5, que no tiene sufijo de fecha. En otras plataformas, usa el ID que aparece 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 necesita additionalProperties: false en cada objeto. Consulta Limitaciones de JSON Schema.

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. En la Claude API y en Claude Models on Google Cloud (Google managed), también los lee de Claude Haiku 5.5. No lee bloques de Claude Opus 5, Claude Opus 5.5 ni de ningún modelo Claude Fable o Claude Mythos.

La API omite los bloques que el modelo no puede leer. La solicitud devuelve 200, y los bloques omitidos no se facturan. Consulta Cambiar de modelo y volver.

Mantén las conversaciones en modo solo anexar, para que los bloques de pensamiento pasen la verificación de prefijo. Para cambiar las instrucciones o las herramientas, consulta Mensajes del sistema y cambios de herramientas a mitad de la conversación.

No superar la “prefix check” (verificación de prefijo) puede o no dar lugar a un error 400. Para identificar y manejar ambos casos, consulta Verificaciones de prefijo en bloques de pensamiento.

La verificación de prefijo se ejecuta en la Claude API y en algunas plataformas en la nube.

Los bloques de pensamiento de Claude Sonnet 5.5 funcionan solo en la cuenta que los produjo o en una cuenta vinculada a ella. Consulta Pensamiento preservado.

Algunas versiones de la herramienta de uso del ordenador no son compatibles

Claude Sonnet 5.5 admite el uso del ordenador a través del conjunto de herramientas computer_toolset_20260801. En Amazon Bedrock, Claude Sonnet 5.5 también acepta la herramienta computer_20251124 con el encabezado beta computer-use-2025-11-24. Claude Sonnet 5.5 devuelve un error 400 para cualquier versión de la herramienta de uso del ordenador que no acepte, como computer_20251124 en la Claude API. No acepta computer_20250124 en ninguna plataforma.

Las integraciones que usan el conjunto de herramientas no necesitan ningún cambio. Para pasar al conjunto de herramientas, reemplaza computer_20251124 o computer_20250124 por computer_toolset_20260801 y omite el encabezado beta de esa versión. Para ver los cambios en la solicitud y en el bucle del agente, consulta Migrar desde computer_20251124.

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

La herramienta de asesor acepta menos asesores

Con la herramienta de asesor, 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 Fable 5.2, Claude Mythos 5, Claude Mythos 5.1 o Claude Mythos 5.2. Los asesores Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 y Claude Haiku 5.5 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 deja de mostrarlas.

Con el 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. Muestra 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 fallback

Claude Sonnet 5.5 se niega en más categorías que Claude Sonnet 5. Una negativa devuelve stop_reason: "refusal", y su stop_details puede indicar 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 le 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 fallback del lado del servidor (fallbacks: "default"), en beta en la Claude API y en Claude Models on Google Cloud (Anthropic managed), reintenta las negativas "cyber" y "frontier_llm" en Claude Sonnet 5. No reintenta las negativas "bio", "reasoning_extraction" ni "general_harms". Consulta Negativas y fallback y Cómo se facturan las negativas.

Las salvaguardas cibernéticas en tiempo real son nuevas para el código proveniente 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 que se puede almacenar 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 Claude API es high. Los niveles están recalibrados, 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 la programación agéntica y el uso de herramientas de varios pasos, comienza con medium para tareas bien especificadas y pasa a high para tareas más difíciles o más 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 base en Cómo escribir prompts 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 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. Elimina temperature, top_p y top_k.

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

Otros cambios

• Aproximadamente un 30 por ciento 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 aproximadamente un 30 por ciento más de tokens, según el contenido. Vuelve a contar con el conteo de tokens y revisa max_tokens y el costo.
• Esfuerzo: Claude Sonnet 5.5 admite xhigh y los niveles están recalibrados. Consulta Cambios recomendados.
• Imágenes: Claude Sonnet 5.5 usa el nivel de imágenes de alta resolución, de hasta 2,576 píxeles en el lado largo y hasta 4,784 tokens visuales por imagen. Claude Sonnet 4.6, Claude Sonnet 4.5 y Claude Haiku 4.5 se detienen en 1,568 píxeles y 1,568 tokens. Una imagen de 2000×1500 cuesta aproximadamente 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 con prefill 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 clasificación.
• Preámbulos: pide en la indicación del sistema una respuesta directa.
• Negativas no deseadas: 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 en la entrada de herramientas. El escape en los argumentos de las llamadas a herramientas puede diferir. Analiza input con un analizador JSON estándar.

Uso del ordenador. Claude Sonnet 5.5 no acepta computer_20250124. Consulta Algunas versiones de la herramienta de uso del ordenador no son compatibles.

Esfuerzo. Claude Sonnet 4.5 no tiene parámetro de esfuerzo. Establece un nivel de esfuerzo de forma explícita (consulta Cambios recomendados).

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

Encabezados beta. Elimina interleaved-thinking-2025-05-14, porque 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 con una entrada de conjunto de herramientas de uso de computadora o de uso de navegador. Consulta Streaming detallado de herramientas.

Salidas estructuradas. El parámetro output_format está obsoleto. 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 Claude API, pero disponible en Claude Models on Google Cloud (Google managed) y en Amazon Bedrock. 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: Maneja refusal. Los modelos Claude 4.5 y posteriores también se detienen con model_context_window_exceeded al alcanzar el límite de la ventana de contexto. Consulta Razones de detención y fallback.
• Saltos de línea finales: Los modelos Claude 4.5 y posteriores los conservan en los parámetros de cadena de las llamadas a herramientas.
• Encabezados beta: Elimina token-efficient-tools-2025-02-19 y output-128k-2025-02-19.
• Prompts: Revísalos con base en las mejores prácticas para escribir prompts.

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.
• Almacenamiento en caché de prompts: El prompt mínimo que se puede almacenar en caché baja de 4,096 tokens al mínimo de Claude Sonnet 5.5.
• Pensamiento intercalado: El pensamiento adaptativo se ejecuta entre llamadas a herramientas automáticamente.
• 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 omite los bloques de Claude Sonnet 5.5.