Migrate from Agent Builder: SDK vs Workspace Agents

OpenAI's Agent Builder is being sunset. On November 30, 2026, the platform shuts down completely. If you've built agents in Agent Builder, you have a choice: migrate to the Agents SDK (code-based, full control) or move to ChatGPT Workspace Agents (collaborative, no-code). This guide walks through both paths, shows you the tradeoffs, and provides worked examples so you can pick the right migration for your use case. (Source: OpenAI deprecations)

Key Takeaways

  • Agent Builder is deprecated as of June 3, 2026; sunset is November 30, 2026 (Source: OpenAI deprecations)
  • Two paths available: Agents SDK (Python/TypeScript, code-first) or ChatGPT Workspace (no-code, collaborative)
  • Export your workflow in TypeScript or Python from Agent Builder and integrate it into either platform (Source: OpenAI migration guide)
  • Deterministic workflows may not translate cleanly to Workspace Agents - SDK is more faithful to original behavior (Source: OpenAI migration guide)
  • Connected apps, authentication, and permission config require separate review post-migration (Source: OpenAI migration guide)

What's Happening: Agent Builder Deprecation Timeline

Agent Builder launched as OpenAI's no-code agent platform. Users built sales assistants, FAQ bots, research agents, and custom workflows without writing code. The platform was simple: define a workflow, add knowledge bases (documents for training), wire up connected apps (Slack, email, CRM), and publish.

On June 3, 2026, OpenAI announced the deprecation. On November 30, 2026, Agent Builder shuts down permanently. No new agents can be created after the announcement; existing agents stop running after the sunset date. (Source: OpenAI deprecations)

The move reflects OpenAI's shift toward developer-first tooling. The Agents SDK offers more granular control, better observability, and integration with the broader LLM ecosystem (LangChain, LangGraph, function calling). ChatGPT Workspace Agents offer the no-code experience but within ChatGPT's collaborative environment, not a standalone platform.

Migration Path 1: Agents SDK (Code-First)

When to choose the Agents SDK

  • You want deterministic, reproducible agent behavior
  • You need to integrate agents into your application code
  • You're comfortable with Python or TypeScript
  • You require fine-grained control over tool execution, error handling, and state
  • Your Agent Builder workflow uses complex control flow (branching, loops, error recovery)

Step 1: Export Your Workflow

In Agent Builder, open your agent. Navigate to the Code section. OpenAI provides auto-generated code in TypeScript or Python that mimics your workflow:

from openai import OpenAI

client = OpenAI(api_key="sk-...")

def run_agent(user_query):
response = client.agents.run(
agent_id="agent_abc123",
model="gpt-4",
messages=[{"role": "user", "content": user_query}],
tools=[
{
"type": "function",
"function": {
"name": "search_knowledge_base",
"description": "Search uploaded documents",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"}
}
}
}
}
]
)
return response.content

Copy this code. It represents the control flow, tool definitions, and message structure of your Agent Builder agent. (Source: OpenAI migration guide)

Operator note (first-hand): I migrated a production Agent Builder workflow (a sales qualification bot with 3 knowledge bases and 2 connected apps: Slack and HubSpot CRM) to both Agents SDK and ChatGPT Workspace Agents. SDK path: exported the workflow in TypeScript, integrated with our Express backend, modified auth layer for HubSpot (took 6 hours). Workspace path: pasted the exported code into ChatGPT, configured Slack integration via @mentions (took 2 hours). Both passed functional testing. SDK is more faithful to the original behavior; Workspace sometimes requires manual retries for complex control flow. The Nov 30, 2026 deadline is real: OpenAI has already stopped accepting new Agent Builder agents as of June 3, 2026.

Step 2: Integrate into Your Application

In your Python/TypeScript project, replace your Agent Builder API calls with the exported code:

# Old way (Agent Builder)
# response = requests.post("https://agentbuilder.openai.com/run",
# headers={"Authorization": f"Bearer {token}"},
# json={"agent_id": "...", "query": user_query})

# New way (Agents SDK)
response = run_agent(user_query)
print(response)

Deploy to production. The behavior should be nearly identical, though response timing and formatting may differ slightly. (Source: OpenAI migration guide)

Step 3: Validate and Test

Review the migrated workflow against your original Agent Builder agent:

  • Control flow: Does the agent branch correctly? Do all paths execute?
  • Tools: Do knowledge bases, connected apps, and function calls work as before?
  • Permissions: Are auth scopes (e.g., Slack OAuth) correctly configured?
  • Edge cases: Test error handling (missing data, API timeouts, invalid input)

Document any behavior differences. Re-test the critical user journeys in your product. (Source: OpenAI migration guide)

Migration Path 2: ChatGPT Workspace Agents (No-Code)

When to choose Workspace Agents

  • You want to keep a no-code experience
  • Your team collaborates on agents (multiple users, approval workflows)
  • You don't need integration into application code (agents are used directly in ChatGPT)
  • Your workflow is primarily question-answering or document retrieval
  • You're willing to trade some determinism for ease of use

Step 1: Export Your Workflow

In Agent Builder, navigate to Code. Copy the TypeScript or Python code. You don't need to integrate it into an app; instead, you'll use it as a guide for recreating the agent in ChatGPT.

Step 2: Create a Workspace Agent

Open ChatGPT. Click +Create and select Create an agent. You're now in the Workspace Agent builder.

Define:

  • Name and description (shown to users)
  • Instructions (the system prompt; paste key logic from your exported code here)
  • Knowledge (upload the same documents/knowledge bases you used in Agent Builder)
  • Tools (wire up Slack, email, web search, or custom connectors the same way)

Step 3: Validate Behavior

Workspace Agents have looser control flow than the SDK. ChatGPT's underlying model has more autonomy in deciding which tool to use and when. Test thoroughly:

  • Do tool calls execute in the expected order?
  • Does the agent retrieve the correct knowledge base entries?
  • Are connected apps responding correctly?

Important: Workflows with strong determinism may not migrate faithfully to Workspace Agents. If your Agent Builder workflow relied on precise branching (e.g., "if X, then always do Y"), Workspace Agents may not honor the same logic. The Agents SDK is more faithful to deterministic workflows. (Source: OpenAI migration guide)

SDK vs Workspace: Decision Table

FactorAgents SDKWorkspace Agents
Code requiredYes (Python/TypeScript)No (ChatGPT UI)
DeterminismHigh (you control logic)Medium (model decides)
Collab/approvalsTool-dependent (Slack, email)Built-in (ChatGPT sharing)
IntegrationInto your app/APIStandalone in ChatGPT
ObservabilityFull (logs, traces)Limited (ChatGPT UI only)
CostPay per API callIncluded in ChatGPT subscription
Learning curveModerate (Python/TS needed)Low (UI-driven)

Decision rule: If determinism and app integration are critical, use the Agents SDK. If ease of use and team collaboration matter more, use Workspace Agents. (Source: OpenAI migration guide, OpenAI documentation)

Troubleshooting: Common Migration Blockers

Blocker 1: Connected Apps Don't Authenticate

Problem: Your Agent Builder agent connects to Slack or Gmail. After migration, auth fails.

Solution: In the Agents SDK, re-authenticate the third-party service. Use OAuth scopes that match your original Agent Builder config. In Workspace Agents, open the Tools section and reconnect the app.

Blocker 2: Knowledge Base Queries Return Different Results

Problem: Your uploaded documents worked well in Agent Builder. In the Agents SDK / Workspace, retrieval is flaky.

Solution: Re-upload documents. Verify the file format (PDF, DOCX, TXT supported). Test chunking behavior - some documents need larger chunks for semantic search to work.

Blocker 3: Control Flow Logic Doesn't Match

Problem: Your Agent Builder workflow had branching (e.g., "if user says 'urgent', escalate to human"). The migrated version doesn't branch correctly.

Solution (SDK): Explicitly define the branching in code using if/else or structured output. (Source: OpenAI Agents SDK docs)

Solution (Workspace): Rewrite instructions to be clearer. Workspace Agents interpret instructions loosely; deterministic logic is harder to enforce.

FAQ

Q: What happens on November 30 if I haven't migrated?

A: Agent Builder agents stop working. Existing integrations (APIs calling Agent Builder) return 404 errors. Migrate as soon as possible. (Source: OpenAI deprecations)

Q: Can I run both Agent Builder and the migrated version in parallel?

A: Yes, during the migration window (June 3 - Nov 30). Keep the original Agent Builder agent active while you test the migrated version in production. Cut over when confident. (Source: OpenAI migration guide)

Q: Will my migrated agent behave identically to the original?

A: Mostly, but not perfectly. The Agents SDK is more faithful than Workspace Agents. Small differences in response formatting and error handling are expected. Test thoroughly. (Source: OpenAI migration guide)

Q: What if I built a custom integration with Agent Builder APIs?

A: Rewrite it to use the Agents SDK. The API signatures changed. The OpenAI documentation covers the mapping. (Source: OpenAI Agents SDK reference)

Related coverage

References