Kingy AI
For Companies
AI News

Agent Builder Migration Guide: Agents SDK or ChatGPT Workspace Agents

August 23, 2026 Curtis Pyke AI
A retiring visual agent workflow splitting through tested paths into a code runtime and a collaborative workspace agent

Migration verdict: export immediately, then choose one destination based on who must own the runtime. OpenAI has deprecated Agent Builder and scheduled it to shut down on November 30, 2026. The supported paths are the code-first Agents SDK or ChatGPT Workspace Agents for team-built workflows. ChatKit remains available.

Source audit: checked against current OpenAI documentation on August 23, 2026. Track the deadline on the AI Stack Change Radar and its Agent Builder change record.

What breaks

After shutdown, Agent Builder is no longer the place to edit, test or operate its visual workflow graphs. The export is a starting artifact, not a lossless conversion: OpenAI says it does not convert the workflow graph and does not guarantee that every behavior transfers unchanged.

Expect to rebuild or re-verify:

  • Node sequencing, branching and handoffs.
  • Tool credentials, authentication and permission boundaries.
  • Guardrails and human approval points.
  • Conversation state and resumability.
  • Published endpoints, ChatKit integration and user identity.
  • Tracing, evaluation, deployment and rollback controls.

Who is affected

  • Teams with production or internal workflows authored in Agent Builder.
  • Applications whose ChatKit experience points to an Agent Builder workflow.
  • Operators who rely on the visual graph as their only documentation.
  • Workflows with connectors, secrets, approvals or external side effects.
  • Admins who need shared ownership, publishing or workspace permissions.

Choose the replacement before rebuilding

Choose Best fit You must own
Agents SDK A product or service built and deployed by engineers Runtime, tools, state, authentication, deployment, observability and approvals
ChatGPT Workspace Agents Repeatable team work built through natural language and shared inside ChatGPT Workspace access, connected apps, permissions, publishing and behavior validation
Hybrid A code-owned backend with a ChatGPT-facing workflow A deliberately split contract; do not duplicate business logic in two places

OpenAI warns that workflows built around strong determinism may not migrate faithfully to a workspace agent. Put deterministic, regulated or side-effect-heavy logic in code and expose bounded tools to the agent.

Prerequisites

  1. Access to every Agent Builder workflow and permission to export it.
  2. An owner for each workflow, tool, credential and downstream system.
  3. A current test set with expected outputs and approved side effects.
  4. For Agents SDK: a Python or TypeScript service, secret management, deployment and telemetry.
  5. For Workspace Agents: a ChatGPT Business, Enterprise or Edu workspace with Workspace Agents access and permission to create agents.
  6. A deadline plan that leaves time for canary traffic before November 30.

Exact migration steps

1. Inventory before export

For each workflow, record its graph version, prompt text, model settings, tools, input/output schema, files, secrets, approvals, connected apps, ChatKit consumers, published URLs and owner. Capture screenshots of the graph because the export does not preserve the visual layout.

2. Export the complete workflow

  1. Open the workflow in Agent Builder.
  2. Select Code in the top navigation.
  3. Select Agents SDK in the code dialog.
  4. Select TypeScript or Python.
  5. Copy the complete export into a version-controlled migration branch.

Tag the export with its workflow name and date. Do not overwrite it during cleanup; it is your rollback and comparison artifact.

3A. Continue with the Agents SDK

Install and configure the matching SDK, then make the exported code runnable in your application. A minimal Python smoke-test shape is:

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="Support triage",
    instructions=(
        "Classify the request, gather the required facts, "
        "and call only the tools permitted for this workflow."
    ),
)

async def main():
    result = await Runner.run(agent, "Customer cannot access their account")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Your real export will include tools, handoffs and configuration. Review every generated dependency and tool implementation before running it. Replace embedded credentials with secret references, pin SDK versions and set explicit timeouts.

3B. Recreate it as a Workspace Agent

Create a Workspace Agent in ChatGPT and paste the exported code into the creation chat with OpenAI’s suggested request: “Please help me convert this workflow into an agent.” Then rebuild connected apps, authentication, instructions, permissions, publishing and review steps in the workspace. Treat the result as a new implementation that must pass the same tests—not as an import.

4. Reconstruct the contract, not the diagram

For each original node, identify the real contract: input, output, side effect, failure behavior and authorization. Merge cosmetic prompt nodes where sensible, but keep approval and safety boundaries explicit. A tool that writes to an external system should expose a dry-run mode and require a confirmation token or human approval for material actions.

5. Reconnect ChatKit deliberately

ChatKit remains available, but the backend workflow has changed. Verify session creation, authentication, domain allowlists, attachments, widget actions, error states and conversation resumption. Do not assume the old workflow identifier can be reused.

Configuration changes

  • Pin the Agents SDK and OpenAI client versions.
  • Move model names, instructions and rollout flags into reviewed configuration.
  • Store tool credentials outside exported source.
  • Give each tool an allowlist, timeout, retry policy and idempotency key.
  • Add explicit approval gates for money movement, deletion, publication, customer communication or permission changes.
  • Define trace retention and redact secrets and personal data.
  • For Workspace Agents, document workspace role, sharing scope, connected apps and publishing owner.

Tests that must pass

  • Node-to-contract coverage: every old graph node maps to code, an agent instruction, a tool, or an explicit retirement decision.
  • Golden tasks: representative inputs meet factual, formatting and completion criteria.
  • Tool safety: unauthorized calls fail; arguments are validated; retries are idempotent.
  • Handoffs: the correct specialist owns the final answer and context is neither lost nor leaked.
  • State: resumed sessions preserve the needed context and respect tenant boundaries.
  • Guardrails: risky cases pause for review and cannot bypass approval through prompt injection.
  • ChatKit: login, session creation, attachments, widgets, error recovery and accessibility work on desktop and mobile.
  • Operations: traces, alerts, cost, p95 latency and failure-rate thresholds are visible.

Staged rollout

  1. Run the export locally with tools mocked or in dry-run mode.
  2. Use replay tests against saved Agent Builder cases.
  3. Release to the workflow owner and internal staff.
  4. Canary one low-risk tenant or one percent of eligible sessions.
  5. Expand by workflow, not all Agent Builder traffic at once.
  6. Freeze edits in Agent Builder after the replacement becomes the source of truth.
  7. Complete cutover and archive the export, graph screenshots and rollback instructions before November 30.

Rollback

Put backend selection behind a server-side flag such as agent_runtime=builder|sdk|workspace. Keep the Agent Builder workflow unchanged during the canary, and do not rotate or delete its credentials until the replacement is stable. If thresholds fail, stop new traffic to the replacement and restore routing to Agent Builder while it remains available.

For side-effecting tools, rollback also requires reconciliation: compare idempotency keys and external audit logs before replaying work. After November 30, Agent Builder is no longer a viable rollback target, so the archived export and last known-good SDK/workspace configuration become the recovery path.

Replacements and limitations

Agents SDK gives engineers control over typed code, tools, MCP, storage, runtime behavior, tracing and deployment. That control also creates operational responsibility. Workspace Agents simplify team creation and sharing inside ChatGPT, but access depends on an eligible workspace, and connected apps, permissions and publishing need separate review.

Neither path is a guaranteed behavioral copy. The export does not convert the graph. Strongly deterministic workflows may need a conventional service or state machine with the agent limited to bounded reasoning tasks.

The useful “graveyard” lesson

Agent Builder’s retirement is useful history only when it changes architecture. Do not let a visual builder become the sole specification of a business process. Keep the workflow contract, tool schemas, test cases and permissions in portable artifacts. That turns a retired product from a museum entry into a migration playbook—without launching a second, overlapping “AI tool graveyard.”

Official sources

Bottom line: export now, choose the runtime deliberately, rebuild permissions and tests, canary one workflow at a time, and leave Agent Builder before November 30.