Moving Off the Assistants API Without Breaking Production

The migration that goes badly is always the ambitious one. A team decides that since they are rewriting the integration anyway, they may as well adopt every new capability at the same time — and then spends three weeks unable to tell whether a regression came from the platform change or from the redesign they smuggled in alongside it.

Preserve behavior first. Adopt capability second. Those are two separate projects and they should be two separate deploys.

Inventory before you architect

Write down what production actually does today: every assistant instruction, every stored file the system depends on, how thread state is created and cleaned up, every function schema, which streaming events the UI reacts to, and which dashboards someone checks when a customer complains. That inventory is your compatibility contract. Anything not on it is something you will discover during an incident.

Map concepts, do not assume names transfer

The temptation is to look for a one-to-one replacement for each object and stop thinking. Resist it. Conversation state may move into storage your application owns. A built-in tool may replace a wrapper you wrote and maintained. Tracing may become a platform feature instead of custom middleware. You are preserving outcomes and auditability — not the shape of the old abstractions.

• Record every instruction, tool schema, file dependency, and thread lifecycle in one document
• Build golden conversations with the expected tool calls and final outputs baked in
• Put an adapter behind a stable product interface so both implementations satisfy the same contract
• Run shadow traffic and compare quality, latency, cost, and failure recovery — all four
• Migrate stored state with a reversible cutover and a defined rollback window

Golden conversations are the whole safety net

Assemble a set of real conversations that cover the ordinary path, the tool-heavy path, the ambiguous request, the one where a tool fails, and the one where a customer changes their mind mid-thread. Capture the expected tool calls and final outputs from the current system. That set is what turns “it seems to work” into a claim you can defend at a go/no-go meeting.

Do not port your blind spots

If the old system could fail without telling you why, copying it faithfully preserves the debt and wastes the opportunity. A migration is the cheapest moment you will ever have to add trace IDs that survive an entire task, structured tool results instead of stringified blobs, explicit retry policies, and an eval suite. The marginal cost during a rewrite is small. The cost of adding it later, under production load, is not.

Retire the adapter on purpose

Compatibility layers are supposed to be temporary and almost never are. Set a removal date when you write it. Once traffic, stored state, and support runbooks have all moved, delete it, update the runbooks, and freeze the migration test set as a permanent regression suite. It will pay for itself the next time a model or tool changes underneath you.