Cross-Provider Model Handoffs

Switch between different LLM providers mid-conversation while preserving context and tool calls

Pi’s AI library supports seamless handoffs between different LLM providers within the same conversation. You can switch models mid-conversation while preserving context, including thinking blocks, tool calls, and tool results.

How It Works

When messages from one provider are sent to a different provider, the library automatically transforms them for compatibility:

• User and tool result messages are passed through unchanged
• Assistant messages from the same provider/API are preserved as-is
• Assistant messages from different providers have their thinking blocks converted to text with <thinking> tags
• Tool calls and regular text are preserved unchanged

This enables you to start with one model, then switch to another while maintaining conversation continuity.

Quick Example

import { getModel, complete, type Context } from "@mariozechner/pi-ai";

// Start with Claude
const claude = getModel("anthropic", "claude-sonnet-4-20250514");
const context: Context = { messages: [] };

context.messages.push({ role: "user", content: "What is 25 * 18?" });
const claudeResponse = await complete(claude, context, {
  thinkingEnabled: true
});
context.messages.push(claudeResponse);

// Switch to GPT-5 - it will see Claude's thinking as <thinking> tagged text
const gpt5 = getModel("openai", "gpt-5-mini");
context.messages.push({ role: "user", content: "Is that calculation correct?" });
const gptResponse = await complete(gpt5, context);
context.messages.push(gptResponse);

// Switch to Gemini
const gemini = getModel("google", "gemini-2.5-flash");
context.messages.push({ role: "user", content: "What was the original question?" });
const geminiResponse = await complete(gemini, context);

With Pi SDK

Use cross-provider handoffs in Pi sessions:

Use Cases

Fast to Capable

Start with a fast model for initial responses, then switch to a more capable model for complex reasoning:

// Quick initial scan with Haiku
const haiku = getModel("anthropic", "claude-haiku-4-5");
const { session } = await createAgentSession({ model: haiku });
await session.prompt("Find all authentication code");

// Deep analysis with Opus
const opus = getModel("anthropic", "claude-opus-4-5");
await session.setModel(opus);
await session.prompt("Analyze these files for security vulnerabilities");

Specialized Models

Use specialized models for specific tasks:

// Code generation with Codex
const codex = getModel("openai-codex", "gpt-5-codex");
const { session } = await createAgentSession({ model: codex });
await session.prompt("Implement the OAuth flow");

// Code review with Claude
const sonnet = getModel("anthropic", "claude-sonnet-4-5");
await session.setModel(sonnet);
await session.prompt("Review the implementation for best practices");

Failover

Maintain conversation continuity across provider outages:

try {
  await session.prompt("Continue the refactoring");
} catch (error) {
  if (error.message.includes("rate limit")) {
    // Switch to backup provider
    const backup = getModel("google", "gemini-2.5-flash");
    await session.setModel(backup);
    await session.prompt("Continue the refactoring");
  }
}

Cost Optimization

Use cheaper models for simple tasks:

// Cheap model for simple queries
const haiku = getModel("anthropic", "claude-haiku-4-5");
const { session } = await createAgentSession({ model: haiku });
await session.prompt("List all test files");

// Expensive model only when needed
const opus = getModel("anthropic", "claude-opus-4-5");
await session.setModel(opus);
await session.prompt("Generate comprehensive test coverage");

Context Serialization

The Context object can be serialized for persistence or transfer:

import { type Context, getModel, complete } from "@mariozechner/pi-ai";

// Create and use a context
const context: Context = {
  systemPrompt: "You are a helpful assistant.",
  messages: [
    { role: "user", content: "What is TypeScript?" }
  ]
};

const claude = getModel("anthropic", "claude-sonnet-4-5");
const response = await complete(claude, context);
context.messages.push(response);

// Serialize the entire context
const serialized = JSON.stringify(context);

// Save to database, localStorage, file, etc.
localStorage.setItem("conversation", serialized);

// Later: deserialize and continue with any model
const restored: Context = JSON.parse(localStorage.getItem("conversation")!);
restored.messages.push({ role: "user", content: "Tell me more about its type system" });

const gpt5 = getModel("openai", "gpt-5-mini");
const continuation = await complete(gpt5, restored);

If the context contains images (encoded as base64), those will also be serialized.

Provider Compatibility

All providers can handle messages from other providers:

Content Type	Compatibility
Text content	✓ Fully compatible
Tool calls	✓ Fully compatible
Tool results (text)	✓ Fully compatible
Tool results (images)	✓ Fully compatible (for vision models)
Thinking blocks	✓ Converted to tagged text for cross-provider
Aborted messages	✓ Partial content preserved

Thinking Block Conversion

When switching providers, thinking blocks are transformed:

Same Provider

Thinking blocks are preserved as-is:

// Claude → Claude
const sonnet = getModel("anthropic", "claude-sonnet-4-5");
const response = await complete(sonnet, context, { thinkingEnabled: true });
// response.content contains { type: "thinking", thinking: "..." }

// Send to another Claude model
const opus = getModel("anthropic", "claude-opus-4-5");
context.messages.push(response);
await complete(opus, context);
// Opus sees the thinking block natively

Different Providers

Thinking blocks are converted to tagged text:

// Claude → GPT-5
const sonnet = getModel("anthropic", "claude-sonnet-4-5");
const response = await complete(sonnet, context, { thinkingEnabled: true });
// response.content contains { type: "thinking", thinking: "Let me calculate..." }

// Send to GPT-5
const gpt5 = getModel("openai", "gpt-5-mini");
context.messages.push(response);
await complete(gpt5, context);
// GPT-5 sees: "<thinking>Let me calculate...</thinking>"

Aborted Messages

Aborted messages can be added to the conversation context and continued:

const controller = new AbortController();
setTimeout(() => controller.abort(), 2000);

const partial = await complete(model, context, { signal: controller.signal });
// partial.stopReason === "aborted"
// partial.content contains partial text/tool calls

// Add to context and continue with different model
context.messages.push(partial);
context.messages.push({ role: "user", content: "Please continue" });

const continuation = await complete(differentModel, context);

Best Practices

Example: Multi-Stage Workflow

Here’s a complete example showing a multi-stage workflow with different models:

import { getModel } from "@mariozechner/pi-ai";
import {
  createAgentSession,
  AuthStorage,
  ModelRegistry,
} from "@mariozechner/pi-coding-agent";

const authStorage = AuthStorage.create();
const modelRegistry = new ModelRegistry(authStorage);

// Stage 1: Fast scan with Haiku
const haiku = getModel("anthropic", "claude-haiku-4-5");
const { session } = await createAgentSession({
  model: haiku,
  authStorage,
  modelRegistry,
});

console.log("Stage 1: Quick scan with Haiku");
await session.prompt("Find all authentication-related files");

// Stage 2: Deep analysis with Sonnet + thinking
const sonnet = getModel("anthropic", "claude-sonnet-4-5");
await session.setModel(sonnet);
session.setThinkingLevel("high");

console.log("Stage 2: Analysis with Sonnet + thinking");
await session.prompt("Analyze these files for security vulnerabilities");

// Stage 3: Implementation with GPT-5 Codex
const codex = getModel("openai-codex", "gpt-5-codex");
await session.setModel(codex);

console.log("Stage 3: Implementation with Codex");
await session.prompt("Implement fixes for the vulnerabilities found");

// Stage 4: Review with Opus
const opus = getModel("anthropic", "claude-opus-4-5");
await session.setModel(opus);

console.log("Stage 4: Final review with Opus");
await session.prompt("Review the implementation for correctness");

console.log("Workflow complete!");

Next Steps

• See Programmatic Usage for SDK basics
• See Building Extensions for custom tools
• See Custom Providers for adding new providers