Draft
Switch an OpenAI Agents SDK App from One Model Provider to Another Without Breaking Tools
Task
What you will complete
After switching model/provider, tools and handoffs still work, proven with tests.
Success criteria
- The application uses the new provider without a rewrite of its tool definitions.
- The same tests that cover tools and handoffs pass after the switch.
- The evidence section can show the test output and the pinned SDK and model versions.
What this is not
Not a guide to choosing a model, and not a rewrite of the application's tools.
Prerequisites
- A working OpenAI Agents SDK application whose tools and handoffs are already covered by tests.
- Credentials for the provider you are switching to.
- A test command you trust more than a manual chat transcript.
Environment
Not recorded. A verified revision will list the operating system, the tool builds, and the model identifiers that were present for the run.
1. Freeze the current provider and the tests
Record the provider, the model id, and the test command that already covers tools and handoffs. Run that command once before the switch so you know which failures are new. Save the output. This draft does not include a copy of it.
2. Switch the provider in one place
Change the model provider without rewriting tool definitions or handoff targets. The sketch below is only a reminder of the diff the verified page will show. It is not application source, and it has not been run.
const before = { provider: "current-provider", model: "current-model" };
const after = { provider: "next-provider", model: "next-model" };
3. Keep tools and handoffs pointed at the same behavior
Leave tool names, parameters, and handoff targets as they were. If the new provider needs a different model id inside a handoff, that change belongs in the verified diff, with a test that fails when the handoff does not arrive.
4. Run the same tests
Run the command from the first step again. A passing chat is not the result this page is for. The result is the test output.
Planned command. Not run for this draft.
# The verified page will name the package manager and paste the passing output.
npm test
5. File the proof with the versions
The evidence section needs the before and after provider settings, the pinned SDK and model versions, and the test output. None of that is recorded yet.
Evidence it actually ran
This is the shape of the stamp. It has not been earned, and the example date that follows is a placeholder, not a run: Ran on YYYY-MM-DD (Asia/Shanghai) with the pinned versions.
- Command output
- None recorded. A verified revision will quote the output from the run, not a sample written in advance.
- Tests, CI, or Inspector
- Not run for this draft.
- Repository or config
- No link recorded.
Failure modes
Anticipated only. None of these has been checked against a run of this tutorial.
Unchecked
The new provider accepts the request and drops a tool call
A successful model response is not proof that the tool ran.
Unchecked
A handoff targets a model id the new provider does not have
The handoff can be configured and still never arrive.
Unchecked
Tests pass against mocks and miss the provider change
A green run that never leaves the test double does not prove the switch.
Related
Other tutorials in Migrate.
Migrate a Working Claude Code Setup (CLAUDE.md, Hooks, and MCP) to Cursor
Migrate a working CLAUDE.md, hooks, and MCP config to equivalent Cursor behavior and re-test the same task.
Not yet verified
1 min read
Switch an Existing OpenAI Client to Qwen4-Max Without Rewriting It
Point an existing OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages client at qwen4-max on Beijing Model Studio by changing only the key, base URL, and model, with 免费额度用完即停 / Free Quota Only turned on, then confirm one request with a local check.
Not yet verified
15 min read