OpenAI Agent Builder Migration Guide: What to Do Before Shutdown

Start with the deadline and a dependency inventory

OpenAI added a June 3, 2026 notice to its AgentKit announcement stating that Agent Builder and Evals are winding down and will no longer be available on the platform after November 30, 2026. That is a service deadline, not a recommended day to begin migration. A replacement needs time for access approval, implementation, evaluation, user acceptance, cutover, and rollback. Set an internal freeze and acceptance date several weeks earlier, adjusted for the consequence and complexity of the workflow.

Inventory usage before choosing technology. For each Agent Builder workflow, identify its owner, users, entry points, schedules, upstream callers, downstream systems, data classes, monthly volume, failure consequence, and last confirmed use. Include prototypes: an apparently abandoned workflow may still be invoked by a bookmarked link, automation, webhook, or internal document. Retirement is a valid migration outcome when the job has no active owner or measurable value.

Capture the complete behavioral specification. Save instructions and examples, but also models and reasoning settings, tool definitions, connector scopes, handoff logic, structured-output schemas, files, memory assumptions, approval points, timeouts, retry behavior, spending limits, user-visible messages, and escalation rules. Screenshots can document layout, but machine-readable configuration and source-controlled specifications are more useful for reconstruction. Confirm available export functions in the product rather than assuming this article has inspected your account.

• Owner and users
• Trigger and schedule
• Instructions and tools
• Identity and permissions
• Tests and known failures
• Operations and rollback

Choose the replacement from the operating model

OpenAI's notice recommends the Agents SDK for workflows that should continue as code and Workspace Agents in ChatGPT for use cases better suited to natural-language prompting. That distinction is more useful than feature-by-feature imitation. Decide who should own changes, where the workflow runs, how it is invoked, which systems it can change, and what engineering control the organization requires.

Workspace Agents suit repeatable team workflows that should be created, tested, shared, scheduled, or run through ChatGPT and supported channels. Current documentation describes apps, custom MCP servers, files, skills, memory, schedules, Slack channels, and API triggers, subject to workspace eligibility and admin controls. It also documents end-user and agent-owned authentication. A shared connection is operationally powerful: use a service account where possible, narrow its scope, and keep write approvals for risky actions.

The Agents SDK suits applications owned in code. Its documented primitives include agents, tools, handoffs, guardrails, sessions, human-in-the-loop mechanisms, and tracing. The SDK uses the Responses API by default and manages the agent loop; use the Responses API directly when the team needs to own tool dispatch and state handling itself or has a short-lived response path. This is an architecture decision, not a ranking: some organizations will use Workspace Agents for internal workflows and SDK applications for customer-facing or deeply integrated systems.

Test plan and regional availability before committing. Workspace features can depend on workspace type, admin configuration, app availability, and channel support. A trigger that only queues work may not satisfy a synchronous application. Conversely, rebuilding a simple shared research workflow as a custom service adds deployment, on-call, security, and maintenance obligations that a managed workspace could avoid.

Translate the workflow without carrying hidden assumptions

Rebuild from an explicit flow: entry condition, trusted instructions, untrusted inputs, decision points, tool calls, validations, approvals, outputs, and stop conditions. Visual layout rarely maps one-to-one to code or another builder. Preserve required behavior while using the replacement's native controls. For example, a handoff in a canvas might become an SDK handoff, a specialist agent exposed as a tool, or deterministic code routing. OpenAI's orchestration documentation distinguishes manager-style agents-as-tools from handoffs; the right choice depends on who should retain control of the final result and conversation.

Treat tool execution as a security boundary. Recreate typed schemas and validate generated arguments against business rules outside the model. Separate read permission from write authority. Require approval for money movement, deletion, account changes, external publication, and other consequential effects. Bound loops with time, turn, retry, and cost limits. Do not embed secrets in prompts or source artifacts; use the target runtime's supported secret and identity mechanisms.

Workspace Agent instructions do not themselves grant app access, according to the current help page. Builders separately configure connections, actions, approvals, and supported connector constraints. The same page warns that constraints narrow action inputs but do not filter returned data. Therefore a rule that limits a search parameter is not a general data-loss-prevention control. Map both what the connector can do and what it can return.

For SDK migrations, preserve structured output and error semantics expected by callers. Decide how sessions and resumable state are stored, how versions are deployed, and how traces handle sensitive information. If users depended on a builder's implicit interface, create an equivalent entry point or communicate the new workflow. Functional equivalence includes accessibility, authorization, latency, and recovery—not only a similar answer.

Rebuild evaluations around acceptance and failure

An evaluation project is not merely a score to screenshot. Preserve its task definitions, inputs, expected properties, human annotations, grader instructions, thresholds, model and workflow versions, sampling rules, and known blind spots. Remove or govern sensitive records before copying them. If the existing dataset cannot be exported in a usable form, reconstruct the highest-value cases while access remains available and record what could not be preserved.

Build a compact baseline that represents production. Include common tasks, difficult edge cases, malformed inputs, unavailable tools, permission denial, stale data, conflicting evidence, prompt injection, excessive requests, and cases where the correct outcome is to abstain or escalate. Measure accepted outcomes after human review, material error classes, tool-call correctness, approval behavior, latency, cost, and reviewer effort. An overall pass rate can hide a rare but consequential action failure.

The Agents SDK documentation describes built-in tracing and links its traces to OpenAI evaluation tooling. Tracing helps explain which model calls, tools, and handoffs produced a result, but a trace is evidence for debugging, not proof of correctness. Define graders that match the business contract, use deterministic checks where possible, calibrate model-based graders against human decisions, and keep a withheld set to reduce tuning to familiar examples.

Run the same fixed cases against the old and new workflows, then conduct exploratory testing for replacement-specific behavior. Record meaningful differences rather than demanding identical wording. A new system can be acceptable if it reaches the same verified outcome with different steps; it can be unacceptable even with similar prose if it changes permissions, citations, costs, or error handling. This guidance is based on opened documentation, not hands-on testing of a private Agent Builder project.

Cut over gradually and close the old path

Begin with shadow execution when policy and cost allow: the replacement receives representative work but cannot affect downstream systems. Compare results, then move to a limited user group with read-only tools or reversible writes. Expand scope only after predefined acceptance thresholds and incident rehearsals pass. If parallel execution would duplicate external actions or expose data unnecessarily, use replayed cases in an isolated environment instead.

Before cutover, freeze nonessential changes, publish the exact accepted replacement version, verify identities and approvals, and communicate the new entry point and escalation route. Monitor task completion, error classes, denials, handoffs, tool calls, latency, spending, and human overrides. Keep a time-bounded rollback path that restores service without reviving unsafe credentials or losing new records.

Decommissioning is part of migration. After acceptance, revoke old tokens and connector grants, disable schedules and webhooks, remove obsolete shared links, update runbooks and ownership records, and retain only the artifacts required by policy. Confirm that no caller is still reaching the old endpoint. Review the replacement after product or model changes; leaving Agent Builder does not eliminate ongoing evaluation and governance work.