Clade migration deep dive

Migrate from OpenAI to Anthropic

Overview

Migrate from OpenAI/GPT to Anthropic/Claude. Covers the complete API mapping (endpoints, models, response shapes), SDK swap with before/after code, five key differences (max_tokens required, system as top-level param, alternating messages, response path, streaming events), and tool use migration.

API Mapping

OpenAI	Anthropic	Notes
openai.chat.completions.create()	anthropic.messages.create()	Different request/response shape
model: 'gpt-4o'	model: 'claude-sonnet-4-20250514'	Different model IDs
response.choices[0].message.content	response.content[0].text	Different response path
system in messages array	system as separate parameter	Claude uses top-level system
response_format: { type: 'json_object' }	System prompt: "Respond in JSON only"	No native JSON mode
tools / function_calling	tools (similar but different schema)	Input schema differences
openai.embeddings.create()	N/A — use Voyage or Cohere	No embeddings API

SDK Swap

Instructions

Step 1: Before (OpenAI)

import OpenAI from 'openai';
const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Hello' },
  ],
});
console.log(response.choices[0].message.content);

Step 2: After (Anthropic)

import Anthropic from '@claude-ai/sdk';
const anthropic = new Anthropic();

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024, // Required (not optional like OpenAI)
  system: 'You are helpful.', // Separate from messages
  messages: [
    { role: 'user', content: 'Hello' },
  ],
});
console.log(response.content[0].text);

Key Differences

1. max_tokens is required — OpenAI defaults it, Anthropic requires it
2. system is a top-level param — not a message in the array
3. First message must be user — can't start with assistant
4. Messages must alternate — no two user or two assistant messages in a row
5. Response shape — content[0].text not choices[0].message.content
6. Streaming events — different event types and structure

Tool Use Migration

// OpenAI tool definition
{ type: 'function', function: { name: 'get_weather', parameters: { ... } } }

// Anthropic tool definition
{ name: 'get_weather', input_schema: { ... } }  // Flatter structure

Grep & Replace

# Find all OpenAI imports
grep -rn "from 'openai'" --include="*.ts" .
grep -rn "import OpenAI" --include="*.ts" .

# Find response access patterns to update
grep -rn "choices\[0\]" --include="*.ts" .
grep -rn "message.content" --include="*.ts" .  # May need updating

Output

• All openai imports replaced with @claude-ai/sdk
• Response access patterns updated (choices[0].message.content → content[0].text)
• System prompts moved from messages array to top-level system parameter
• max_tokens added to all API calls (required, not optional)
• Tool definitions restructured to Anthropic format

Error Handling

Error	Cause	Solution
API Error	Check error type and status code	See clade-common-errors

Examples

See API Mapping table, Before/After SDK code, Key Differences list, Tool Use Migration, and Grep & Replace commands above.

Resources

• Anthropic Messages API
• Migration Guide

Next Steps

See clade-sdk-patterns for production Anthropic SDK patterns.

Prerequisites

• Existing OpenAI integration to migrate
• Access to codebase with search capability
• Test suite for comparing outputs between providers