An AI workflow migration is complete when the new system can carry out the intended business operation with the right data, authority and recovery behavior. A code export is useful evidence of the implementation. It does not, by itself, prove that customer files, pending approvals, background jobs or external writes will survive the move.
That distinction is urgent for some teams. As of November 4, 2026, OpenAI schedules Agent Builder shutdown for November 30, 2026. ChatKit remains available. The Evals platform and reusable prompt objects have separate entries on the same deprecations page; this is not an announcement that all OpenAI APIs are closing.
OpenAI's Agent Builder migration guide provides an Agents SDK export path and says the process does not convert the workflow graph or guarantee unchanged behavior. For a SaaS owner, the next question is concrete: what must still work when a customer resumes yesterday's unfinished task?
This guide answers that through a synthetic document-to-task workflow, a runnable local contract exercise, and a migration evidence worksheet. The engineering checks apply beyond Agent Builder. The provider instructions and dates need rechecking when you act.
First, define what is actually moving
“Switching AI providers” can describe four different changes. Name yours before estimating the work.
| Change | What may stay in place | What needs a new proof |
|---|---|---|
| Model replacement | Application, storage, orchestration and tools | Output quality, tool selection, schema handling, latency and cost |
| API or SDK migration | Business process and some infrastructure | Request/response mapping, streaming, errors, tool calls and state references |
| Orchestrator replacement | Models and external systems | Branching, retries, approvals, schedules and resumable execution |
| Hosted workflow exit | Possibly only your exported code and source documents | Runtime, configuration, data access, state, operations and the customer integration |
A common adapter can reduce repetitive code. It cannot establish equivalent tool behavior, recreate a hosted index or authorize a user. Likewise, two endpoints accepting similar JSON does not show that an interrupted operation can resume between them.
For the first cutover, keep unrelated changes small. Moving the orchestrator, changing the model, rewriting prompts and rebuilding retrieval together makes a regression harder to locate. Some combinations are unavoidable; record them as separate changes with separate acceptance checks.
What a code export does—and does not—prove
Do not assume a particular export omits every item below. Inspect the actual artifact, run it, and classify each dependency as present and verified, rebuild required, or not verified. An ID in source code may refer to an object that still lives only in the old account.
| Dependency | Inspect in the export | Recreate or transfer if needed | Acceptance evidence |
|---|---|---|---|
| Instructions and schemas | Full instructions, variables, structured outputs, defaults | Versioned prompt content and schema validation | Representative and invalid inputs take the intended path |
| Control flow | Branches, handoffs, loops, stop conditions | Explicit state transitions and bounded retry behavior | Every material branch, including refusal and tool failure, is exercised |
| Models and tools | Model identifiers, SDK versions, tool names and argument contracts | Supported configuration and tool adapters | Expected tool calls, rejected arguments and compatible results |
| Identity and authority | Where user, tenant and service identity enter execution | Server authentication, tenant mapping, scopes and credential ownership | Another tenant is refused; revoked access blocks a later write |
| Files and retrieval | File/index references and any bundled source material | Authorized documents, metadata, access filters and index configuration | Counts/checksums, permitted retrieval and denial of excluded documents |
| Conversations and jobs | History, checkpoints, cursors and state schema | A defined mapping or an explicit restart/manual policy | A sampled pending job reaches its correct next state |
| Approvals | Pending decisions and the exact action they authorize | Server-owned approval records, expiry and replay protection | Changed input or expired authority requires a new decision |
| Schedules and triggers | Webhook endpoints, cron definitions and event contracts | Trigger ownership, timezone, missed-run and deduplication rules | Deploy/restart does not create a second business operation |
| Evaluations | Fixtures, rubrics, graders and baseline results | A runnable comparison independent of the retiring dashboard | Reviewed results against a frozen dataset and acceptance criteria |
| Operating limits | Timeouts, retries, quotas, budgets and alert destinations | Enforced ceilings and an owned failure queue | Slow, expensive and exhausted runs stop visibly and recover safely |
For retrieval, retain the source documents and their permissions, then decide whether the target can use the existing index. A rebuild needs its own retrieval comparison. Matching vector dimensions alone is insufficient evidence that embeddings from different models are interchangeable.
Retention also needs a separate inventory. OpenAI documents different storage behavior for responses, conversations, files and vector stores in its data controls guide. Check each object type and the destination's rules. A successful code export does not establish that data was copied, that you have authority to move it, or that old copies were deleted.
A migration example: document, proposal, approval, task
Consider a B2B SaaS feature: a customer uploads a delivery document, AI proposes a follow-up task, a reviewer approves it, and the application creates that task in an external system.
This is an invented teaching scenario, not a client case. The contract is intentionally narrow:
- The job belongs to one tenant and one document revision.
- The proposal is reviewable; generating it creates no external task.
- Approval binds the exact proposed action and relevant workflow version.
- Current authority is checked again before execution.
- Repeated delivery refers to the same business operation.
- Completion requires an external receipt. An uncertain result remains uncertain until reconciled.
- If AI is unavailable, an authorized person can review and submit the task through the same controlled execution path.
The portable unit is the pending business operation: its input, authority, decision and receipt—not just the model conversation.
Preserve an operation record outside the model
Give the job a stable application ID before requesting a proposal. Store its tenant, source document revision, workflow/configuration version, proposed action, approval record, execution status and external receipt in application-controlled storage. Preserve the initiator, reviewer and executing service identity separately where they differ.
The model may help produce the proposal. It should not choose the tenant, grant its own authority or declare that an external write succeeded. Treat uploaded content as untrusted: a document saying “ignore the approval step” must not change application policy.
Keep approval state on the server. The Agents SDK human-in-the-loop guide distinguishes resumable run state from application authorization and warns that deserializing state does not authenticate its sender. Loading a serialized checkpoint is not permission to execute it.
For a long pause, recheck both sides of the decision: does the reviewer still have authority, and is this still the action they reviewed? A changed recipient, document revision or tool meaning can require fresh approval even if the old record says approved.
Separate approval from execution and completion
Use states with observable meanings, for example:
awaiting_review → approved → executing → completed
Also define rejected, expired, manual_required and uncertain. The last state matters when the external system created the task but your worker lost the response. Blindly retrying with a new operation ID can create a duplicate. Reporting failure as though nothing happened is equally misleading.
Use a stable idempotency key for the business operation across old and new runtimes, within the destination API's supported scope and retention window. Verify its behavior with concurrent requests and changed parameters. AWS's idempotent API guidance explains why request intent, late arrivals and parameter mismatches matter; a retry key is a contract, not a universal guarantee.
Persist the local transition and the intent to dispatch through a transaction/outbox or another recoverable protocol. The transactional outbox pattern addresses the gap between a database update and notification, while still requiring duplicate-safe consumers. It does not make an arbitrary external task API transactional with your database.
Run the contract exercise before connecting a model
Download contract-demo.mjs, inspect it, and run it locally with Node.js 20 or later:
node --test contract-demo.mjs
No packages, API key or network connection are needed. The file uses synthetic records, a fake task API and Node's test runner. It maps an application job envelope from schema 1 to schema 2 while retaining the same approved business workflow. It does not parse an Agent Builder export or call an AI model.
The published exercise was run on November 4, 2026: 9 tests passed, 0 failed.
| Test | Expected observation |
|---|---|
| Original versus migrated envelope | The same approved task payload reaches separate fake destinations |
| Another tenant attempts approval or execution | Both are refused; no external record exists |
| Concurrent duplicate attempts | The fake API returns one task for the shared operation key |
| Reviewer's role is revoked after approval | The eventual write is refused |
| Document revision changes after approval | The old approval no longer matches |
| Approval expires during a pause | Resumed execution is refused |
| External write succeeds but the response is lost | Job becomes uncertain; receipt reconciliation completes it without another create |
| Pending review crosses the cutover | It stays pending; an old worker epoch is refused |
| AI is unavailable | Manual review uses the same operation and receipt path |
These results prove the exercise's assertions against its fakes. They do not prove model quality, document extraction, retrieval isolation, authentication, durable storage, actual SDK checkpoint compatibility or distributed worker safety. In particular, the toy epoch check is not a production distributed lease: real stale workers need enforcement at the write boundary. Its fake API supplies idempotency; your actual destination may not.
Use the exercise to specify tests for your application. Replace assumptions with real integration evidence before declaring those rows passed.
Then evaluate the AI behavior separately
Keep a frozen set of authorized, sanitized or synthetic documents with expected facts, acceptable actions, refusal cases and examples that require manual review. Compare the old and new implementations using that same set. Review structured fields, source references, tool choices and downstream actions rather than demanding identical prose.
Include documents with missing dates, conflicting instructions, misleading embedded text and no actionable content. Test invalid structured output, model refusal, timeout and an unavailable tool. A schema-valid task can still have the wrong date or come from the wrong document.
Set acceptance criteria before looking at the new results. For this scenario, another tenant's document or an unapproved external write is a blocker, even if the summaries otherwise look excellent. Define quality, latency and cost thresholds from your product's needs; there is no universal passing percentage.
Measure the full operation cost, including retrieval, model/tool loops, retries and recovery. A cheaper individual model call can still produce a more expensive completed task. Enforce limits per job and tenant, cap retry/fan-out behavior, and keep exhausted work visible to an operator.
Agent Builder migration: choose the destination by the user journey
For the documented export, open your existing Agent Builder workflow, select Code → Agents SDK, choose TypeScript or Python, and retain the complete output. Then configure and test it in the target runtime. Preserve a dated copy of the source configuration and available fixtures while you still have access.
The migration guide also describes recreating a ChatGPT Workspace Agent for eligible workspaces. That can suit a team using an internal assistant. A customer-facing SaaS still needs its own customer identity, tenant boundaries, application UI and operating contract. Treat these as different destination designs rather than assuming one replaces the other.
If the product uses ChatKit, inspect what the frontend connects to. ChatKit remaining available does not keep a retiring Agent Builder workflow running. OpenAI's ChatKit guide directs migration planning toward a custom server integration with your own server-side implementation.
Exporting into code also moves operating work to your team or hosting provider: deploying the runtime, owning credentials, persisting state, monitoring failures and maintaining dependencies. Account for that work when comparing destinations.
Cut over without losing unfinished work
Compare freely in an isolated environment. In production, every external write needs a clear execution owner.
1. Inventory and freeze the baseline
Record the running application revision, workflow export, prompts, tool schemas, model configuration, data/index references, authentication scopes, event producers, workers and schedules. Identify who owns each account and the deadline for each dependency. An inaccessible production configuration is an unresolved migration dependency.
2. Reproduce the workflow in isolation
Use separate credentials and synthetic or approved test data. Stub external writes before replaying historical input. Match required configuration deliberately; a local success with broader permissions is weak evidence for a restricted production runtime.
Do not enable tracing that sends customer documents to a new destination by accident. Review logs, traces and retained checkpoints as data stores too.
3. Compare behavior without duplicating effects
Run contract tests and AI evaluations separately. If you use shadow traffic, route the comparison's write tools to a recorder or sandbox. A “shadow” worker connected to a real task system can still create real tasks.
Read-only comparisons can also incur cost or expose data. Authorize their data scope and cap their workload.
4. Assign every pending operation a disposition
Take a cutover inventory grouped by state and age. For each job, choose finish on the old runtime, map and resume on the new runtime, restart from safe input with fresh approval, or route to manual recovery. Record the decision and owner. Do not silently reset every job to “new.”
Separate unresolved external outcomes from jobs that never started. Compare local records against destination receipts before replay. Reconcile counts and individual exceptions: every source job needs a mapped destination or an explained disposition.
If SDK checkpoints cannot be restored in the target, migrate the application operation envelope only through a reviewed mapping. Reconstructing a proposal is different from executing an already approved action. Preserve the old evidence and request a new decision when the meaning changes.
5. Switch a bounded cohort with one execution owner
Route a defined tenant cohort or operation type to the new path. Coordinate frontend, backend and worker versions. Stop or drain the old consumers for that scope, account for leased/in-flight work, and verify that old webhook subscriptions and schedules cannot keep writing.
Use atomic claims, shared deduplication and fencing appropriate to the real replica topology. A flag checked only by the web frontend does not stop a background worker. Set stop conditions for unauthorized actions, duplicates, missing receipts, backlog growth, quality regressions and cost overruns.
6. Accept operations, then retire the dependency
Check actual completed outcomes and the exceptions queue. Confirm alert recipients, recovery access, credential rotation and the person responsible for stuck work. Expand only after the bounded cohort meets the agreed criteria.
Retain the required evidence and data under an explicit policy. Stop old triggers and remove access when dependencies allow. Deactivation, archival and deletion are different actions; verify the intended result for each service.
Rollback has an expiration date
A rollback plan works only while the old service remains available and can understand the current data. Reverting application code does not undo an external task, restore a deleted file or make a retired hosted workflow run again.
Before the cutoff, rehearse which cohort can return to the old path and how new-format records will be handled. After the cutoff, define a continuation path you control: pause automated writes, retain accepted work, expose honest status and let an authorized operator complete or repair it. Keep duplicate protection across that manual path.
If the wider application also needs structural change, use the rewrite, refactor or replatform decision model to scope it. The vendor deadline alone is not evidence that the whole SaaS needs a rewrite.
Keep a migration evidence pack
Use the CSV worksheet for each dependency. It starts with NOT VERIFIED statuses so an empty evidence field cannot look like a pass.
| Field | What to record |
|---|---|
| Dependency and owner | Exact service/object and the person accountable for it |
| Source version | Application revision, workflow/configuration version and capture date |
| Available export | What you actually obtained and where the controlled copy lives |
| Reconstruction | Mapping, rebuild, restart or manual continuation decision |
| Acceptance check | Observable expected result, including failure/repeat behavior |
| Evidence | Test output, sanitized trace, receipt comparison or restore record |
| Status and blocker | PASS, FAIL or NOT VERIFIED; next action and owner |
Keep secrets, full approval snapshots and customer documents out of a public worksheet. Link to access-controlled evidence where needed. A row passes only for the version and environment exercised. The local demo does not fill in your production rows.
Frequently asked questions
Can I migrate an AI workflow by changing the API key or base URL?
Sometimes that changes how a model request is routed. It does not establish tool compatibility, transfer hosted state, remap identity or preserve pending operations. Start with the dependency inventory, then test the exact behavior your product relies on.
Do we need exactly the same AI output after migration?
Usually the useful target is equivalent acceptable behavior: correct extracted facts, permitted tool calls, preserved approval boundaries and an explainable outcome. Define where wording can vary and where a field, source reference or action must be exact.
Can pending approvals move to the new runtime?
Only with a verified state/authority mapping or supported checkpoint restoration. Test the exact source and target versions. If compatibility is unknown, retain the operation record and use an explicit reapproval or manual continuation path instead of assuming serialized state will work.
Does this checklist prove the migrated feature is production-ready?
It supplies migration-specific evidence. It does not replace the surrounding review of security, privacy, recovery, capacity and support. Use the 12-gate production audit for that broader baseline and add the requirements of your own product.
If an AI workflow is embedded in a live SaaS, the move often belongs inside application modernization: establish the current behavior, replace a bounded dependency and prove continuity. After the move, application maintenance keeps provider changes and operational fixes in the release process.
Describe the workflow you need to move, the platform deadline and what happens when it fails. Share a high-level dependency list; keep credentials, customer documents and private exports out of the contact form.
Sources and provider timelines reviewed November 4, 2026. The nine-test exercise is original synthetic teaching material. No real provider migration, model benchmark or customer outcome is claimed.
