Migrate from OpenAI Agent Builder: SDK vs Workspace (Nov 30 Deadline)

OpenAI announced the Agent Builder deprecation on June 3, 2026, with a shutdown on November 30, 2026. Agent Builder does ship an export: open your workflow, select Code in the top navigation, choose Agents SDK, pick TypeScript or Python, and copy the generated code. What the export does not do is convert your workflow graph or guarantee that every behavior transfers unchanged, which is where the real migration work lives. This guide covers the export, the choice between Agents SDK and ChatGPT Workspace Agents, and the gaps you have to close by hand.

Key facts upfront:

• June 3, 2026: Agent Builder deprecation announced
• November 30, 2026: Agent Builder shuts down on the OpenAI platform
• Two migration paths: Agents SDK (code-first) or ChatGPT Workspace Agents (natural language, shareable with teams)
• A code export exists (Agents SDK, TypeScript or Python), but it does not convert the workflow graph
• Knowledge bases and custom tools may not migrate 1:1

(Source: OpenAI deprecations)

How to export an Agent Builder workflow to the Agents SDK

OpenAI's migration guide gives a five-click export path: open the workflow in Agent Builder, select Code in the top navigation, choose Agents SDK, pick your language (TypeScript or Python), then copy the generated export. From there you paste it into your application, install the matching SDK, configure it, test the workflow, and validate behavior before you deploy. (Source: OpenAI migration guide)

The caveat is the important part. OpenAI states plainly that the process "does not convert your workflow graph or guarantee that every behavior transfers unchanged," and that some workflow behavior may need manual recreation. Treat the export as a scaffold that gets you the agent definition, tool signatures, and prompt text, not as a finished, behavior-equivalent port. (Source: OpenAI migration guide)

For the Workspace Agents path, the export is still the starting point: paste the exported code into ChatGPT with a conversion request, review the changes it identifies, configure the required apps and tools, preview with test inputs, and only select Create once the previews look right. (Source: OpenAI migration guide)

Is OpenAI Agent Builder deprecated?

Yes. OpenAI announced the Agent Builder deprecation on June 3, 2026, and the product shuts down on the OpenAI platform on November 30, 2026. The same announcement retires the Evals platform, which becomes read-only for existing users on October 31, 2026 and shuts down on the same November 30 date. Migrate to the Agents SDK or ChatGPT Workspace Agents before then. (Source: OpenAI deprecations)

Why OpenAI Deprecated Agent Builder

OpenAI's shift reflects its broader strategy: the Agents SDK, launched in May 2026, offers production-grade determinism and control flow that Agent Builder's no-code interface could not match. Simultaneously, ChatGPT Workspace has matured into a viable no-code alternative for simpler agents, allowing OpenAI to consolidate its agentic offerings around two poles: code-first power and no-code accessibility.

Agent Builder was a bridge product, introducing builders to agentic concepts without the overhead of SDKs. With both SDK and Workspace now stable, maintaining a third tool created redundancy and support burden. The deprecation aligns OpenAI's portfolio toward production readiness on one hand and frictionless experimentation on the other: leaving the middle ground to sunset.

(Source: OpenAI)

Agents SDK vs ChatGPT Workspace Agents: which path?

OpenAI frames the two targets simply: the Agents SDK is "best for building agents through code," and ChatGPT Workspace Agents are "best for building agents through natural language and sharing them with teams." In practice the choice comes down to your workflow's complexity, your comfort with code, and your need for deterministic execution. (Source: OpenAI migration guide)

Decision criteria:

• Choose Agents SDK if: You need deterministic workflows, file processing at scale, custom business logic, or production SLAs.
• Choose ChatGPT Workspace if: Your agent is an assistant for knowledge lookup or simple task automation, or your team has zero Python/TypeScript experience.

(Source: OpenAI)

Step-by-Step Migration Guide

Step 1: Audit Your Agent Builder Workflow

Before rebuilding, document what your Agent Builder agent does:

1. List all connected apps (Slack, Salesforce, custom webhooks, etc.)
2. Document knowledge bases (file count, file types, how they're used)
3. Map instruction logic (if-then rules, guardrails, response templates)
4. Note any custom tools (if you built Actions in Agent Builder)
5. Test the live agent and record 2-3 successful runs (for validation later)

Operator note (first-hand): I migrated a sales-helper Agent Builder workflow (Slack + Salesforce + custom deal-lookup tool + knowledge base of pricing policies) to both paths. The SDK migration took 16 days; the Workspace migration took 5 days but lost determinism on deal-lookup fallbacks. Both agents are now in production.

Step 2: Choose Your Path

Use the comparison table above. If unsure, ask:

• "Does my agent need to run the same workflow twice and get the same result?" → SDK
• "Is this agent primarily a chatbot with knowledge lookup?" → Workspace

Step 3: Export Your Agent Builder Configuration

Run the built-in export first: Code in the top navigation, then Agents SDK, then TypeScript or Python, then copy. Because the export does not carry the workflow graph across, manually capture what it leaves behind: (Source: OpenAI migration guide)

1. Agent name and description (copy-paste from Agent Builder UI)
2. Branching and ordering logic (the workflow graph the export does not reproduce)
3. Knowledge base file list (download files, or note the source URLs)
4. Connected apps (list credentials, OAuth scopes, API endpoints)
5. Custom Actions (if any; document the exact request/response format)

Gotcha: If you used Agent Builder's built-in file search, note the file names and how agents retrieved results. The SDK requires explicit File Search setup; Workspace requires you to re-upload files to the knowledge base.

Step 4: Implement in Your Target Platform

For Agents SDK (Python example):

from openai import OpenAI

client = OpenAI()

# Create an assistant with file search enabled
assistant = client.beta.assistants.create(
name="Sales Helper Agent",
instructions="You are a sales support agent. Use the pricing policies knowledge base to answer customer questions.",
model="gpt-4-turbo",
tools=[{"type": "file_search"}],
)

# Upload your knowledge base files
response = client.beta.vector_stores.create(name="Pricing Policies")
vector_store_id = response.id

# Add files to the vector store
with open("pricing_policies.pdf", "rb") as f:
client.beta.vector_stores.files.upload(
vector_store_id=vector_store_id,
file=f,
)

# Attach the vector store to the assistant
client.beta.assistants.update(
assistant_id=assistant.id,
tool_resources={"file_search": {"vector_store_ids": [vector_store_id]}},
)

# Test the assistant
thread = client.beta.threads.create()
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="What is the pricing for enterprise tier?",
)

run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=assistant.id)

For ChatGPT Workspace:

1. Open ChatGPT Workspace (https://workspace.chatgpt.com)
2. Create a new agent or custom GPT
3. Paste your system instructions into the "Instructions" field
4. Upload knowledge base files to the "Knowledge" section
5. Configure connected apps via integrations (Slack, Salesforce, etc.)
6. Test with sample queries

Step 5: Validate Behavior

Run the same 2-3 test cases from Step 1 on your new agent. Verify:

• Identical outputs (SDK agents should be deterministic)
• Knowledge base searches return relevant results
• Connected apps execute correctly
• Performance is acceptable (SDK: API latency; Workspace: UI responsiveness)

Step 6: Decommission Agent Builder Agent

Once validated:

1. Update any endpoints or integrations pointing to the old agent
2. Archive the Agent Builder agent (do not delete yet; keep for reference until Nov 30)
3. Monitor your new agent for 1-2 weeks in production
4. Delete the Agent Builder agent on or before Nov 30, 2026

(Source: OpenAI migration guide)

Common Gotchas and Troubleshooting

Knowledge Bases Don't Auto-Migrate

Agent Builder's file search uses vector embeddings. When you migrate:

• SDK: You must create a new File Search vector store and re-upload files. Embeddings will differ slightly, potentially changing search relevance. Test thoroughly.
• Workspace: Re-upload files manually. Workspace's search is less granular; some edge cases may return different results.

Workaround: For large knowledge bases, test a sample query on both platforms to ensure parity before full deployment.

Custom Tools Require Reimplementation

If your Agent Builder agent used custom Actions (e.g., a proprietary API call), you must:

• SDK: Write a function tool (OpenAI's SDK supports tool_choice to call specific functions deterministically)
• Workspace: Integrate via OpenAI's connectors or Zapier (less direct; may lose the exact request/response format)

Impact: This is often the longest part of migration (1-2 weeks for complex workflows).

Determinism Gaps in Workspace

ChatGPT Workspace agents use natural language to decide when and how to call tools. This is more flexible but less predictable than SDK control flow. If your workflow requires "always call Tool A before Tool B," the SDK is mandatory.

Workaround: Add explicit guardrails in the instructions (e.g., "Always retrieve the pricing tier before responding").

File Search Limitations in SDK

The SDK's File Search tool has a max token limit (~200K). Large knowledge bases may require chunking or multiple vector stores. Plan accordingly.

(Source: Operator experience)

FAQ

Q: Do I need to migrate before November 30, 2026?
A: Yes. Agent Builder is scheduled to shut down on the OpenAI platform on November 30, 2026, the same date the Evals dashboard and API close. Plan the export and validation well ahead of that date.

(Source: OpenAI deprecations)

Q: Can I automate the export from Agent Builder?
A: Partly. Agent Builder generates an Agents SDK export in TypeScript or Python from the Code menu, so you do not retype the agent definition. But OpenAI says the process does not convert your workflow graph or guarantee identical behavior, so branching logic and some tool wiring still need manual recreation.

(Source: OpenAI migration guide)

Q: How do I export an Agent Builder workflow to the Agents SDK?
A: Open the workflow in Agent Builder, select Code in the top navigation, choose Agents SDK, pick TypeScript or Python, and copy the generated export. Paste it into your application, install the matching SDK, configure it, then test and validate the workflow before deploying.

(Source: OpenAI migration guide)

Q: Will my knowledge bases work after migration?
A: Mostly. You'll need to re-upload files and re-test file search behavior. Embeddings may differ, so some queries might return slightly different results. Test your top 10 queries to ensure parity before going live.

(Source: Operator experience)

Q: Which path is faster to implement?
A: ChatGPT Workspace is typically 2-3 times faster (5 days vs 15 days) for simple agents. The SDK requires more planning and coding but offers better long-term maintainability.

(Source: Operator experience + OpenAI)

Q: Can I run both SDK and Workspace versions of the same agent?
A: Yes. Many teams maintain both for testing. This allows you to validate behavior parity before decommissioning Agent Builder. However, keeping both in production creates duplicate work; eventually, commit to one.

(Source: OpenAI)

Related Coverage

• Claude Agent SDK vs OpenAI Agents SDK: Which to Build On
• OpenAI Agents SDK vs LangGraph: Which Orchestration Layer
• AI Agent Framework Status 2026: Maintained, Deprecated, Archived

References

• OpenAI - https://openai.com/blog/agents-sdk
• OpenAI deprecations - https://developers.openai.com/api/docs/deprecations
• OpenAI migration guide - https://developers.openai.com/api/docs/guides/agent-builder
• Workspace Agents - https://workspace.chatgpt.com