OpenAI → Claude Migration Tutorial (2026)

Both SDKs now accept the same `messages: [{role, content}]` array shape. The differences: method name, response structure, and how system prompts are passed. Here's the canonical diff for a simple completion.

```python # OpenAI (before) 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 (after) 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 ```

Three differences. **System prompt is its own field** on Claude (`system=`), not a message in the array. **`max_tokens` is required** on Claude (OpenAI defaults to model max). **Response shape** is `resp.content[0].text` (an array of content blocks) instead of `resp.choices[0].message.content`.

Streaming works the same way conceptually — both expose `with client.<x>.stream(...)` context managers. Anthropic's events are more structured (`content_block_start`, `content_block_delta`, `content_block_stop`) where OpenAI's stream is a flat sequence of completion chunks. Most production code just iterates the stream and concatenates `delta.text` (Claude) or `delta.content` (OpenAI) — both work.

GPT models perform well with markdown-structured system prompts (`# Heading`, `**bold**`, numbered lists). Claude models perform noticeably better with XML-tagged structure. Anthropic's own prompt engineering guide recommends XML tags as the canonical way to delimit sections — `<context>`, `<instructions>`, `<example>`, `<output_format>`, `<constraints>`.

Before (GPT-tuned):

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

After (Claude-tuned):

``` 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> ```

Why this matters: Claude's attention pattern is tuned to recognize XML tag boundaries and weight content inside them appropriately. Markdown headings work but require Claude to infer structure from convention. XML tags make the structure explicit and substantially improve output quality on complex prompts. On a 50-prompt eval we ran in May 2026 across customer-support classification tasks, the same prompt restructured from markdown to XML lifted Sonnet 4.6 accuracy by 7-12 percentage points.

Few-shot examples are also better when wrapped in `<example>...</example>` tags. The closing tag matters — incomplete tags (`<example>` without `</example>`) confuse Claude's parsing.

OpenAI's prompt caching is opportunistic and prefix-only — you get savings automatically if your system prompt is stable. Claude's prompt caching is *explicit* — you mark breakpoints in the message array and pay a premium on the cache write (1.25x for 5-min TTL, 2x for 1-hour TTL) in exchange for 10% read cost (90% savings) on subsequent hits.

The explicit model is more powerful because you can cache any portion of the input, not just the literal prefix. Cache system prompt + tools + first few-shot example; vary the user query freely. Example:

```python # Cache the stable prefix (system + tools + few-shot) resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=500, system=[ { "type": "text", "text": SYSTEM_PROMPT, # stable across calls "cache_control": {"type": "ephemeral"} } ], tools=TOOL_DEFINITIONS, # also cached via the system breakpoint above messages=[ {"role": "user", "content": user_input} # not cached ], ) ```

Break-even on the 1-hour cache write (2x premium) happens after exactly 2 hits — almost trivial to clear for production agents. On a 2,000-token system prompt + 1,500-token tools (3,500 cached tokens) on Sonnet 4.6 read 100 times in an hour:

Cache write: 3,500 / 1M × $6 = $0.021 (one-time). Cache reads: 99 × 3,500 / 1M × $0.30 = $0.10395. Total cached cost: $0.125. Without cache: 100 × 3,500 / 1M × $3 = $1.05. **Saving: $0.925 — 88% off the prefix portion of the bill**.

This is the migration's biggest cost lever. Teams that move from OpenAI to Claude without setting up explicit cache breakpoints often end up paying *more* — because the 'Claude is cheaper' assumption was based on cached pricing they didn't enable. Cache setup is not optional for production migrations.

Both APIs support tool use (function calling). The schemas differ slightly. OpenAI's tools are `{type: 'function', function: {name, description, parameters}}`. Claude's tools are `{name, description, input_schema}` — flatter, no enclosing `function` wrapper.

OpenAI (before):

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

Claude (after):

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

Tool responses also differ. OpenAI returns `tool_calls` on the assistant message. Claude returns `tool_use` content blocks inside the messages array. Loop construction:

```python # Claude tool loop 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} ]}) ```

Two gotchas. First, Claude requires the tool result to be a `user` message with `tool_result` content block — not a separate `tool` role like OpenAI. Second, parallel tool calls are returned as multiple `tool_use` blocks in the same assistant turn — your tool runner needs to handle them in parallel, then return all results in a single user message.

Now the actual cost math for your workload. Take a representative production shape: 1M calls/month, 2,000 tokens average input, 500 tokens average output, with a 1,500-token stable system prefix (caching candidate).

**Before — gpt-5.5 without cache** (OpenAI's opportunistic cache may help but not modeled here):

Input: 1M × 2,000 / 1M = 2,000M tokens × $5/1M = $10,000. Output: 1M × 500 / 1M = 500M tokens × $30/1M = $15,000. **Total: $25,000/month**.

**After — Claude Sonnet 4.6 without cache**:

Input: 2,000M × $3/1M = $6,000. Output: 500M × $15/1M = $7,500. **Total: $13,500/month** — a 46% saving even without caching.

**After — Claude Sonnet 4.6 with explicit caching** (1-hour TTL on 1,500-token prefix, 90% cache hit rate):

Cache writes: 0.1M (cache miss) × 1,500/1M × $6 = $900. Cache reads: 0.9M × 1,500/1M × $0.30 = $405. Non-cached input portion (500 remaining tokens × 1M) = 500M × $3/1M = $1,500. Output: $7,500. **Total: $10,305/month** — a 59% saving vs OpenAI.

**Annual delta**: $25,000 × 12 - $10,305 × 12 = $300,000 - $123,660 = **$176,340/year saved** on this workload.

Important caveat: gpt-5.5 → Sonnet 4.6 is the high-leverage migration. gpt-5.4 → Sonnet 4.6 actually *costs more* per call ($3 input vs $2.50). gpt-5.4-mini → Haiku 4.5 also costs more (+33% input). At the small / nano tier, OpenAI wins on price. Migrate the premium and mid tiers; keep the small and nano tier on OpenAI. The cost-delta calculator becomes per-workload, not per-organization.

**Eval parity first**. Run both providers on your held-out eval set before cutting over. The same prompt restructured for Claude should match or beat the GPT baseline; if it doesn't, you have a prompt problem, not a model problem.

**Shadow traffic for one week**. Route 5-10% of production traffic to Claude alongside OpenAI, log both outputs, compare quality. Catch silent regressions before they ship to users.

**Set up your monitoring before cutover**. Token counts, latency, error rates, cache hit ratio. The cache hit ratio is the metric that determines whether your migration math holds in production — track it explicitly.

**Plan a rollback path**. Feature-flag the model choice in your code; flip back to OpenAI in seconds if quality drops. Don't rip OpenAI out of your dependency list on day 1 of the cutover.

**Communicate to users only when relevant**. Most user-facing AI features don't need to advertise model changes. Internal tools might (developers care which model is suggesting their code).

Both APIs stream tokens. The event shape is different enough that naïve copy-paste of streaming code fails subtly. OpenAI streams a flat sequence of `chunk.choices[0].delta.content` strings; Claude streams structured events with explicit start/delta/stop boundaries on each content block.

OpenAI streaming pattern:

```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="") ```

Claude streaming pattern:

```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="") ```

The `text_stream` helper on Claude flattens the structured events into a plain string stream — most production code uses it. If you need finer control (e.g., handling tool_use blocks mid-stream, surfacing reasoning content separately), drop down to the event-level API and pattern-match on `event.type`.

Tool-use streaming is meaningfully different on Claude. Tool input JSON streams as partial JSON deltas inside `content_block_delta` events with `delta.type === 'input_json_delta'`. Naïve string concatenation works but you need to wait for the `content_block_stop` event before parsing the full JSON. OpenAI's streaming tool calls have a similar partial-JSON pattern; the field names differ.

**Mistake 1: assuming Claude is cheaper without checking the tier.** Sonnet 4.6 vs gpt-5.4 is roughly even, and Haiku 4.5 is actually *more expensive* than gpt-5.4-mini. The savings come from the premium tier (Opus 4.8 vs gpt-5.5-pro) and the mid-tier with caching (Sonnet 4.6 + 1-hour cache vs gpt-5.5).

**Mistake 2: copying prompts verbatim.** Markdown structure works on Claude but XML-tag structure works better. Skipping the prompt restructure leaves quality on the table.

**Mistake 3: skipping explicit cache breakpoints.** The 'Claude is cheaper' claim depends on caching. Without explicit breakpoints, you may pay more per call than the OpenAI equivalent. Set up caching as part of the migration, not as a follow-up.

**Mistake 4: not handling parallel tool calls.** Claude returns multiple `tool_use` blocks per turn when it makes parallel tool calls. Your tool runner needs to handle them concurrently and return all results in one user message.

**Mistake 5: keeping `max_tokens` set to OpenAI defaults.** Claude requires `max_tokens` to be explicit. Old code that relied on OpenAI's default (model max) needs to set a real ceiling — typically 500-2,000 for chat use cases. Don't set it too high; you'll pay for output you don't need.