The shutdown notice does not mean every workflow will stop working today, and it does not mean every workflow can be moved with one export click. OpenAI's migration guide is precise: it exports an existing workflow as Agents SDK code that you can continue in an application or use to recreate a ChatGPT Workspace Agent. The process does not convert the workflow graph or guarantee identical behavior. That makes this a dependency and behavior migration, not just a deadline reminder.
This guide is a practical checklist for teams with published workflows, embedded ChatKit experiences, or app code that depends on a Builder workflow ID. It focuses on what to inventory, how to choose the migration target, how to test equivalence, and what to preserve so a cost or usage report still makes sense after the runtime changes.
What OpenAI has announced
OpenAI's current Agent Builder overview says existing users can continue using the product during a transition window and that shutdown is scheduled for November 30, 2026. It says ChatKit remains available. The separate migration guide tells users how to copy an Agents SDK export in TypeScript or Python, then either continue with that SDK in an application or recreate an agent in a ChatGPT workspace. The workspace option requires a ChatGPT Business, Enterprise, or Edu workspace with access to Workspace Agents.
Do not infer that an existing published Builder graph will keep executing just because ChatKit remains available. The announcement establishes the future of Agent Builder and the availability of ChatKit; it does not promise that every existing workflow ID, published version, or embedded integration will remain a supported deployment path. Confirm the precise behavior for your account and migration route with the current OpenAI Agent Builder notice and migration guide.
Inventory the dependency before exporting
Start with a register of every workflow, even the ones nobody remembers owning. Search application code, environment configuration, deployment manifests, and support notes for workflow IDs, ChatKit references, SDK packages, and workflow names. Ask product and operations owners to identify internal agents and test projects that do not live in the main application repository. Record an owner and destination for each one; an orphaned workflow without a decision is the easiest one to discover too late.
| Inventory field | Why it matters |
|---|---|
| Workflow ID, published versions, and owner | Shows which environments and teams depend on each Builder artifact. |
| Entry point and user population | Separates a public application agent from an internal team workflow. |
| Nodes, branches, and handoffs | Defines the control flow that an SDK or workspace agent must reproduce. |
| Tools, connected apps, and credentials | Exposes permission and authentication work that a code export cannot safely decide for you. |
| Inputs, outputs, and side effects | Creates a contract for regression tests and duplicate-action protection. |
| Trace graders, sample runs, and known failure cases | Gives the migration an observable baseline instead of relying on a quick demo. |
| ChatKit embeds, workflow IDs, and fallback screens | Shows where an application or browser will need a changed connection path. |
Keep a copy of the workflow export, relevant prompts, input examples, and screenshots or notes about graph behavior in version control or an approved archive. Do not put live secrets into the archive. Preserve permission boundaries and data-retention decisions alongside the workflow description, because a migration that accidentally broadens a tool's access is a security regression even if the generated answer looks right.
Choose the destination based on where the agent runs
Agents SDK in your application: choose this when the agent is part of a product you operate and you need application-level control over runtime, tools, authentication, deployment, and monitoring. The migration guide says to select Code, select Agents SDK, choose TypeScript or Python, and copy the complete export into your application. Then configure the matching SDK and validate the runtime before deployment. The exported code is a starting point: you own package versions, environment variables, scaling, and the permission checks around each tool.
ChatGPT Workspace Agent: choose this when the workflow is primarily an internal assistant for a supported Business, Enterprise, or Edu workspace and its access model belongs in that workspace. The migration guide describes pasting the exported code into a workspace agent creation flow and reviewing changes it identifies. Connected apps, authentication, publishing, and permissions require separate review. A workspace agent is not an automatic substitute for an end-user feature embedded in your public product.
ChatKit: OpenAI says ChatKit remains available. That is useful context for teams that already embed chat, but it should not replace a compatibility check. Map which part of your system is the user interface, which part executes the workflow, and which runtime owns the agent logic. Test your current integration against the destination OpenAI documents for your account before concluding that an existing Builder workflow can remain untouched.
Export in a way you can reproduce
- Open the workflow in Agent Builder while the account still has access.
- Use Code in the top navigation and select Agents SDK.
- Choose TypeScript or Python, then copy the complete export rather than a partial excerpt.
- Commit the export to the application's migration branch with its workflow ID, source version, export date, and intended destination in a short README or code comment.
- Review generated instructions, models, tools, input/output types, and orchestration logic against the existing graph and known traces.
- Install the matching SDK and pin the dependency according to the application's normal release process.
Make the export reproducible before making it production code. Record the exact SDK version and runtime, but do not assume the export itself freezes every remote dependency. A mutable model alias, external tool endpoint, secret, or connected app can still change behavior. Move secrets into the deployment's secret store, rotate any credential that was copied into an unsafe place, and make each tool's authorization decision in the application that invokes it.
Rebuild behavior, not just the visible graph
Translate every branch, trigger, handoff, and failure path into a testable behavior. A visual graph can make a decision boundary look simple while hiding the exact conditions for a transition. Write examples for normal input, ambiguous input, missing data, an unavailable tool, a permission denial, malformed output, and a user who changes their mind. For each example, record what the existing workflow should do and what must never happen.
Keep deterministic business rules outside a free-form model decision wherever possible. If a workflow approves a refund only below a defined amount, code the amount check in the business service and have the agent request the action. If it reads a customer record, the application should derive the customer identity from authenticated context rather than trusting a name or identifier spoken into the conversation. Tool schemas should be narrow, input validation should happen at the boundary, and side effects should use idempotency where a retry could repeat them.
OpenAI's migration guide warns that strong determinism at the core may not migrate faithfully to a Workspace Agent. That is a signal to keep explicit rules and authorization in your application or service instead of treating generated natural-language instructions as a substitute for enforcement. For code-hosted agents, use ordinary code review and tests for those rules. For workspace agents, inspect the configured capabilities and permissions and run representative preview inputs before creating the agent.
Set up a migration evaluation before the canary
Build a small evaluation set from existing traces and real edge cases. Include expected tool choice, required argument fields, allowed side effects, refusal conditions, and the final user-facing answer. Test with sanitized data. Compare old and new runtimes on task success, correct tool selection, latency, token usage, error rate, and operator review time. Do not compare only the prose of the final response; a plausible sentence can conceal a missing write or an unauthorized lookup.
Run tests in a development environment first, then staging. Where both runtimes can safely answer the same request, use shadow evaluation with side effects disabled on the shadow path. If an operation can send an email, update a record, trigger a payment, or change access, never replay it twice against real customer data just to compare agent answers. Provide mock tools, a no-op mode, or a recorded input fixture for that pass.
Define acceptance thresholds before the first canary. For example, require that all mandatory authorization cases pass, all required tools are called with schema-valid arguments, no forbidden side effect occurs, and response latency stays within the product's chosen limit. Treat a change in model output or cost as an explicit product decision. If the behavior differs, identify whether the cause is prompt interpretation, SDK orchestration, tool schema, model, or runtime configuration before expanding traffic.
Roll out with a rollback that still works after shutdown
Route a small, measurable group of internal or opted-in users to the new runtime. Keep the old path available during the transition while it is supported, but also create a fallback that does not require Agent Builder: a simpler application flow, a human handoff, a prior stable SDK implementation, or a clear temporary unavailable state. Verify your runbook by disabling the new path in staging. A rollback plan that says “switch back to Builder” is not a durable plan for a date when Builder may no longer be accessible.
Increase traffic only after the canary's tool outcomes, error handling, and user experience meet the thresholds. Keep the old workflow read-only for the time needed to compare logs, then remove stale workflow IDs and credentials from application configuration. Preserve approved exports and test fixtures for future incident review. Update support documentation and internal owner records so the next person knows which runtime is authoritative.
Plan the cutover early enough to handle a failed export, account-access problem, or workspace permission delay. Forty-four days is not a large migration window if several workflows share one owner or release cycle. Set an internal freeze date before November 30, reserve time for regression and stakeholder review, and communicate which user experiences may change.
Preserve usage and cost comparisons across the move
A runtime migration changes more than a workflow identifier. It can change the model, tool-call count, prompt size, retry pattern, and amount of retained conversation context. If you compare usage before and after, keep the measurement definition stable. Record the application version, runtime, workflow version, model, event timestamp, and the usage values available from the provider in your own operational data model. Avoid sending extra labels to a meter endpoint unless its schema explicitly accepts them.
Keep raw usage quantities separate from any dollar calculation. A token count, request count, or session count is a measurement. The provider's rate card and your own pricing rules determine cost and customer charges. UsageBox can aggregate quantities that your application submits under its meters, but it does not translate the old workflow's token totals into a new model's cost, rate agent calls, or generate customer invoices. A stable quantity ledger lets finance compare periods; a separate rating layer can apply the right model and customer rates for each period.
Before you change traffic, confirm that the new runtime emits the fields your reconciliation process expects and that the same customer or product routes to the same billing identity. If the destination changes which events are available, document the gap instead of filling it with estimated values that look exact. Keep old and new records distinguishable so a cost increase can be traced to a code change, a new model, a longer prompt, or a different user population.
Migration checklist
- Inventory every Builder workflow, owner, published version, embedded integration, and workflow ID.
- Export the full TypeScript or Python Agents SDK code and store a reviewed, secret-free copy.
- Choose an app-hosted Agents SDK or an internal Workspace Agent based on the real user and permission boundary.
- Recreate control flow, input/output contracts, tool permissions, failure behavior, and safety checks explicitly.
- Build an evaluation set and disable side effects during shadow testing.
- Canary behind a routing switch and verify a fallback that remains available after Agent Builder shuts down.
- Preserve provider usage, model, runtime, and version context so pre- and post-migration reports remain interpretable.
- Complete the cutover and remove obsolete configuration before November 30, 2026.
OpenAI's dates and migration options can change, so check the official notice again before each release milestone. The practical objective is to finish the migration while the Builder is still accessible, validate the replacement under your own permissions and tests, and make the post-shutdown fallback independent of the retired visual editor.
Related guide
If the migrated workflow handles live speech, use the Realtime voice-agent build and metering checklist to keep session events, usage quantities, and provider cost calculation separate.