How to Use ChatGPT's Agent Builder to Create Custom Agents

OpenAI Agent Builder is still usable by existing users, but it is no longer a sensible place to begin a long-lived workflow. OpenAI deprecated it on June 3, 2026 and scheduled it to shut down on November 30, 2026. That leaves two practical jobs for the builder now: understanding or maintaining an existing graph, and extracting the behavior you need to move elsewhere.

This guide covers both. It shows how to structure an Agent Builder workflow so that inputs, model decisions, tool calls, and approvals have clear boundaries. It also explains where the canvas stops and application code needs to take over.

The short answer

• Agent Builder is OpenAI's visual canvas for multi-step agent workflows. It supports typed connections, preview runs, versioned publishing, and code export, but it is now listed under legacy APIs in the current Agent Builder documentation.
• Existing workflows can run during the transition. OpenAI recommends the Agents SDK for agents that should continue as code and ChatGPT Workspace Agents for agents that teammates should build through natural-language instructions.
• A reliable workflow starts with an explicit input contract. Named values such as question, customer_tier, and region are safer and easier to route than one unstructured text blob.
• Model guardrails do not replace authorization. Permission checks, transaction limits, idempotency, and final validation belong in deterministic code around any consequential tool.

Which "ChatGPT agent builder" do you mean?

The search term points to several different OpenAI products. Their editors may look related, but they solve different problems.

That distinction matters because OpenAI now says new GPT creation is limited to eligible Business, Enterprise, and Edu workspaces, while Workspace Agents are controlled by workspace access and permissions. A tutorial written for the API-platform canvas will not match either ChatGPT editor. For more detail on adjacent ChatGPT-native options, see how to create a custom GPT and how ChatGPT agent mode works.

How an Agent Builder workflow fits together

Agent Builder connects nodes with typed edges. Each edge is a data contract: an earlier node produces fields that the next node expects. The official node reference groups the available pieces into core nodes, tool nodes, logic nodes, and data nodes.

For a support workflow, a useful graph might receive a question, retrieve the relevant policy, draft an answer, and request approval before any account change. The canvas makes that sequence visible. Reliability still depends on the contract at each handoff.

Start with a narrow outcome

Write the success condition before adding nodes. "Help with returns" is too loose. A better target is:

Answer a returns question from approved policy content. If the policy does not support a clear answer, send the case to a person. Never issue a refund from the model's recommendation alone.

This statement separates informational work from an irreversible action. It also gives you obvious test cases: an answer supported by policy, a request missing required context, and a request that needs approval.

Define the input contract in the Start node

The Start node exposes the user's text as input_as_text and can include state variables. Use those variables to make context explicit. For example:

question: string
customer_tier: string
region: string
order_id: string | null

Do not pass an entire customer record because it happens to be available. Pass the smallest set of fields the workflow needs. Validate allowed regions and customer tiers before the values reach a privileged tool.

OpenAI's safety guidance recommends fixed schemas, required field names, and structured outputs between nodes. That limits the free-form text a malicious or confused input can push into later steps.

Give the Agent node a bounded decision

An Agent node contains its instructions, tools, and model configuration. Keep its responsibility narrow enough that you can inspect its output. For the support example, require a structured result such as:

{
  "answer": "string",
  "policy_source": "string",
  "needs_human": true,
  "requested_action": "none"
}

The model can draft an answer and classify the next step. It should not decide whether the current user is authorized to receive account data or whether a payment operation may proceed. Those checks need facts and rules from your application.

If the workflow has several distinct decisions, give each Agent node one job. The node reference says you can add as many Agent nodes as you need, but OpenAI's public documentation does not state a maximum for total nodes in a workflow. An undocumented ceiling is not a capacity guarantee. More nodes also mean more handoffs, more possible tool failures, and a larger evaluation surface.

Connect retrieval and external tools deliberately

Use File search when the source material lives in an OpenAI vector store. Use an MCP node when the workflow needs a supported connector, a third-party MCP server, or your own remote server. The distinction is documented in the Agent Builder node reference.

Give every tool a narrow input schema and predictable error output. A tool called get_order_status(order_id) is easier to secure than run_customer_action(request). Keep read and write operations separate so an approval can sit directly before the write.

The model should receive only the tool result it needs. OpenAI warns that private data can leak when a model sends more context to an MCP server than the user intended, even without an attacker. Its Agent Builder safety guide recommends structured data flow, cautious access, and approval for tool operations.

Put guardrails and hard controls in different layers

Guardrail nodes monitor prior output for unwanted content and produce a pass or fail by default. Route a failure to an end state or a safer retry.

Use them. Then enforce the rules that cannot depend on model judgment in code:

An instruction such as "never refund more than the allowed amount" is useful context for the model. It is not the limit. The tool that performs the refund must reject an unauthorized amount even if every earlier node says to proceed.

Route decisions with logic nodes

Agent Builder provides if/else, while, and human approval nodes. Use if/else for classifications with a closed set of outcomes. Use while only when its exit condition is explicit and independently checked. Put human approval immediately before the tool that causes the side effect.

For the support example, needs_human = true should route to review. A requested account change should route to approval and then to a narrowly scoped write tool. A rejected approval should end the branch without calling that tool.

Preview, publish, and deploy without losing the contract

Preview the failure paths

Agent Builder's Preview feature lets you run a workflow with sample input, attach files, and inspect each node's execution. Test the paths that could change the result:

• required input missing or malformed
• retrieved policy absent or contradictory
• prompt injection inside user text or retrieved content
• tool denied, timed out, or returned an invalid shape
• approval rejected
• the same write requested again after a retry

Check each node's input and output rather than grading only the final answer. A plausible answer can hide the wrong policy source or an unsafe tool argument.

Publish a versioned snapshot

Publishing creates a major version of the workflow. OpenAI's guide says you can create later versions or specify an older one in API calls. Record the published version beside the test set that passed. Otherwise, a rollback tells you which graph returned, but not whether its surrounding tools and policies still match.

Choose the deployment path with migration in mind

Existing hosted workflows can still connect to ChatKit during the transition. For new ChatKit work, OpenAI now directs developers to a custom server integration backed by their own agent implementation.

That server is important. The ChatKit documentation requires it to authenticate each application user and send a unique user identifier when creating a session. This is where identity, access checks, secret handling, and application-specific recovery logic belong.

Where Agent Builder stops being the right tool

The shutdown date is the clearest boundary, but it is not the only one.

Authentication failures need an application owner

OpenAI's MCP documentation says connector requests use an OAuth access token and that OAuth registration and authorization must be handled separately by your application. The Agent Builder docs do not promise that a hosted graph will refresh an expired credential or resume a partially completed sequence.

Treat credential expiry as a tool failure. Stop before any dependent write, preserve enough state to retry safely, and ask the user to reconnect when needed. If a workflow must refresh tokens, retry transient errors, or resume without duplicating an action, put that behavior in a backend you control.

The canvas is not a transaction boundary

A visual route can express an approval or failure branch. It cannot make two external systems commit atomically. Use backend code when a workflow needs durable queues, idempotent retries, secret rotation, fine-grained audit records, or compensation after a partial failure.

The practical test is simple: if a duplicated or half-completed tool call could cost money, alter customer data, or create a compliance incident, the model graph should propose the action and a deterministic service should enforce it.

Exported code is a migration starting point

Agent Builder can export Agents SDK code in TypeScript or Python. OpenAI's migration guide explicitly says the process does not convert the workflow graph or guarantee that behavior transfers unchanged.

Review the export path by path. Recreate state handling, tool authentication, guardrails, approvals, and error routes in the destination. Run the same test cases against the old and new implementations before sending production traffic to the replacement.

Cost follows the work the workflow invokes

OpenAI said at launch that Agent Builder was included with standard API model pricing. Model and tool charges can change, so use the current API pricing page for the exact configuration you plan to run. Measure repeated loops, retrieval calls, and failed retries in the same evaluation set as answer quality.

Pick the replacement by ownership model

Do not choose by whichever editor looks easiest in a demo. Choose the surface whose owner can operate the workflow when authentication breaks, a tool changes its schema, or a user disputes an action.

Migration checklist for an existing Agent Builder workflow

• Inventory every published version, prompt, state variable, structured output, tool, approval, and failure branch.
• Open the Code dialog and copy the complete TypeScript or Python export while you still have access.
• Store test inputs and expected outcomes outside the retiring product. OpenAI has placed the Evals platform on the same November 30, 2026 shutdown schedule.
• Decide whether the replacement belongs in your application or in a managed ChatGPT workspace.
• Rebuild authentication and authorization outside model instructions.
• Test missing inputs, denied approvals, expired credentials, tool timeouts, malformed results, and duplicate writes.
• Compare the old and new paths on the same cases, then move traffic gradually and keep a rollback route.

The useful lesson in Agent Builder survives the product: make every handoff explicit. Name the inputs. Constrain model output. Separate advice from authority. Put irreversible actions behind controls that do not depend on the model agreeing with them.