Tutorial de Migración OpenAI → Claude (2026)

Ambos SDKs ahora aceptan la misma forma de array `messages: [{role, content}]`. Las diferencias: nombre del método, estructura de respuesta, y cómo se pasan los prompts del sistema. Aquí está el diff canónico para una conclusión simple.

```python # OpenAI (antes) from openai import OpenAI client = OpenAI() resp = client.chat.completions.create( model="gpt-5.5", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize: ..."} ], max_tokens=500, ) answer = resp.choices[0].message.content ```

```python # Anthropic (después) import anthropic client = anthropic.Anthropic() resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=500, system="You are a helpful assistant.", messages=[ {"role": "user", "content": "Summarize: ..."} ], ) answer = resp.content[0].text ```

Tres diferencias. **El prompt del sistema es su propio campo** en Claude (`system=`), no un mensaje en el array. **`max_tokens` es requerido** en Claude (OpenAI tiene un valor por defecto). **Forma de respuesta** es `resp.content[0].text` (un array de bloques de contenido) en lugar de `resp.choices[0].message.content`.

El streaming funciona de la misma manera conceptualmente — ambos exponen gestores de contexto `with client.<x>.stream(...)`. Los eventos de Anthropic están más estructurados (`content_block_start`, `content_block_delta`, `content_block_stop`) donde el stream de OpenAI es una secuencia plana de chunks de conclusión. La mayoría del código de producción simplemente itera el stream y concatena `delta.text` (Claude) o `delta.content` (OpenAI) — ambos funcionan.

Los modelos GPT funcionan bien con prompts del sistema con estructura markdown (`# Encabezado`, `**negrita**`, listas numeradas). Los modelos Claude funcionan notoriamente mejor con estructura etiquetada en XML. La propia guía de ingeniería de prompts de Anthropic recomienda las etiquetas XML como la forma canónica de delimitar secciones — `<context>`, `<instructions>`, `<example>`, `<output_format>`, `<constraints>`.

Antes (ajustado para GPT):

``` You are a senior product analyst. ## Task Write a competitive analysis of X. ## Context The customer is... ## Output Return JSON with... ```

Después (ajustado para Claude):

``` You are a senior product analyst. <task> Write a competitive analysis of X. </task> <context> The customer is... </context> <output_format> Return JSON with... </output_format> ```

Por qué importa esto: el patrón de atención de Claude está ajustado para reconocer límites de etiquetas XML y ponderar el contenido dentro de ellas apropiadamente. Los encabezados markdown funcionan pero requieren que Claude infiera la estructura de la convención. Las etiquetas XML hacen la estructura explícita y mejoran sustancialmente la calidad de salida en prompts complejos. En una evaluación de 50 prompts que ejecutamos en mayo de 2026 en tareas de clasificación de atención al cliente, el mismo prompt reestructurado de markdown a XML elevó la precisión de Sonnet 4.6 entre 7-12 puntos porcentuales.

Los ejemplos de few-shot también funcionan mejor cuando se envuelven en etiquetas `<example>...</example>`. La etiqueta de cierre importa — etiquetas incompletas (`<example>` sin `</example>`) confunden el análisis de Claude.

El caché de prompts de OpenAI es oportunista y solo de prefijo — obtienes ahorros automáticamente si tu prompt del sistema es estable. El caché de prompts de Claude es *explícito* — marcas puntos de ruptura en el array de mensajes y pagas una prima en la escritura de caché (1,25x para TTL de 5 min, 2x para TTL de 1 hora) a cambio de costo de lectura del 10% (ahorro del 90%) en golpes posteriores.

El modelo explícito es más poderoso porque puedes cachear cualquier porción de la entrada, no solo el prefijo literal. Cachea el prompt del sistema + herramientas + primer ejemplo few-shot; varía la consulta del usuario libremente. Ejemplo:

```python # Cachea el prefijo estable (sistema + herramientas + pocos disparos) resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=500, system=[ { "type": "text", "text": SYSTEM_PROMPT, # estable a través de llamadas "cache_control": {"type": "ephemeral"} } ], tools=TOOL_DEFINITIONS, # también cacheado a través del punto de ruptura del sistema anterior messages=[ {"role": "user", "content": user_input} # no cacheado ], ) ```

El punto de equilibrio en la escritura de caché de 1 hora (prima 2x) ocurre después de exactamente 2 golpes — trivial para limpiar en agentes de producción. En un prompt del sistema de 2.000 tokens + 1.500 tokens de herramientas (3.500 tokens cacheados) en Sonnet 4.6 leído 100 veces en una hora:

Escritura de caché: 3.500 / 1M × $6 = $0,021 (una vez). Lecturas de caché: 99 × 3.500 / 1M × $0,30 = $0,10395. Costo cacheado total: $0,125. Sin caché: 100 × 3.500 / 1M × $3 = $1,05. **Ahorro: $0,925 — 88% de descuento en la porción de prefijo de la factura**.

Este es el mayor factor de costo de la migración. Los equipos que cambian de OpenAI a Claude sin configurar puntos de ruptura de caché explícitos a menudo terminan pagando *más* — porque la suposición 'Claude es más barato' se basaba en precios cacheados que no habilitaron. La configuración de caché no es opcional para migraciones de producción.

Ambas APIs soportan tool-use (llamada de función). Los esquemas difieren ligeramente. Las herramientas de OpenAI son `{type: 'function', function: {name, description, parameters}}`. Las herramientas de Claude son `{name, description, input_schema}` — más planas, sin envoltorio `function` de cierre.

OpenAI (antes):

```python tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather", "parameters": { "type": "object", "properties": { "location": {"type": "string"} } } } } ] ```

Claude (después):

```python tools = [ { "name": "get_weather", "description": "Get current weather", "input_schema": { "type": "object", "properties": { "location": {"type": "string"} } } } ] ```

Las respuestas de herramientas también difieren. OpenAI devuelve `tool_calls` en el mensaje del asistente. Claude devuelve bloques de contenido `tool_use` dentro del array de mensajes. Construcción del bucle:

```python # Bucle de herramientas Claude while True: resp = client.messages.create(model="claude-sonnet-4-6", tools=tools, messages=messages) if resp.stop_reason == "end_turn": break messages.append({"role": "assistant", "content": resp.content}) for block in resp.content: if block.type == "tool_use": result = run_tool(block.name, block.input) messages.append({"role": "user", "content": [ {"type": "tool_result", "tool_use_id": block.id, "content": result} ]}) ```

Dos gotchas. Primero, Claude requiere que el resultado de la herramienta sea un mensaje de `user` con un bloque de contenido `tool_result` — no un rol `tool` separado como OpenAI. Segundo, las llamadas de herramientas paralelas se devuelven como múltiples bloques `tool_use` en el mismo turno del asistente — tu ejecutor de herramientas necesita manejarlos en paralelo, luego devolver todos los resultados en un solo mensaje de usuario.

Ahora las matemáticas de costo real para tu carga de trabajo. Toma una forma de producción representativa: 1M llamadas/mes, 2.000 tokens de entrada promedio, 500 tokens de salida promedio, con un prefijo estable de 1.500 tokens (candidato a caché).

**Antes — gpt-5.5 sin caché** (el caché oportunista de OpenAI puede ayudar pero no se modela aquí):

Entrada: 1M × 2.000 / 1M = 2.000M tokens × $5/1M = $10.000. Salida: 1M × 500 / 1M = 500M tokens × $30/1M = $15.000. **Total: $25.000/mes**.

**Después — Claude Sonnet 4.6 sin caché**:

Entrada: 2.000M × $3/1M = $6.000. Salida: 500M × $15/1M = $7.500. **Total: $13.500/mes** — ahorro del 46% incluso sin caché.

**Después — Claude Sonnet 4.6 con caché explícito** (TTL de 1 hora en prefijo de 1.500 tokens, tasa de acierto de caché del 90%):

Escrituras de caché: 0,1M (fallo de caché) × 1.500/1M × $6 = $900. Lecturas de caché: 0,9M × 1.500/1M × $0,30 = $405. Porción de entrada no cacheada (500 tokens restantes × 1M) = 500M × $3/1M = $1.500. Salida: $7.500. **Total: $10.305/mes** — ahorro del 59% vs OpenAI.

**Delta anual**: $25.000 × 12 - $10.305 × 12 = $300.000 - $123.660 = **$176.340/año ahorrados** en esta carga de trabajo.

Advertencia importante: gpt-5.5 → Sonnet 4.6 es la migración de alto apalancamiento. gpt-5.4 → Sonnet 4.6 realmente *cuesta más* por llamada ($3 entrada vs $2,50). gpt-5.4-mini → Haiku 4.5 también cuesta más (+33% entrada). En el nivel pequeño / nano, OpenAI gana en precio. Migra el nivel premium y medio; mantén el nivel pequeño y nano en OpenAI. La calculadora de delta de costos se convierte en por carga de trabajo, no por organización.

**Primero paridad de evaluación**. Ejecuta ambos proveedores en tu conjunto de evaluación retenido antes de cambiar. El mismo prompt reestructurado para Claude debe coincidir o superar la línea de base de GPT; si no es así, tienes un problema de prompt, no un problema de modelo.

**Tráfico en la sombra durante una semana**. Enruta del 5-10% del tráfico de producción a Claude junto con OpenAI, registra ambas salidas, compara la calidad. Atrapa regresiones silenciosas antes de que se envíen a los usuarios.

**Configura tu monitoreo antes del cambio**. Conteos de tokens, latencia, tasas de error, relación de acierto de caché. La relación de acierto de caché es la métrica que determina si tus matemáticas de migración se mantienen en producción — rastreala explícitamente.

**Planifica una ruta de reversión**. Feature-flag la opción de modelo en tu código; vuelve a OpenAI en segundos si la calidad cae. No saques OpenAI de tu lista de dependencias el día 1 del cambio.

**Comunícate con los usuarios solo cuando sea relevante**. La mayoría de características de IA dirigidas al usuario no necesitan anunciar cambios de modelo. Las herramientas internas podrían (los desarrolladores se preocupan por qué modelo está sugiriendo su código).

Ambas APIs streamean tokens. La forma del evento es lo suficientemente diferente como para que copiar-pegar ingenuo del código de streaming falle sutilmente. OpenAI streamea una secuencia plana de strings `chunk.choices[0].delta.content`; Claude streamea eventos estructurados con límites de inicio/delta/parada explícitos en cada bloque de contenido.

Patrón de streaming OpenAI:

```python stream = client.chat.completions.create( model="gpt-5.5", messages=messages, stream=True, ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") ```

Patrón de streaming Claude:

```python with client.messages.stream( model="claude-sonnet-4-6", max_tokens=500, messages=messages, ) as stream: for text in stream.text_stream: print(text, end="") ```

El ayudante `text_stream` en Claude aplana los eventos estructurados en un stream de string plano — la mayoría del código de producción lo usa. Si necesitas control más fino (por ejemplo, manejar bloques tool_use mid-stream, surfacear contenido de razonamiento por separado), desciende a la API de nivel de evento y busca coincidencias en `event.type`.

El streaming de tool-use es significativamente diferente en Claude. La entrada de herramienta JSON streamea como deltas JSON parciales dentro de eventos `content_block_delta` con `delta.type === 'input_json_delta'`. La concatenación de string ingenua funciona pero necesitas esperar el evento `content_block_stop` antes de analizar el JSON completo. El streaming de llamadas de herramientas de OpenAI tiene un patrón JSON parcial similar; los nombres de campo difieren.

**Error 1: asumir que Claude es más barato sin revisar el nivel**. Sonnet 4.6 vs gpt-5.4 es aproximadamente parejo, y Haiku 4.5 es realmente *más caro* que gpt-5.4-mini. Los ahorros provienen del nivel premium (Opus 4.8 vs gpt-5.5-pro) y del nivel medio con caché (Sonnet 4.6 + caché de 1 hora vs gpt-5.5).

**Error 2: copiar prompts verbatim**. La estructura markdown funciona en Claude pero la estructura de etiquetas XML funciona mejor. Saltar la reestructuración de prompts deja calidad en la mesa.

**Error 3: saltar puntos de ruptura de caché explícitos**. La afirmación 'Claude es más barato' depende del caché. Sin puntos de ruptura explícitos, puedes pagar más por llamada que el equivalente de OpenAI. Configura el caché como parte de la migración, no como un seguimiento.

**Error 4: no manejar llamadas de herramientas paralelas**. Claude devuelve múltiples bloques `tool_use` por turno cuando hace llamadas de herramientas paralelas. Tu ejecutor de herramientas necesita manejarlos concurrentemente y devolver todos los resultados en un mensaje de usuario.

**Error 5: mantener `max_tokens` configurado en valores por defecto de OpenAI**. Claude requiere que `max_tokens` sea explícito. El código antiguo que se basaba en el valor por defecto de OpenAI (máximo del modelo) necesita establecer un techo real — típicamente 500-2.000 para casos de uso de chat. No lo configures demasiado alto; pagarás por salida que no necesitas.