Plan a Cross-Provider Migration

Inventory the real provider boundary

Find every conversational product, developer console, API and SDK version, credential path, model or alias, prompt, context builder, retrieval dependency, content part, conversation state field, tool schema and result, safety control, modality, file, cache, batch, evaluation, trace, dashboard, alert, quota, cost assumption, runbook, and support dependency.

For each dependency record the current owner, exact surface, source, data classification, business criticality, date last verified, failure effect, and observable proof. Include prototypes, shadow clients, scheduled jobs, experiments, fallback routes, and undocumented manual work.

Classify portable and provider-specific contracts

Keep user outcomes, domain input and output schemas, authorization policy, evaluation cases, trace identifiers, postconditions, incident rules, and rollback criteria application-owned where possible. Treat request shapes, message roles, content parts, tool-call protocols, finish states, safety settings, model controls, hosted tools, and preview features as provider-specific until proven otherwise.

Give every dependency one disposition: retain as portable, translate in an adapter, redesign intentionally, remove, mark unsupported, migrate data, or investigate. Record semantic loss and operational cost instead of hiding differences behind a shared method name.

Build a compatibility map

Map source behavior to candidate behavior for identity, API authentication, request and response types, streaming, errors, retries, context, state, structured output, tools, parallelism, safety, data handling, modalities, files, batches, evaluations, observability, quotas, latency, and cost.

Use current official migration, model, SDK, and deprecation sources for the exact products and interfaces. Label equivalent only after contract and behavior evidence; otherwise label adapter, redesign, unsupported, changing, or unknown with an owner.

Environment-only provider configuration

typescript

const providerConfig = {
  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY, model: process.env.ANTHROPIC_MODEL },
  openai: { apiKey: process.env.OPENAI_API_KEY, model: process.env.OPENAI_MODEL },
  google: { apiKey: process.env.GEMINI_API_KEY, model: process.env.GEMINI_MODEL },
};

for (const [provider, config] of Object.entries(providerConfig)) {
  if (!config.apiKey || !config.model) throw new Error(`Missing ${provider} environment configuration`);
}

Freeze a representative baseline

Version representative, edge, adversarial, multilingual, accessibility, safety, tool-failure, state-recovery, latency, and cost cases before evaluating a candidate. Capture trusted inputs, expected outcome, forbidden outcomes, rubric, critical slices, grader calibration, source version, and pass, hold, or rollback thresholds.

Run source and candidate through the same application contract and fixtures. Compare output quality, factuality, refusal and block behavior, structured-data validity, tool selection and arguments, side effects, state, latency, usage, cost assumptions, errors, and operator effort.

Choose a reversible migration shape

Select in-place adapter replacement, dual-run, offline replay, shadow, cohort canary, route-by-use-case, or a staged combination from the workflow's risk and data constraints. Define entry evidence, promotion gates, maximum exposure, stop authority, rollback objective, side-effect reconciliation, communications, and observation duration.

Create a decision record listing the selected approach, rejected options, compatibility gaps, evaluation results, data and safety review, capacity and cost assumptions, owners, dependencies, residual risks, acceptance authority, review date, and proof needed before implementation.

Practice activity

Create an evidence-backed migration plan

Inventory one workflow across products, SDKs, models, credentials, prompts, context, state, tools, safety, data, evaluation, observability, cost, and operations.
Create a compatibility map that assigns every dependency to portable, adapter, redesign, remove, unsupported, data migration, or investigate and links volatile claims to current official sources.
Build synthetic no-paid-call source and candidate fixtures for representative, edge, safety, tool-failure, accessibility, and state-recovery cases, then define slice-level pass, hold, and rollback thresholds.
Choose a migration shape and write entry criteria, promotion gates, exposure limits, stop authority, rollback objective, reconciliation requirements, observation window, and communications.
Submit the inventory, compatibility map, baseline specification, and decision record to an independent reviewer who must challenge one assumed equivalence or missing dependency.

What to produce

A sourced dependency inventory and compatibility map with owners, dispositions, unknowns, semantic-loss notes, and current lifecycle evidence.
A versioned fixture baseline and reviewed decision record containing migration shape, gates, rollback and reconciliation requirements, residual risks, and acceptance authority.

Reflect before continuing

Which dependency appeared portable until you traced its state, tool, safety, data, or operational semantics?

Plan a Cross-Provider Migration

You will be able to

Inventory the real provider boundary

Classify portable and provider-specific contracts

Build a compatibility map

Freeze a representative baseline

Choose a reversible migration shape

Create an evidence-backed migration plan

What to produce

Reflect before continuing

Sources and verification

Make it stick.