How to Build an AI Agent With OpenAI/ChatGPT
Learn how to build an OpenAI agent using the Agents SDK. A step-by-step guide to tools, handoffs, and multi-agent workflows for beginners and pros.
Posted July 27, 2026
Table of Contents
Most people use ChatGPT to get an answer. You type a prompt, you read the reply, and the work is yours to finish. An OpenAI agent flips that around. It can take a task and run it for you across multiple steps, calling tools, reading files, and checking its own work before it gives you a final output. The difference matters when the job is not "answer my question" but "do this for me."
This guide shows you how to build an OpenAI agent from the ground up. You will start with one simple agent, give it the right tools, and then grow into multi-agent workflows where specialized agents pass work to each other. The early sections are written for someone building their first agent. The later sections go deeper for readers who already know the basics and want to coordinate several agents in one system. You do not need to be an expert to follow along, but you should be comfortable reading a little Python code.
What is an OpenAI Agent?
An OpenAI agent is a model paired with a system prompt that tells it how to behave, a set of tools it can call, and a loop that runs until the work is done. A plain ChatGPT prompt gives you one reply in plain text and stops. An agent keeps going. It can decide it needs to search the web, run that search, read the result, decide it needs one more piece of data, fetch that too, and only then write its answer.
Here is the practical split between the two:
| Single ChatGPT Prompt | OpenAI Agent | |
|---|---|---|
| Steps | One turn and one reply | Multiple steps until the task is done |
| Tool use | None by default | Calls tools, reads results, and continues |
| Output | Plain text | Plain text or structured output your app can read |
| Control | You guide every turn | The agent decides what to do next within your rules |
| Best for | Quick aswers and drafts | Tasks that need several actions on your behalf |
The core parts of any agent are worth naming clearly, because every build you do will use them.
- Model. The OpenAI model that does the reasoning. You pick one based on the task.
- Instructions. The system prompt. This is where you define the agent's job, its limits, and how it should respond.
- Tools. The functions and services the agent can call to take action or pull in data.
- The agent loop. The built-in cycle that handles each tool call, sends the result back to the model, and repeats until the model returns a final output.
OpenAI Responses is the interface underneath all of this. The Responses API is the lower-level way to call a model with tools and manage the logic yourself. When one model call plus your own code is enough, you can use it directly. When you want something to own the orchestration for you, you move up to the Agents SDK, which we cover next.
Read: The Different Types of AI Agents & What You Need to Know About Each
Should You Build an OpenAI Agent?
Not every task needs an agent. If a job follows fixed rules and the same input always leads to the same output, a normal script or a single ChatGPT prompt will do it faster and cheaper. An agent earns its place when the work involves judgment, changing conditions, or messy input that rules cannot cover cleanly.
Three kinds of work fit agents well:
- Complex decisions. The task needs judgment, handles exceptions, or depends on context. Approving a refund is a good example. The right answer shifts based on the order, the customer history, and the reason for the request, so a fixed checklist falls short.
- Rules that are hard to maintain. A system has grown into a tangle of conditions that breaks every time you update it. A vendor security review with dozens of branching checks is one case. An agent can reason through the policy instead of forcing you to maintain every branch by hand.
- Heavy unstructured input. The work means reading documents, interpreting plain language, or holding a real conversation. Processing an insurance claim from a written description fits here, since the useful information is buried in free text rather than tidy fields.
If your task does not match one of these, build the simpler thing first. You can always move up to an agent later when the work grows.
Read: The 3 Most Important Principles of Building AI Agents
Meet the OpenAI Agents SDK
The OpenAI Agents SDK is the framework most builders should start with. It is a lightweight package for building agents and multi-agent workflows, and it handles the parts that are tedious to wire up by hand. It runs on OpenAI Responses by default, and it also works with different models from other providers, so you are not locked to one model family.
The Agents SDK gives you a small set of building blocks:
- Agent definitions. Create a new agent with a name, instructions, a model, and a list of tools.
- Function tools. Turn any Python function into a tool the model can call, with the input schema generated for you.
- Hosted tools. Use the tools OpenAI runs for you, such as web search, file search, code interpreter, and computer use.
- Handoffs. Let one agent pass control to another agent built for a specific job.
- Guardrails. Run output validation and safety checks alongside the agent so a wrong or off-topic answer gets caught.
- Human in the loop. Pause an agent so a person can review or approve a step before it continues.
- Sessions. Keep conversation context across turns without you managing it.
- Tracing. See every step, tool call, and handoff so you can debug behavior.
The SDK grew out of OpenAI's earlier experiments and has an active open source community around it, with code, examples, and issues you can learn from. It also supports more advanced patterns once you need them, including sandbox agents that work in a container over longer tasks and real-time voice agents.
Read: Claude vs. ChatGPT vs. Gemini: Pros & Cons and Which AI Tool is Best for You
When Should You Use the SDK Instead of Building on the Responses API Directly?
Use the SDK when your application owns orchestration, tool execution, approvals, and state, and you would rather not write that loop yourself. Use the Responses API directly when a single model call plus your own application logic covers the job. Many teams do both. They rely on the SDK for managed workflows and call the Responses API for the simpler paths. The SDK ships for both Python and TypeScript. The examples here use Python.
Setup and Requirements Before You Start
You need Python 3.10 or newer and an OpenAI API key. There are two ways to install the SDK. Pick whichever matches how you already work.
Using venv and pip:
bash python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install openai-agents Using uv, which is faster if you have it: bash uv init uv add openai-agents
For voice support, add the voice group: pip install 'openai-agents[voice]' or uv add 'openai-agents[voice]'. Then set OPENAI_API_KEY in your environment so the SDK can authenticate.
Pick your first model with cost in mind. A good method is to build your prototype with the most capable model, so you have a performance baseline, then test smaller, faster models on the simpler parts of the task. A small model can handle a basic lookup or an intent check. Save the larger model for the steps where a wrong call is expensive, like deciding whether to approve a refund.
One more setup point. Set the expected response language in your instructions, for example English (United States), so the agent's behavior stays predictable for your users. Spelling out small expectations like this in the system prompt removes guesswork later.
Build Your First Single Agent
Here is the shortest path to a working single agent. You define it, you run it, and you read the final output.
python from agents import Agent, Runner agent = Agent( name="History Tutor", instructions="You answer history questions clearly and briefly.", ) result = Runner.run_sync(agent, "When did the Roman Empire fall?") print(result.final_output)
That is the whole pattern. You import the pieces, you define a new agent with a name and instructions, and the Runner handles the run. The final_output is what the model returns after the loop finishes.
Now give the agent a tool so it can do more than talk. Function tools turn a normal Python function into something the model can call.
python from agents import Agent, Runner, function_tool @function_tool def get_weather(city: str) -> str: """Return the weather for a city.""" return f"The weather in {city} is sunny." agent = Agent( name="Weather Assistant", instructions="Answer weather questions. Use get_weather when it helps.", tools=[get_weather], ) result = Runner.run_sync(agent, "What is the weather in Chicago?") print(result.final_output)
Giving an agent a tool does not force it to use that tool. The model reads the user input, decides whether a tool call is the right move, and either calls it or answers directly. When it does call the tool, the result feeds back into the loop, and the model uses it to write the answer.
Hosted tools extend this further without you wiring up each integration. With hosted tools, the agent can search the web, read files, run code in a code interpreter, or use a computer to work through an app the way a person would. You add the hosted tool to the agent, and the SDK handles the connection.
Giving Agents the Right Tools
Tools are how an agent moves from talking to doing. Without them, an agent can only reason and reply. With them, it can pull in data, take action, and work across the systems you already run. Picking the right tools for each step is most of the build.
It helps to think about tools by what they do for the agent:
- Data tools pull in the context the agent needs to work. These read a database, search the web, or open a PDF so the agent has the facts before it acts.
- Action tools change something in the outside world. These send an email, update a customer record, or process a return. Use them when the agent needs to do more than answer.
- Orchestration tools are other agents. One agent can call another as a tool, hand off a subtask, and use the result. This is how you coordinate a team of specialists, covered in the multi-agent section below.
In the Agents SDK, you build these as one of two kinds:
- Function tools are functions you write. The SDK turns a normal Python function into something the model can call and generates the input schema for you. Use them for your own logic, your own data, and any action specific to your business.
- Hosted tools are services OpenAI runs for you. These cover common needs like web search, file search, code execution, and computer use. You add the hosted tool to the agent, and the SDK handles the connection.
You also control how the agent uses its tools. You can let the model decide whether to call a tool, require it to use some tool, or point it at one specific tool. Letting the model choose works for most cases. Requiring a tool helps when an answer without data would be wrong.
To connect an agent to your own systems, you can use MCP, an open standard for exposing tools and data to a model. MCP lets the agent reach your files, apps, and data so it can act on your behalf inside the systems you already use.
Guardrails: Keeping Agent Output Safe
Once an agent can take action, guardrails keep a wrong or unsafe response from reaching your users. Think of them as layers rather than a single gate. One check on its own misses things. Several specific checks running together catch far more. The Agents SDK runs guardrails alongside the agent, so a draft answer gets validated while the agent works, and a failed check stops the response before it goes out.
Most production agents use some mix of these guardrail types:
- Relevance check: Flags answers that drift off topic, so the agent stays inside the job you gave it. A question like "How tall is the Empire State Building?" to a support agent gets caught here.
- Safety check: Catches inputs that try to break your agent, such as jailbreaks or prompt injections that aim to expose your system instructions.
- PII filter: Scans output for personal information like names, account numbers, or contact details, and stops it from leaking.
- Moderation: Flags harmful or inappropriate content so the agent keeps interactions safe and respectful.
- Tool safeguards: Rate each tool by risk, from low to high, based on whether it only reads data or can change it, whether the action can be undone, and how much is at stake. A high-risk tool, like one that issues a large refund, can pause for an extra check or route to a person before it runs.
- Rules-based filters: Simple, fixed checks such as blocklists, input length limits, and pattern matching that stop known problems before they reach the model.
You do not need every guardrail on day one. Start with the risks you already know, usually data privacy and content safety, then add more as real use turns up new edge cases.
From One Agent to Multi-Agent Workflows
A single agent that tries to do everything gets unreliable as the job grows. The fix is to split the work across specialized agents, each with focused instructions and the right tools. This is the idea behind multi-agent workflows, and the Agents SDK gives you two ways to coordinate them.
- Handoffs. One agent passes control of the turn to another agent. A handoff is a one-way transfer: the new agent takes over, and the conversation state goes with it. Picture a support system. A triage agent reads the request, identifies what the customer wants, and hands off to the agent built for that job. If the customer wants money back, the triage agent hands the conversation to a refund agent that owns refunds and nothing else. This is sometimes called the decentralized pattern, since the agents act as peers.
- Agents as tools. Here, a manager agent stays in control and calls other agents as if they were tools. The manager sends a subtask to a specialist, gets the result back, and assembles the pieces into one final output. Use this when you want one agent to own the answer and coordinate the rest. This is sometimes called the manager pattern.
| Pattern | Who Owns the Answer | Good For |
|---|---|---|
| Handoffs | The agent that receives the handoff | Routing a request to the right specialist |
| Agents as tools | The manager agent | One coordinator pulling work from several specialists |
Across these steps, structured output keeps the system reliable. When an agent returns structured output instead of plain text, the next agent or your own application can read the data cleanly and act on it without guessing. This matters as soon as one step's result becomes another step's input.
A Worked Example: A Customer Support Agent
Put the pieces together in one scenario you can picture. A company wants an agent to handle incoming support requests from customers.
- Map the workflow. A request arrives. A triage agent reads the context and decides where it should go.
- Add the specialists. A refund agent handles refund requests with tools that look up orders and process returns. A billing agent handles billing questions with its own tools and its own instructions. Each one is a single agent with a narrow job.
- Route with handoffs. The triage agent identifies the request type and hands off to the matching specialist. The customer talks to the right agent without knowing a handoff happened.
- Validate before responding. Guardrails check the draft answer before it reaches the customer. An off-scope reply or an unsafe one gets caught, so a wrong answer does not go out.
This same shape works for many business cases. The triage step routes, the specialists do focused work, and output validation protects the customer-facing answer.
Read: How to Build an AI App: Best Process, Tools, & Tips (2026)
Testing, Tracing, and Going to Production
Building the agent is the start. Getting it ready for real users takes a few more steps.
- Trace your runs. Built-in tracing shows each step, tool call, and handoff. When behavior goes wrong, the trace tells you where.
- Run evals. Set up evaluations to measure accuracy. Run them before and after you swap a large model for a smaller one, so you can see whether the cheaper model still meets your target.
- Deploy with controls. For business and enterprise use, the SDK supports sandboxes that run an agent's code and file work in a safe, isolated space. Add approvals and human review for the steps where a person should sign off. Enterprise clients can also customize permissions and keep their data protected.
Some steps should pause for a person. A human-in-the-loop step lets the agent hand control back when it hits its limits, which protects your users and gives you a way to catch failures early in a deployment. Two triggers are worth building in from the start:
- Too many failed tries. Set a limit on retries or actions. If the agent cannot understand what the user wants after a few attempts, it should stop and pass the work to a person rather than guess.
- High-risk actions. Steps that are sensitive, hard to undo, or expensive should wait for human approval until you trust the agent with them. Canceling an order, authorizing a large refund, or sending a payment all fit here.
Common Mistakes to Avoid
Vague instructions
A thin system prompt produces unpredictable behavior. Define the job, the limits, and the format you want, and spell out how the agent should handle the variables it will encounter so it behaves the same way each time.
Too many tools at once
An agent with a long list of tools makes worse choices. The problem is rarely the count itself but the overlap between similar tools. Give each agent the tools it needs to interact with your systems and no more.
Treating the agent like a chatbot
This is the mistake builders run into most. If the agent tracks progress inside the chat history, the workflow falls apart the moment a task runs across more than one session. Keep the real state in your database, with explicit steps the agent reads rather than rebuilds, so the model proposes the next move but does not become the source of truth for what already happened. The model handles reasoning and language; the process stays deterministic.
Skipping output validation
Without guardrails, a wrong or off-topic answer reaches your users. Add checks before the agent responds so its capabilities do not outrun its safety.
Using the largest model everywhere
This raises cost and latency for no gain on simple steps. Match the model to the task so smaller models handle the easy work effectively, and the capable model is saved for the hard calls.
No tracing
Without traces, you cannot tell why an agent behaved the way it did. Turn tracing on from the start so you can explore each run, see where steps go wrong, and prove the agent did not skip anything.
When several agents collaborate, these habits matter even more, since one weak step can quietly derail the rest of the workflow.
The Bottom Line
Building an OpenAI agent comes down to a clear path. Define one agent, give it sharp instructions and the right tools, and read its final output. Add function tools and hosted tools so it can act on real work. When one agent starts doing too much, split the job across specialized agents and coordinate them with handoffs or a manager. Then add guardrails for output validation, turn on tracing, and run evals before you ship. Start small, prove each piece works, and grow the system as the work demands.
Build Your Agent With Expert Support
If you are working toward a goal that calls for this kind of hands-on, practical skill building, Leland's AI Coaches can help you map the steps and stay accountable. You can also enroll in the AI Builder Program to learn the full process in a structured track, or join a live bootcamp to build alongside instructors and other learners in real time.
Top Coaches
Keep learning and read these next:
- Agentic AI vs. AI Agents: Differences & What You Need to Know
- The 5 Best AI Agents Courses & Bootcamps to Learn Automation (2026)
- AI for Programming & Software Engineering: Use Cases, Examples, & Expert Tips (2026)
- AI & Agents for SEO: Use Cases, Examples, & Expert Tips (2026)
- How to Become an AI Consultant: What It Pays, How to Get Started, and Where to Find Clients
- The 5 Best AI Tools & Agents for Note-Taking: Reviewed & Ranked (2026)
FAQs
What is the difference between the Agents SDK and the Responses API?
- The Agents SDK is a runtime that manages the agent loop, tool calls, handoffs, and state for you, while the Responses API is the lower-level way to call a model with tools and run that logic yourself. Use the SDK when you want it to own orchestration. Use the Responses API directly when one model call plus your own code is enough.
Do I need to know Python to build an OpenAI agent?
- No, but basic coding skills help. The SDK is built for both Python and TypeScript, and the examples in this guide use Python. You can follow the setup with light coding experience and lean on the open-source community examples to learn faster.
What is the difference between a single-agent and a multi-agent workflow?
- A single agent handles a task on its own, while a multi-agent workflow splits the task across specialized agents. Those agents pass work to each other through handoffs or by acting as tools for a manager agent. Use a single agent until the job gets too complex for one set of instructions and tools.
Can an OpenAI agent search the web and read files?
- Yes. Hosted tools let an OpenAI agent search the web, read files, run code, and use a computer. This lets the agent pull in data and take action across systems instead of only answering from what it already knows.
How much does it cost to run an agent?
- The cost of running an OpenAI agent depends on the model you choose and how many steps and tool calls each task takes. You lower it by using smaller, faster models for simple steps and saving the most capable model for the hard ones.
What are handoffs, and when should I use them instead of agents as tools?
- Handoffs let one agent pass control of the conversation to another agent, so use them when you want a specialist to fully take over. Use agents as tools instead when you want one manager agent to stay in control and call specialists for pieces of the work.
