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

OpenAI deprecated Agent Builder on June 3, 2026, with a hard sunset on November 30, 2026. If you've built agents using Agent Builder, you have a 7-month window to migrate to one of two paths: the Agents SDK (deterministic, code-first, full control) or ChatGPT Workspace (no-code friendly, faster deployment, less predictable execution). This guide walks you through choosing your path, executing the migration step-by-step, and troubleshooting common blockers.

Key facts upfront:

  • June 3, 2026: Agent Builder deprecated; no new agents can be created
  • Nov 30, 2026: All existing Agent Builder agents stop running (hard deadline)
  • Two migration paths: Agents SDK (deterministic workflows, code required) or ChatGPT Workspace (no-code, built-in tools)
  • No automated export; manual rebuild is required
  • Knowledge bases and custom tools may not migrate 1:1

(Source: OpenAI)

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)

The Two Migration Paths: SDK vs Workspace

Choosing between Agents SDK and ChatGPT Workspace depends on your workflow's complexity, your comfort with code, and your need for deterministic execution:

AspectAgents SDKChatGPT Workspace
Code RequiredYes (Python/TypeScript)No (custom instructions or GPT)
Deterministic WorkflowsFull control via control flowLimited; natural language-driven
Knowledge Base SupportFile search requires reimplementationBuilt-in document upload and search
Connected Apps & ToolsOAuth integrations; custom functionsPre-built OpenAI tools + custom integrations
Production ReadinessHigh (explicit control)Medium (best for assistive agents)
Effort to Migrate2-4 weeks (depends on workflow complexity)1-2 weeks (simpler rebuild)
ScalabilityUnlimited API calls (pay-per-use)Subject to Workspace rate limits
Real-time MonitoringFull logging and observabilityBasic activity logs

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

Agent Builder does not offer automated export. Manually extract:

  1. Agent name and description (copy-paste from Agent Builder UI)
  2. System prompt/instructions (the core logic)
  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 Nov 30, 2026?
A: Yes. Any Agent Builder agent still running on Nov 30 will be permanently disabled. There is no extension or grace period. Start planning your migration today if you haven't already.

(Source: OpenAI)

Q: Can I automate the export from Agent Builder?
A: No. OpenAI does not provide an automated export tool. Your migration requires manual documentation and rebuild. This is a one-time effort; plan for 1-4 weeks depending on complexity.

(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

Learn more about agentic frameworks and migration:

References

Word count: 1,687 words