OpenAI is deprecating Agent Builder and has scheduled its shutdown for November 30, 2026. Existing users can continue during the transition. The supported migration direction is not a one-click conversion: open the workflow, use Code, choose Agents SDK, select TypeScript or Python, and copy the export. You then have to validate the workflow, rebuild anything the export does not carry, and choose whether the destination is code-owned SDK infrastructure or a shared ChatGPT Workspace Agent. (Source: OpenAI Agent Builder)

This guide answers the practical question: what should move to code, what can move to Workspace, and what must be checked by hand? It includes a runnable SDK-shaped fixture and a bounded live run set, including a provider rate-limit interruption. The fixture is representative code, not a private Agent Builder export, so its timing is evidence about this test only.

Current Agent Builder status

OpenAI's current documentation describes Agent Builder as a visual canvas for multi-step agent workflows, with deployment through ChatKit or downloaded SDK code. The same documentation says the product is being deprecated, existing users can continue during the transition, and shutdown is scheduled for November 30, 2026. Keep the old workflow available while you validate the replacement, but do not treat the export as a complete production migration. (Source: OpenAI Agent Builder)

The deadline changes the order of work. First capture representative inputs, tool calls, permissions, and expected outputs. Then export and rebuild the destination. Only after the replacement passes those checks should you retire the old workflow. This sequence preserves a reference while the two implementations differ.

What the Agent Builder export actually does

The current migration path is: open the workflow in Agent Builder, select Code in the top navigation, select Agents SDK, choose TypeScript or Python, and copy the complete export. OpenAI's guide then says to install and configure the matching SDK, place the export in your runtime, and test it there. (Source: OpenAI migration guide)

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. Connected apps, authentication, publishing, and permissions also need separate review. That means the migration checklist has two lanes: code portability and environment parity. (Source: OpenAI migration guide)

SDK versus Workspace: which destination fits?

OpenAI's decision rule is simple: the Agents SDK is for building through code, while Workspace Agents are for natural-language building and sharing with teams. The SDK is the better fit when your server owns deployment, tools, state, approvals, and runtime behavior. Workspace is the better fit when the agent is primarily an internal assistant and the team wants to maintain it in ChatGPT. (Source: OpenAI migration guide)

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 create a business failure. Choose Workspace when the main value is a shared assistant and the team accepts configuration-led behavior. OpenAI's SDK documentation also highlights sessions, tracing, guardrails, resumable approvals, and handoffs as SDK capabilities, but you still own the surrounding runtime and deployment. (Source: OpenAI Agents SDK)

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. This gives you 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. Do not edit away the original export before you have a clean baseline. (Source: OpenAI migration guide)

3. Run the smallest working tool loop

The following is the core shape tested in this pass. It uses one local function tool and a structured result, so the migration boundary is visible without hiding tool wiring 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 checkable artifact is experiment/fixture/exported_workflow.py. It adds the recommendation field, fixed model, and validation used by the harness. Its SHA-256 is recorded in experiment/results.json, so a reader can distinguish this exact fixture from a later edit.

Operator note (first-hand): On August 24, 2026, the fixture ran with Python 3.13.5, openai-agents 0.22.0, openai 3.3.1, and model gpt-5.4-mini. All three default runs returned structured, correct output and made one tool call and two requests per run. (Source: experiment/results.json)

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. 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. (Source: OpenAI migration guide)

Operator note (first-hand): The artifact contains three default runs and three planned controlled-parity runs. The default cell completed with 3/3 successful, structured, and correct outputs. The first parity run also succeeded; the remaining parity repetitions returned RateLimitError after the project reached its daily request cap. This is a partial reproducibility check, not evidence that any private Agent Builder graph will transfer unchanged. (Source: experiment/results.json)

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.

Operator note (first-hand): Median wall time was 2432.11 ms for the default cell. The one successful parity run took 2079.12 ms; each successful run made one tool call, two requests, and used 432 input tokens plus 48 output tokens. These are sample timings on this machine, not a general SDK performance claim. (Source: experiment/results.json)

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. (Source: OpenAI migration guide)

Operator note (first-hand): After removing the fixture's AGENT_BUILDER_CONNECTED_APP_TOKEN, the local connection probe raised KeyError. The harness records this as missing_connection_compatibility: 1 and missing_connection_error: KeyError. It is a local compatibility check, not an OpenAI API outage: the point is that the exported code cannot supply an external credential that was never part of the code export. (Source: experiment/results.json)

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 successfully. (Source: OpenAI migration guide)

FAQ

Is OpenAI Agent Builder deprecated?

Yes. OpenAI's current Agent Builder documentation says the product is being deprecated and scheduled to shut down on November 30, 2026. Existing users can continue during the transition. Preserve your workflow as a reference, start validation early, and do not wait until the shutdown window to discover an app or permission gap. (Source: OpenAI Agent Builder)

Can Agent Builder migrate automatically to the Agents SDK?

Agent Builder provides a Code menu export for TypeScript or Python, but OpenAI says the export does not convert the workflow graph or guarantee unchanged behavior. Use it to seed the SDK project, then rebuild and test branches, tools, authentication, permissions, and deployment behavior. (Source: OpenAI migration guide)

Should I choose the Agents SDK or Workspace?

Choose the SDK when your application team needs explicit control over runtime, tools, state, approvals, storage, and deployment. Choose Workspace when a team-shared assistant can live inside ChatGPT and configuration-led maintenance is the better fit. The migration decision is about ownership and risk, not only developer preference. (Source: OpenAI migration guide)

Will connected apps and knowledge bases transfer unchanged?

Do not assume so. OpenAI lists connected apps, authentication, publishing, permissions, and tools as areas that need separate review. Reconnect credentials, rebuild integrations, re-upload or reconfigure knowledge sources, and compare representative retrieval results before switching traffic. (Source: OpenAI migration guide)

Does a successful SDK import prove the migration worked?

No. In this pass the representative fixture imported and completed successful tool-backed runs, but the official guide still requires behavior and environment validation. A successful import proves package compatibility for that fixture. It does not prove graph, tool, permission, retrieval, or deployment parity for your workflow. (Source: OpenAI migration guide)

Related coverage

References