How to Switch AI Providers Without a Rewrite
The HTTP call is twenty lines. Tool schemas, stream shapes, finish reasons and token accounting are the real cost, and a thin adapter should wrap exactly those.
You can switch AI providers without rewriting your app, but only if you make a few decisions before you need to. The HTTP call is never the problem. About twenty lines of it change. What costs you a fortnight is everything shaped around the call, and there are exactly four things in that category.
What actually locks you in
Not the endpoint. These four:
Tool call schema. How you describe a function to the model, and how the model hands back a call, differ in field names and nesting between providers. Compare one provider's function calling reference with another's tool use overview and the concepts match while almost no key names do.
Streaming event shape. Event names, whether text arrives as deltas or cumulative snapshots, and how tool calls are chunked mid-stream. This is where naive adapters break, because the happy path looks identical and the partial-tool-call path does not.
Finish and refusal reasons. One provider's
stopis another'send_turn. Length cutoffs, content refusals and tool-call pauses all arrive as different strings, and your retry logic is almost certainly branching on them.Token accounting and cache semantics. Where usage numbers appear in the response, whether cached tokens are reported separately, and what counts as a cache hit. Your cost dashboard quietly lies after a switch if you do not map this.
Everything else people worry about, context limits and model names and temperature ranges, is configuration. These four are code.
The thin adapter
Write one interface that your app calls, and let exactly one file per provider implement it. The interface should be boring and narrow:
type FinishReason = "stop" | "length" | "tool_call" | "refused";
interface ModelReply {
text: string;
toolCalls: { id: string; name: string; args: unknown }[];
finishReason: FinishReason;
usage: { inputTokens: number; cachedInputTokens: number; outputTokens: number };
}
interface Provider {
name: string;
generate(req: {
system: string;
messages: { role: "user" | "assistant"; content: string }[];
tools?: { name: string; description: string; schema: unknown }[];
maxOutputTokens: number;
}): Promise<ModelReply>;
}The important part is not the shape, it is the FinishReason union. You define your own four values and each adapter maps the provider's strings onto them. Your application never sees a vendor's vocabulary, so a switch cannot leak into your retry logic. Same for usage: normalise to your three numbers and your cost reporting survives the move.
Keep the adapter under a hundred lines per provider. If it grows past that, you are abstracting things you should not be.
What not to abstract
Do not build a universal prompt layer. Prompts tuned for one model genuinely perform differently on another. Store the variants as data, keyed by provider, and keep them in version control next to your evals. Branching code is the wrong tool.
Do not abstract a feature only one provider has. If you want a capability that exists in one place, use it directly and accept that path is provider-specific. A fake abstraction over a unique feature is worse than an honest dependency.
Do not wrap structured output in your own validator theatre. Validate the parsed result against your schema and retry on failure. That logic is yours either way, and it is covered in getting JSON output from AI.
Prove it works before you need it
An adapter you have never exercised against a second provider is not portability, it is a hope. The drill:
Keep a golden set of twenty real requests, covering a plain answer, a tool call, a refusal, a length cutoff and a long input.
Run the set against your current provider and store the outputs.
Run the same set through the second adapter. You are not looking for identical text. You are checking that nothing threw, every
finishReasonmapped to one of your four values, tool calls parsed, and usage numbers came back populated.Put that run in CI on a schedule. Twenty requests is cents, and it catches the day a provider changes an event name.
That drill is also your outage plan. The same switch that saves you from a price rise saves you when a provider is down, which is the scenario in what to do when your AI provider is down.
How to switch AI providers without rewriting your app, step by step
Run the golden set against the new provider and read the diffs.
Fix the mapping gaps the run exposes, which is usually one finish reason and one usage field.
Write the provider-specific prompt variants for anything that scored badly.
Route a small share of live traffic to the new adapter and compare output quality and cost on real requests.
Move the remainder. Keep the old adapter in the codebase for a month, because reverting should be a config change.
Note what is not on that list: rewriting your app. If your product code never imported a vendor SDK type, the switch is an adapter plus prompt variants.
The mapping you will actually write
When people say the adapter was harder than expected, it is nearly always one of these four mappings, so write them down before you write code:
Finish reasons to your four values. Expect at least one provider string you did not anticipate, usually a content refusal or a tool-call pause. Map unknown strings to your
refusedvalue and log the raw string, rather than defaulting tostop. A silent default here turns a refusal into an empty but apparently successful answer.Tool arguments to a parsed object. Some providers hand you a JSON string, some an object, and some stream the arguments in fragments you must concatenate before parsing. Decide that your interface always returns a parsed object and make each adapter do the work.
Cached tokens into their own field. If a provider reports cached input inside the ordinary input count and another reports it separately, summing them the same way overstates one bill and understates the other. Keep
cachedInputTokensdistinct even when a provider reports zero.Stream fragments into one text value. Deltas and cumulative snapshots both arrive as a sequence of events. Appending a cumulative snapshot gives you every word repeated, which is the classic first bug in a hand-written adapter.
What to watch during the parallel run
When you route a slice of live traffic to the new adapter, resist comparing answers side by side and arguing about which reads better. Measure four things instead:
Error and refusal rate per thousand requests, which exposes mapping gaps faster than reading output.
Share of responses that failed your own schema validation, which is the honest proxy for whether prompts transferred.
Median and ninety-fifth percentile latency, because a provider that is cheaper per token and slower per call can still cost you more in abandoned sessions.
Cost per completed task rather than per million tokens, which is the only comparison that accounts for retries.
Give it a week of real traffic. A provider comparison run for an afternoon tells you about an afternoon.
The lock-in nobody can adapt around
One honest caveat. All of this protects you at the model layer. It does nothing about a platform that owns your hosting, database and deploy pipeline, which is a heavier kind of dependency and a different decision, discussed in vendor lock-in with AI app builders. Model portability is cheap. Platform portability is not, and conflating the two is how people end up believing they are safe.
For where this sits in a wider build, see the guide to building an app with AI, and for the forced version of this exercise, what to do when an AI model gets deprecated.
Frequently asked questions
Should I use a routing library instead of writing an adapter?
A library is a reasonable shortcut, and it makes the same four mappings for you. The cost is that you inherit its opinion about finish reasons and usage, and you still need the golden-set drill to know it behaves. Write the drill either way.
Will my prompts work unchanged on a new provider?
Mostly, and the exceptions will be your most tuned prompts. Expect to rewrite the two or three where you squeezed out the last ten percent of quality, and expect the plain ones to transfer fine.
How often should I run the portability drill?
Monthly is enough, and cheap. The point is to find out that an event name changed from a scheduled job rather than from an incident.
How did this land?
About the author

Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.


