Draft

Switch an OpenAI Agents SDK App from One Model Provider to Another Without Breaking Tools

  • Not yet verified
  • Versions not pinned
  • 1 min read

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.

Other tutorials in Migrate.