Guía de migración a Claude Haiku 5.5

Esta guía cubre cómo migrar código que llama a Claude Haiku 4.5 a Claude Haiku 5.5. Para pasar en su lugar a un modelo Sonnet u Opus, consulta Actualizar entre versiones de modelos. Para saber cuánto tiempo seguirá disponible Claude Haiku 4.5, consulta Deprecaciones de modelos.

Lista de verificación de migración

Cada elemento es un cambio que debes hacer en el código que llama a Claude Haiku 4.5.

1. Reemplaza el ID de modelo por el ID de Claude Haiku 5.5 para tu plataforma. Consulta Usa el ID de modelo de Claude Haiku 5.5.
2. Vuelve a contar tus prompts y revisa los límites de max_tokens y las estimaciones de costos, porque el mismo texto cuenta como más tokens. Consulta Vuelve a contar los tokens.
3. Si tus solicitudes envían thinking: {"type": "enabled", "budget_tokens": N}, cambia thinking a {"type": "adaptive"}. Consulta Configura el pensamiento.
4. Si tu código lee el primer bloque de contenido como la respuesta, selecciona los bloques por type en su lugar. Consulta Configura el pensamiento.
5. Elimina temperature, top_p y top_k de tus solicitudes. Consulta Elimina los parámetros de muestreo.
6. Si tus solicitudes terminan messages con un turno del asistente para que el modelo lo continúe, termínalas con un turno del usuario en su lugar. Consulta Reemplaza el prefill del asistente.
7. Si usas el uso de computadora en la Claude API o en Google Cloud, pasa de computer_20250124 al conjunto de herramientas computer_toolset_20260801. Consulta Migra el uso de computadora al conjunto de herramientas.
8. Si reproduces conversaciones almacenadas a través de una cuenta diferente, reproduce cada una a través de la cuenta que la produjo. Consulta Reproduce los bloques de pensamiento a través de la cuenta que los produjo.
9. Si tu código cambia system, tools o messages anteriores entre solicitudes de una conversación y devuelve bloques de pensamiento, mantén la conversación en modo de solo anexar. Consulta Mantén sin cambios los turnos anteriores.
10. Maneja stop_reason: "refusal". Claude Haiku 5.5 ejecuta clasificadores de seguridad que pueden rechazar una solicitud, y no tiene fallback del lado del servidor. Consulta Rechazos de las salvaguardas.

Si tu organización tiene un compromiso de Priority Tier en Claude Haiku 4.5, planifica la capacidad por separado: Priority Tier no es compatible con Claude Haiku 5.5.

Usa el ID de modelo de Claude Haiku 5.5

Reemplaza el ID de modelo de Claude Haiku 4.5 por el ID de Claude Haiku 5.5 para tu plataforma.

claude-haiku-5-5 es un ID de modelo fijo sin sufijo de fecha y sin un alias separado.

Vuelve a contar los tokens

Claude Haiku 5.5 usa el mismo "tokenizer" (tokenizador) más reciente que Claude 4.7 y los modelos posteriores. Como ocurre con todos los modelos que usan este tokenizador, el mismo texto de entrada produce aproximadamente un 30% más de tokens en Claude Haiku 5.5 que en Claude Haiku 4.5. El aumento exacto depende del contenido. Las solicitudes, las respuestas y los eventos de streaming mantienen la misma forma. Lo que cambia es todo lo que midas o presupuestes en tokens:

• Los campos de usage y los resultados del conteo de tokens son más altos para el mismo texto.
• Una cantidad determinada de tokens contiene menos texto.
• Un límite de max_tokens ajustado para Claude Haiku 4.5 puede cortar una salida equivalente.
• Las estimaciones de costos hechas a partir de los conteos de tokens de Claude Haiku 4.5 deben recalcularse con los conteos y los precios de Claude Haiku 5.5.

Cuenta tus prompts con model establecido en claude-haiku-5-5 en lugar de reutilizar los conteos medidos en Claude Haiku 4.5.

Configura el pensamiento

Claude Haiku 5.5 configura el pensamiento de forma diferente a Claude Haiku 4.5. Un valor de thinking de {"type": "enabled", "budget_tokens": N} devuelve un error 400, por lo que una solicitud que lo envíe necesita un nuevo valor de thinking.

Antes, una solicitud a Claude Haiku 4.5 establecía thinking en enabled con un presupuesto de tokens:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

Después, la misma solicitud a Claude Haiku 5.5 usa el "adaptive thinking" (pensamiento adaptativo). El valor de thinking cambia, y output_config.effort establece cuánto piensa el modelo:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

El pensamiento adaptativo está activado de forma predeterminada, por lo que una respuesta puede comenzar con uno o más bloques thinking incluso cuando la solicitud no establece thinking. Deja thinking sin establecer o establécelo en {"type": "adaptive"}, y usa el esfuerzo como palanca: donde Claude Haiku 4.5 se ejecutaba sin pensamiento, o con un presupuesto pequeño para ahorrar tokens, elige un nivel de esfuerzo más bajo. En un nivel más bajo, el modelo piensa menos y puede omitir el pensamiento por completo en solicitudes más simples. Para obtener orientación sobre prompts, consulta Usa el esfuerzo para controlar el pensamiento. Selecciona los bloques de contenido por su campo type en lugar de por su posición, y devuelve los bloques thinking sin modificar junto con los resultados de las herramientas.

Los tokens de pensamiento cuentan para max_tokens, por lo que una solicitud con un max_tokens pequeño puede detenerse con stop_reason: "max_tokens" después de un bloque thinking y antes de cualquier texto. Si estableciste un max_tokens pequeño para Claude Haiku 4.5, auméntalo para dejar espacio para el pensamiento, o elige un nivel de esfuerzo más bajo.

De forma predeterminada, Claude Haiku 5.5 devuelve cada bloque thinking con un campo thinking vacío y solo una signature, mientras que Claude Haiku 4.5 devolvía el pensamiento resumido. Para recibir el pensamiento resumido, establece thinking: {"type": "adaptive", "display": "summarized"}.

Claude Haiku 5.5 acepta un tool_choice forzado (any o una herramienta con nombre), pero la respuesta comienza con la llamada a la herramienta y no tiene ningún bloque thinking. Para permitir que el modelo piense antes de llamar a una herramienta, usa tool_choice: {"type": "auto"} e indica en el prompt cuándo usar la herramienta.

Elimina los parámetros de muestreo

Claude Haiku 4.5 acepta temperature, top_p y top_k. En Claude Haiku 5.5, omite los tres y usa los prompts para guiar el comportamiento del modelo en su lugar. Si una solicitud incluye temperature, debe ser 1. Si incluye top_p, debe ser 0.99, su valor predeterminado. Cualquier otro valor de temperature o top_p devuelve un error 400, incluido un top_p de 1. Lo mismo ocurre con cualquier valor de top_k, y con una solicitud que incluya tanto temperature como top_p.

Reemplaza el prefill del asistente

Un "prefill" (prellenado) es un turno final del asistente en messages que el modelo continúa. Claude Haiku 4.5 lo acepta cuando el pensamiento está desactivado. Claude Haiku 5.5 lo rechaza con un error 400, incluso con el pensamiento desactivado. Termina messages con un turno del usuario y reemplaza cada prefill según su propósito:

• Formato de salida: usa salidas estructuradas, o herramientas con campos enum para la clasificación. En Claude en Amazon Bedrock, que no admite salidas estructuradas, usa herramientas.
• Preámbulos: pide en la indicación del sistema una respuesta directa.
• Continuaciones: muévelas al mensaje del usuario, por ejemplo "Tu respuesta anterior se interrumpió y terminó con [previous_response]. Continúa desde donde te quedaste."
• Recordatorios de contexto: colócalos en el turno del usuario.

Migra el uso de computadora al conjunto de herramientas

Claude Haiku 4.5 admite el "computer use" (uso de computadora) a través de la herramienta computer_20250124, con el encabezado beta computer-use-2025-01-24. En la Claude API y en Google Cloud, Claude Haiku 5.5 admite el uso de computadora solo a través del conjunto de herramientas computer_toolset_20260801, y una solicitud que declare computer_20250124 devuelve un error 400.

Para migrar una integración, elimina el encabezado beta computer-use-2025-01-24 y reemplaza la entrada de tools por {"type": "computer_toolset_20260801"}. Luego realiza los demás cambios en la solicitud y en el bucle del agente descritos en Migrar desde computer_20251124: despacha según el name y el toolset_name de cada bloque tool_use miembro en lugar de según input.action, maneja cada uno de esos bloques en un turno y repite toolset_name en los resultados. El zoom está activado de forma predeterminada en el conjunto de herramientas; si tu entorno no lo implementa, agrega "configs": {"zoom": {"enabled": false}}. Si envías el encabezado beta fine-grained-tool-streaming-2025-05-14, elimínalo. Junto con una entrada de conjunto de herramientas, devuelve un error 400. Para otras plataformas, consulta la sección Compatibilidad de la herramienta de uso de computadora.

En la Claude API y en Google Cloud, Claude Haiku 5.5 también admite la herramienta de uso del navegador (browser_toolset_20260801) para tareas dentro de páginas web. Claude Haiku 4.5 no la admite.

Reproduce los bloques de pensamiento a través de la cuenta que los produjo

Los bloques de pensamiento de Claude Haiku 5.5 funcionan solo en la cuenta que los produjo, o en una cuenta vinculada a ella. Cuando otra cuenta envía uno de estos bloques, la API descarta el bloque antes de que el modelo lo vea, y la solicitud se completa correctamente sin ese razonamiento. Esto afecta al código que almacena conversaciones y las reproduce a través de una cuenta diferente, por ejemplo, un servicio que atiende a varios clientes desde un único almacén de conversaciones. Reproduce cada conversación a través de la cuenta que la produjo. Consulta Los bloques de pensamiento permanecen con la cuenta que los produjo.

Mantén sin cambios los turnos anteriores

Un bloque de pensamiento de Claude Haiku 5.5 sigue siendo válido solo mientras todo lo enviado antes de él permanezca sin cambios: una solicitud que devuelve un bloque de pensamiento después de un cambio en system, tools o messages anteriores devuelve un error 400. Claude Haiku 4.5 no realiza esta comprobación. Mantén las conversaciones en modo de solo anexar. En las cuentas creadas antes del 31 de agosto de 2026, 00:00 UTC, el error se produce solo en las solicitudes que establecen thinking.block_binding.prefix_mismatch_behavior. Para conocer los cambios que provocan el error y qué hacer en su lugar, consulta Quién necesita cambiar algo.