OpenAI Agent Builder deprecation: how to migrate before 30 November

Under the OpenAI Agent Builder deprecation announced on 3 June 2026, Agent Builder shuts down on 30 November 2026. The hosted Evals platform and reusable prompt objects shut down the same day. ChatKit stays, but a ChatKit app backed by a hosted Agent Builder workflow needs a backend of its own by then. OpenAI’s migration guide offers two routes. Export the workflow as Agents SDK code and run it yourself, or rebuild it as a workspace agent in ChatGPT.¹²

Existing evals go read-only sooner, on 31 October, about three weeks from now, so any final baseline run on OpenAI’s platform has to happen before then.¹ The export needs care too. OpenAI says it doesn’t convert the workflow graph and doesn’t guarantee that every behaviour carries over unchanged.²

Below are the dates, the changes for ChatKit apps, how to choose a route, a six-step plan with a code sketch, how to replace the evals, and where a migrated workflow can behave differently. Everything is as of 9 October 2026.

What the OpenAI Agent Builder deprecation covers, and when

OpenAI launched Agent Builder in beta on 6 October 2025 as part of AgentKit. The bundle also included ChatKit, a Connector Registry for admins, and new Evals features such as datasets, trace grading and automated prompt optimisation.³ ChatKit remains available and none of the notices mentions the Connector Registry, so AgentKit is only partly deprecated.¹ If the shutdown date holds, Agent Builder will have been available for 420 days.

Dates as of 9 October 2026, from OpenAI’s deprecations page and the GPT-5 model page.¹⁴

The Evals notice reaches further than the dashboard. OpenAI’s guides put Datasets and the dataset-backed Prompt optimizer under the same notice, and graders documented for eval workflows are part of the same transition.⁵⁶¹ The trace-grading guide’s Grade all step opens the evaluation dashboard, which is part of what shuts down.⁷

ChatKit without Agent Builder: what keeps working and what breaks

OpenAI’s ChatKit guide now describes two paths. The custom server integration runs ChatKit on your own infrastructure with the ChatKit Python SDK, connected to any agent service, including one built with the Agents SDK. The Agent Builder-hosted integration is only for existing workflows during the transition window. The guide sends new apps, and apps moving off a hosted workflow, to the custom server path.⁸⁹

In a hosted app, your server creates a ChatKit session with a workflow ID, and the browser fetches a short-lived client secret from your server.⁸¹⁰ Plan for that workflow ID to stop working at the Agent Builder shutdown on 30 November. Moving to your own server changes these parts of the app.

Sources: ChatKit JS and Python docs and the ChatKit API reference, as of 9 October 2026.^11121013

The ChatKit JS docs list three features that only a self-hosted backend gets. Users can cancel a response, the composer gains @-mentions, a tool menu and a model picker, and your server can push effects to the client.¹¹ On the frontend, the change is small:

// Before: ChatKit on a hosted Agent Builder workflow
const options = { api: { getClientSecret: fetchClientSecret } };

// After: ChatKit on your own server
const options = { api: { url: "/api/chatkit", domainKey: "your-domain-key", fetch: fetchWithAuth } };

The domain key comes from registering each hostname that serves the chat on OpenAI’s domain allowlist page. The ChatKit iframe checks the key with OpenAI’s API on load and refuses to load if the key is missing or invalid. OpenAI’s production guide also asks you to authenticate every request to your ChatKit endpoint and to authorise access to threads and attachments with your own user and tenant model.¹⁴

Existing conversations need a decision. The ChatKit API can list threads, filtered by user and up to 100 a page, and list the items in each thread.¹⁵ We found nothing in OpenAI’s docs about what happens to threads stored on the hosted backend after 30 November. If users expect to keep their history, export it and load it into your store before you switch.

Agents SDK or workspace agents: which route fits

OpenAI’s migration guide names two routes, and both start from the same export. The Agents SDK is for teams that build agents in code. Workspace agents in ChatGPT are for building agents in natural language and sharing them with a team.²

Sources: OpenAI’s migration guide, workspace agents announcement and trigger API docs, as of 9 October 2026.²¹⁶¹⁷

We’d decide by who the workflow serves. If it answers your product’s users, through ChatKit or your own API, take the Agents SDK route, because a workspace agent’s API can’t currently return its answer to your code.¹⁷ If it serves your own staff in ChatGPT or Slack and has little fixed branching, a workspace agent is less work. For that route, OpenAI’s steps are to create the agent in ChatGPT, paste the export with a short conversion prompt, review what the builder flags, configure apps and permissions, and preview it on representative inputs before creating it.²

OpenAI also released an Agents API in public beta on 10 September 2026. It runs agents on a managed Codex harness with durable sessions and optional sandboxes, and OpenAI positions it for long-running tasks.¹⁸¹⁹ The Agent Builder migration guide doesn’t list it as a route, and we’d treat it as a separate decision from this migration.

A six-step plan to migrate from Agent Builder

1. Inventory your workflows. Search your code for workflow IDs (wf_) in ChatKit session calls, prompt object IDs (pmpt_) and Evals API calls. For each workflow, note the version your sessions run (the latest deployed one unless the call pins a version) and the state variables they pass.¹⁰ Then list its nodes, the vector stores and MCP connections behind them, and any evals attached to its Agent nodes.²⁰ Mark whether it serves customers or staff.
2. Export them. Open each workflow, select Code, choose Agents SDK and Python or TypeScript, and copy the complete export.² Agent Builder autosaves drafts and publishing creates a versioned snapshot, so check that the export matches the version your sessions run.²¹ Commit each export unchanged, and pull eval data and ChatKit threads in the same pass.
3. Rebuild each in the Agents SDK. Treat the export as a draft. Keep its model and settings, move instructions into versioned code, and replace hosted features node by node, as in the mapping below. Run the result inside your ChatKit server’s respond() or behind your own API.
4. Re-create the evals elsewhere. Rebuild each eval in Promptfoo or your own harness. Before trusting it, re-grade the exported samples with the new graders and check that they reach the old verdicts.
5. Test. Run the hosted and rebuilt workflows on the same inputs while both exist, using eval cases and samples of real traffic. Compare routes taken, tool calls, guardrail results and final answers. Grouping traces by thread ID makes runs easy to line up.²²
6. Switch over. Move the frontend to your server behind a flag, get a domain key for each production hostname, and shift traffic in steps. Keep the hosted workflow as a fallback until the numbers hold, and finish well before 30 November. Then remove workflow and prompt object IDs from your code.

After the switch, check each route’s output against what it produced before. Counting errors isn’t enough, because a counter only sees the failures that reach it. One of our pipelines reported 0 dropped while most of its output was missing.

Mapping Agent Builder nodes to Agents SDK code

Agent Builder has eleven node types.²⁰ Most map to one SDK feature, and the logic nodes become ordinary Python.

Sources: OpenAI’s node reference and the Agents SDK docs, as of 9 October 2026.^202324252627

Two rows need more than a rename. Human approval moves from a step in the graph to a property of a tool call. A run that reaches a tool needing approval pauses and returns the pending calls as interruptions. You approve or reject them on a saved RunState and resume.²⁶ Your app has to show that request to the user, for example as a ChatKit widget with actions. Connector-backed MCP tools need an access token from your code, so the OAuth flow behind the connector becomes part of your app.²⁷

Keep the safety measures OpenAI recommended for Agent Builder workflows. Pass structured outputs between agents, keep approvals on for MCP tools, run guardrails on user input, and put untrusted text in user messages instead of developer instructions.²⁸

A small Agent Builder flow, rebuilt in the Agents SDK

Take a routing flow. A classifier agent returns JSON, an If/else node routes on it, one agent answers with file search over a vector store, and a fallback agent handles everything else. OpenAI’s homework-helper example uses the same classify-and-route pattern.²⁰ A minimal version, written for this post for openai-agents 0.23.1, released on 2 October 2026:²⁹

from typing import Literal

from agents import Agent, FileSearchTool, ModelSettings, Runner, TResponseInputItem, trace
from openai.types.shared import Reasoning
from pydantic import BaseModel

# Keep the model and settings from your export for the first comparison.
MODEL = "gpt-5"
SETTINGS = ModelSettings(store=True, reasoning=Reasoning(effort="low"))


class Route(BaseModel):
    kind: Literal["product_question", "other"]


classifier = Agent(
    name="Classifier",
    instructions="Classify the latest user message. Use product_question for questions about the product.",
    model=MODEL,
    model_settings=SETTINGS,
    output_type=Route,  # the Agent node's JSON output schema
)

product_agent = Agent(
    name="Product answers",
    instructions="Answer from the product documentation. If it has no answer, say so.",
    model=MODEL,
    model_settings=SETTINGS,
    tools=[FileSearchTool(vector_store_ids=["vs_your_store"], max_num_results=5)],
)

fallback_agent = Agent(
    name="Fallback",
    instructions="Reply in two sentences and suggest contacting support.",
    model=MODEL,
    model_settings=SETTINGS,
)


async def run_workflow(history: list[TResponseInputItem], thread_id: str) -> str:
    """history holds the earlier turns plus the new user message."""
    with trace("Support router", group_id=thread_id):
        routed = await Runner.run(classifier, history)
        # The If/else node, written in Python instead of CEL
        if routed.final_output.kind == "product_question":
            next_agent = product_agent
        else:
            next_agent = fallback_agent
        # Pass the classifier's turn on, as exported code does after each agent node
        answer = await Runner.run(next_agent, routed.to_input_list())
    return answer.final_output

Three details carry Agent Builder’s behaviour over. output_type=Route gives the classifier a structured output, as an Agent node’s schema did, and OpenAI’s safety guide recommends structured outputs between agents because they leave no free-text channel for injected instructions.²³²⁸ to_input_list() passes the classifier’s turn to the next agent, which matches how exported code extends the conversation after each agent node.³⁰ group_id ties every trace from one chat thread together, so you can line up a conversation’s runs when comparing versions.²²

Inside a ChatKit server, respond() would load the thread’s items, convert them with simple_to_agent_input, run the classifier, then stream the second agent with Runner.run_streamed and stream_agent_response, as in OpenAI’s advanced integration example.⁹ Our post on cutting an assistant’s time to first word covers a self-hosted ChatKit server on the Agents SDK, including what client tool round trips cost.

The OpenAI Evals deprecation: export first, then rebuild

Existing evals become read-only on 31 October, and the dashboard and API shut down on 30 November.¹³¹ Two jobs follow. Run each eval once more while runs are still possible, so the baseline is recent, and pull everything out through the API before the shutdown.

The Evals API returns what you need. Retrieving an eval returns its testing criteria, which hold the grader definitions. Each run’s output items carry the input row, the sampled input and output with the model and settings used, and every grader’s name, pass flag and score.³² That is enough to rebuild the test set, keep the old scores as a baseline, and check that recreated graders agree with the old ones on the same outputs.

OpenAI recommends Promptfoo, which its cookbook describes as an open-source CLI and library. The migration it describes is manual. You recreate prompts, providers, test cases and assertions in a config file, with no Evals export feature involved. The cookbook warns that similarity scores may differ between systems and that recreated graders, LLM judges especially, need validating before they drive regression decisions.³³ Promptfoo announced on 9 March 2026 that it had agreed to be acquired by OpenAI and would remain open source.³⁴

Your own harness is the other option. Replay the exported input rows through the rebuilt workflow, apply the same checks, repeat each case a few times and compare per-case scores with the baseline. In either tool, call the workflow itself, through a Python provider in Promptfoo or directly in your harness, so the eval sees routing and tool calls as well as the final text.³⁵ Our post on measuring model drift covers paired differences, error bars and pinning everything a score depends on.

Where a migrated workflow can behave differently

The export is a draft. OpenAI’s guide says some behaviour may need rebuilding by hand, and it asks you to review control flow, triggers, tools and permissions while testing. On the SDK route, runtime configuration, auth, permissions and deployment are yours to validate.²

Model and settings. Copy them exactly from the export. An Agent with no model runs on the SDK default, which the docs give as gpt-5.6-luna with reasoning effort none as of 9 October 2026.³⁶ A public export from October 2025 pins gpt-5, and the snapshot behind that alias is removed on 11 December 2026.³⁰⁴¹ Migrate first, measure, then change the model as a separate step with its own eval run.

Conversation history. In a chat workflow, the Start node appended each message to the conversation history.²⁰ The October 2025 export’s entry point takes one input_as_text string and starts a fresh history from it.³⁰ On your ChatKit server, respond() has to load earlier thread items and pass them in. OpenAI’s example loads the last 20, a window worth setting deliberately.⁹

Prompt objects. The SDK’s prompt parameter references prompts saved in the OpenAI platform, and those shut down on 30 November.²³¹ Move instructions into code. OpenAI’s guide on leaving prompt objects says to keep static text first and dynamic values last, so prompt caching still works.³⁷

The guardrails package. Agent Builder’s Guardrails are OpenAI’s open-source safety layer, which also ships as a Python library.³ On PyPI it is openai-guardrails, imported as guardrails.³⁸ guardrails-ai is an unrelated project that installs a module with the same name, so check which one your environment has.³⁹

Secrets. Hosted MCP tools take an authorization value.²⁷ If an export contains one, move it into your secret store before the code reaches a repository.

A checklist for the next seven weeks

By 31 October

• List every wf_ and pmpt_ ID in your code, and every call to the Evals API.
• Export each workflow and commit it unchanged.
• Run a final baseline of each hosted eval, and save its definition, runs and output items.
• Choose a route per workflow. Anything your product’s users touch goes to the Agents SDK.

By mid-November

• Rebuild each workflow with the export’s model and settings pinned.
• Stand up the ChatKit server and its stores, and get a domain key for each production hostname.
• Re-create the evals, and check that the new graders reach the old verdicts on the exported samples.
• Move the ChatKit threads users need to keep into your store.

Before 30 November

• Run the hosted and rebuilt versions side by side and compare routes, tool calls and answers.
• Switch the frontend behind a flag, move traffic in steps, then remove workflow and prompt object IDs from your code.

Before 11 December

• Move any agent pinned to gpt-5 to a current model, as its own change with its own eval run.

Frequently asked questions