OpenAI Agent Builder is being deprecated and is scheduled to shut down on November 30, 2026. The Agent Builder deprecation leaves you an export to Agents SDK code, but OpenAI says that export does not convert the workflow graph or guarantee unchanged behavior. The real migration work is deciding what moves to code, what can move to ChatGPT Workspace Agents, and what has to be checked by hand.

To see where an export stops, I ran a small fixture I wrote for this test in the shape of an Agents SDK export: one agent, one function tool, structured output. It is not an export of a real customer workflow, so its results describe this test only. Against gpt-5.4-mini with openai-agents 0.22.0, all three default runs returned correct structured output with one tool call each. When I removed the connected-app token the fixture expects, the connection probe failed with KeyError, which is the point: exported code cannot carry a credential that was never part of the code. A second cell with controlled settings got one successful run before my account hit its daily request limit.

Current Agent Builder status

OpenAI's Agent Builder documentation describes it as a visual canvas for multi-step agent workflows, deployed through ChatKit or through downloaded SDK code. The same page says the product is being deprecated, that existing users can continue during the transition, and that shutdown is scheduled for November 30, 2026, the date also listed on OpenAI's deprecations page. Keep the old workflow available while you validate the replacement, and do not treat the export as a complete production migration.

The deadline sets the order of work. First capture representative inputs, tool calls, permissions, and expected outputs. Then export and rebuild in the destination. Retire the old workflow only after the replacement passes those checks, so you keep a reference while the two implementations differ.

What the Agent Builder export actually does

The OpenAI migration guide gives the path: open the workflow in Agent Builder, select Code in the top navigation, select Agents SDK, choose TypeScript or Python, and copy the complete export. Then install and configure the matching SDK, place the export in your runtime, and test it there.

The export is a starting point, not a graph translator. OpenAI explicitly warns that it does not convert the workflow graph or guarantee that every behavior transfers unchanged, and that connected apps, authentication, publishing, and permissions need separate review. So the migration has two lanes: code portability and environment parity.

SDK versus Workspace: which destination fits?

OpenAI's decision rule is simple: the Agents SDK is for building through code, and Workspace Agents are for natural-language building and sharing with teams. The SDK fits when your server owns deployment, tools, state, approvals, and runtime behavior. Workspace fits when the agent is mainly an internal assistant that the team wants to maintain in ChatGPT.

Decision pointAgents SDKChatGPT Workspace Agents
Primary ownerApplication teamWorkspace team
Build surfacePython or TypeScript codeNatural-language configuration and shared workspace controls
Control flowExplicit in application codeReviewed through the Workspace agent configuration
Tools and authRebuild and authorize in your runtimeConfigure apps, tools, skills, and connection permissions in Workspace
DeploymentYour server, CI, storage, and observabilityChatGPT workspace
Best fitProduction workflows with custom logic or approvalsInternal assistants and team-shared workflows
Migration riskRuntime and integration work remainsWorkspace eligibility and configuration work remains

Choose the SDK when a missing tool call, a reordered step, or an unreviewed approval could cause a business failure. Choose Workspace when the main value is a shared assistant and the team accepts configuration-led behavior. The Agents SDK documentation lists sessions, tracing, guardrails, resumable approvals, and handoffs as SDK capabilities, but you still own the runtime and deployment around them.

A reproducible SDK migration path

1. Inventory the old workflow

Record the workflow's instructions, branches, tools, connected apps, authentication scopes, knowledge files, representative inputs, and expected outputs. Save two or three successful runs as fixtures, so you have a comparison target when the exported code behaves differently.

2. Export the SDK code

Use Code, Agents SDK, and your chosen language. Store the export in version control with the date and the Agent Builder workflow identifier, and do not edit away the original export before you have a clean baseline.

OpenAI Agent Builder Get code dialog with the Agents SDK tab selected and TypeScript or Python export
The Agent Builder export dialog (Image: OpenAI documentation)

3. Run the smallest working tool loop

This is the core shape I tested. It uses one local function tool and a structured result, so the migration boundary is visible without tool wiring hidden inside a framework wrapper:

from agents import Agent, Runner, function_tool
from pydantic import BaseModel

class MigrationAnswer(BaseModel):
    item: str
    available: bool
    quantity: int

@function_tool
def lookup_migration_fixture(item: str) -> str:
    return '{"item":"migration-check","available":true,"quantity":3}'

agent = Agent(
    name="migration-check",
    instructions="Call the lookup tool before returning the structured result.",
    tools=[lookup_migration_fixture],
    output_type=MigrationAnswer,
)

result = await Runner.run(agent, "Check migration-check using the lookup tool.")

The full fixture adds a recommendation field, a fixed model, and the validation the harness uses. Its SHA-256 is in the public results file, so this exact fixture can be told apart from a later edit. With Python 3.13.5, openai-agents 0.22.0, openai 3.3.1, and gpt-5.4-mini, all three default runs returned structured, correct output, each with one tool call and two requests.

4. Rebuild the parts the export cannot guarantee

Compare the exported agent with the inventory from step 1. Recreate branches and triggers in code or Workspace. Reconnect apps and credentials. Re-upload knowledge files or rebuild the retrieval setup, and compare representative retrieval results before switching traffic; for a self-hosted RAG replacement, compare open source vector databases by filtering, scale, and PostgreSQL fit before you commit to the storage layer. Then test the same inputs, including a tool error, an empty result, an unauthorized connection, and a timeout. OpenAI's migration guide specifically calls out control flow, triggers, tools, permissions, apps, skills, and authentication as items to review.

A clean import is not that check. My fixture imported and completed tool-backed runs, which proves package compatibility for that fixture and nothing about graph, tool, permission, retrieval, or deployment parity for your workflow.

5. Compare default behavior with controlled settings

The default cell leaves the SDK's ordinary run settings in place. The parity cell pins automatic tool choice, a 300-token output cap, a 60-second model timeout, and a four-turn run limit. Both cells use the same fixture, prompt, model, and tool.

CellSuccessful runsStructured and correctWall timeTokens per successful run
Default settings3/33/32432.11 ms median432 input, 48 output
Controlled parity settings1/31/1 completed2079.12 ms (single run)432 input, 48 output

The second and third parity runs returned RateLimitError because the account had used its 50 requests per day for the model, so the parity cell is a partial reproducibility check. These are sample timings on one machine, not a general SDK performance claim, and none of it shows that a private Agent Builder graph will transfer unchanged.

6. Test the environment boundary

The code export cannot contain an external CRM token, OAuth grant, app connection, or deployment secret. Treat those as migration inputs. In SDK code, provide them through the runtime's secret and authorization system. In Workspace, configure the required connection and permissions in the workspace, then preview representative inputs before creating the agent. Workspace migration also requires an eligible Business, Enterprise, or Edu workspace and permission to create agents.

In my run, removing the fixture's AGENT_BUILDER_CONNECTED_APP_TOKEN made the local connection probe raise KeyError, recorded as missing_connection_compatibility: 1 and missing_connection_error: KeyError. That is a local compatibility check, not an OpenAI API outage. It shows the gap you will hit in a real migration: the exported code cannot supply an external credential that was never part of the export.

Validation checklist before shutdown

Use this order for each workflow:

  1. Preserve the old workflow and save representative input/output pairs.
  2. Export the Agents SDK code from the Code menu, choosing Python or TypeScript.
  3. Choose SDK or Workspace based on ownership, control flow, tools, and sharing needs.
  4. Rebuild branches, tools, knowledge sources, connections, permissions, and secrets.
  5. Test successful runs plus empty data, tool failure, timeout, and unauthorized access.
  6. Compare outputs and side effects, not only the final text.
  7. Deploy the replacement and monitor it before retiring Agent Builder.

The official guide says to review the exported changes, configure the target tools and permissions, preview representative inputs, compare expected behavior, and create the Workspace agent only after validation. Those checks matter more than whether the copied file imports. Include failed and interrupted runs in the set you replay, not only successful ones, check retries and human handoffs, and have the workflow owner sign off on any behavior change. That is the gap between an export button and a production migration.

How I tested this

  • Machine: Apple M1 (arm64, Darwin 26.3), Python 3.13.5.
  • Versions: openai-agents 0.22.0, openai 3.3.1, model gpt-5.4-mini.
  • Date: August 24, 2026.
  • Fixture: constructed for this test in the shape of a Python Agents SDK export (one Agent plus one function_tool returning a fixed record). It is not a real exported Agent Builder workflow.
  • What was run: two cells of three live runs each against the OpenAI API, one with default SDK settings and one with the controlled parity settings above, with a 90-second harness timeout per run. A separate local probe removed the connected-app token.
  • What went wrong: the second and third parity runs hit the daily request limit and returned RateLimitError, so only 4 of 6 runs completed.
  • Not tested: a real Agent Builder export, TypeScript, Workspace Agents, ChatKit deployment, branching workflows, knowledge files or retrieval, and real connected apps.
  • Raw record: per-run metrics, the fixture hash, and the error messages are in the public results file.

Related coverage

References