OpenAI's Practical Guide to Building Agents, Simplified

Quick answer: OpenAI's practical guide to building agents says to build one only where rules struggle: messy judgement, sprawling rulesets or unstructured data. Give it three parts (a model, tools and clear instructions). Start with a single agent in a loop, split into a manager or handoff design only when needed, and layer guardrails plus human escalation.

OpenAI's A practical guide to building agents is a PDF aimed at product and engineering teams building their first agent. It is based, OpenAI says, on lessons from customer deployments. Its code samples use OpenAI's own Agents SDK (software development kit), but the ideas carry over to any stack.

Here is the guide in plain English. It is part of our AI software development lifecycle series.

What does OpenAI mean by an "agent"?

OpenAI's guide defines agents as systems that independently get tasks done for you. A workflow here just means the sequence of steps needed to reach the user's goal, such as resolving a support ticket or committing a code change.

Two traits make something an agent, according to the guide:

1. A large language model (LLM) runs the workflow and makes decisions. It notices when it is done, corrects itself, and can stop and return control to the user if things go wrong.
2. It has tools to fetch context and take actions, and it picks the right one for the moment, inside clearly defined guardrails.

A simple chatbot, a one-shot LLM call or a sentiment classifier is not an agent in this definition, because the model is not controlling the workflow.

When should you build an agent?

The guide contrasts a rules engine, which works like a checklist, with an agent, which it likens to an experienced investigator weighing context. Its fraud-checking example makes the point: rules flag known patterns; an agent can spot something odd even when no rule is broken.

OpenAI suggests prioritising workflows that have resisted automation before:

Signal	What it looks like	OpenAI's example
Complex decisions	Judgement calls, exceptions, context matters	Approving refunds
Hard-to-maintain rules	Rulesets so tangled that updates are costly or risky	Vendor security reviews
Unstructured data	Reading documents, natural language, conversation	Processing a home insurance claim

If your use case does not clearly hit one of these, the guide says a deterministic (fixed-logic) solution may be enough. That is worth taking seriously: an agent you did not need is just a slower, less predictable program.

What are the three foundations of an agent?

OpenAI breaks every agent into a model, tools and instructions.

Model: start big, then shrink

Not every step needs the most capable model. Classifying intent might suit a small, fast one; deciding a refund might need a stronger one. The guide's approach:

1. Set up evals (repeatable tests of output quality) to get a baseline.
2. Hit your accuracy target with the best models available.
3. Then swap in smaller models where they still pass, to save cost and latency.

Starting big avoids blaming the design for what was really a model limit. We go deeper on evals in AI evals for beginners.

Tools: data, action and orchestration

The guide sorts tools into three kinds:

• Data tools fetch context: query a database, read a PDF, search the web.
• Action tools change things: send an email, update a customer record, pass a ticket to a person.
• Orchestration tools are other agents used as tools, such as a refund agent or a research agent.

It asks for standard, well-documented, tested and reusable tool definitions. For old systems with no application programming interface (API), it mentions computer-use models that operate the app's screens like a person would.

Instructions: turn your existing docs into routines

The guide's tips for writing agent instructions:

1. Reuse what you have. Support scripts, policies and operating procedures make good starting points.
2. Break tasks into smaller steps. Dense documents become clear numbered routines.
3. Make every step an action. "Ask for the order number" or "call the account lookup", even down to the wording of a message.
4. Cover edge cases. Say what to do when information is missing or the user asks something unexpected.

OpenAI also suggests using a capable reasoning model to convert a help-centre article into a numbered instruction list.

How should you orchestrate: one agent or many?

OpenAI says teams usually do better building up gradually than starting with a complex, fully autonomous design.

Single-agent systems

One model, with tools and instructions, runs in a loop. Every design needs the idea of a run: keep looping until an exit condition, such as a final-answer tool being called, a reply with no tool calls, an error, or a maximum number of turns.

To avoid juggling many prompts, the guide suggests one prompt template with variables (customer name, tenure, common complaints). New cases mean new variable values, not a rewrite.

When to split into multiple agents

OpenAI's general advice is to get the most out of a single agent first. More agents add overhead. It gives two signs it is time to split:

• Complex logic. The prompt is full of if-then-else branches and the template no longer scales.
• Tool overload. The issue is overlap more than count. The guide says some teams manage more than 15 distinct tools, while others struggle with fewer than 10 similar ones. Try clearer names and descriptions first.

Manager pattern vs decentralised handoffs

	Manager (agents as tools)	Decentralised (handoffs)
Who is in charge	One central manager agent	No single boss; agents are peers
How work moves	Manager calls specialists like tools	One agent hands control to another
Who talks to the user	Always the manager	Whichever agent holds control
Good for	One unified voice that combines results	Triage, where a specialist should fully take over
Guide's example	Translate "hello" into three languages via three translator agents	A triage agent passes a delivery question to an order-management agent

In a handoff, the conversation state travels with it, and the receiving agent can optionally hand back. The guide also contrasts declarative graph frameworks, where you draw every branch up front, with its own code-first SDK, though that is partly a product pitch.

What guardrails does OpenAI recommend?

The guide treats guardrails as layered defence: no single check is enough, but several together make an agent sturdier. It adds that they work alongside, not instead of, proper authentication, access control and normal software security.

Types it lists:

• Relevance classifier: flags off-topic requests.
• Safety classifier: catches jailbreaks and prompt injection, such as attempts to extract the system prompt.
• PII filter: stops the output exposing personally identifiable information.
• Moderation: flags harmful or abusive input.
• Tool safeguards: rate each tool low, medium or high risk, based on read-only versus write access, reversibility, permissions and financial impact. High-risk tools can trigger extra checks or a human.
• Rules-based protections: blocklists, length limits and regular-expression filters for known threats.
• Output validation: checks that replies fit your brand and values.

Its heuristic for building them: start with data privacy and content safety, add guardrails as real failures appear, and keep balancing security against user experience. In the Agents SDK, guardrails run alongside the main agent by default ("optimistic execution") and raise an exception if they trip.

When should a human step in?

The guide calls human intervention a critical safeguard, especially early on, when it helps uncover failures and build an evaluation cycle. In support, that means escalating to a person; for a coding agent, handing back to the user. Two triggers:

1. Failure thresholds. Cap retries or actions. If the agent keeps failing, for example misreading what the customer wants, escalate.
2. High-risk actions. Sensitive, irreversible or high-stakes steps, such as cancelling orders, large refunds or payments, need a human until you trust the agent.

How does it line up with Anthropic's advice?

Read alongside Anthropic's Building Effective Agents, simplified, the two guides agree more than they differ:

• Both say start simple. Anthropic: try a single call before any agentic system. OpenAI: try a single agent before multi-agent.
• Both obsess over tools. Anthropic's agent-computer interface advice and OpenAI's "clear names, parameters and descriptions" tip are the same lesson.
• Both want ground truth and limits. Stopping conditions, maximum turns and human checkpoints appear in each.
• Different vocabulary. Anthropic separates fixed workflows from free agents. OpenAI uses "workflow" for the task itself and calls the system an agent once a model controls it. OpenAI's manager pattern is close to Anthropic's orchestrator-workers.
• Different emphasis. OpenAI spends more pages on guardrails and business use cases; Anthropic on pattern choice and tool design. OpenAI's guide also promotes its SDK, while Anthropic warns frameworks can hide what is going on.

What we do at Pocket Grove

In our studio, Cong Le maintains around 53 iOS and Android apps with Claude Code and Codex. Our view, not a study:

• One main agent, subagents only for genuinely parallel work. That is OpenAI's "maximise one agent first" in practice.
• Instructions from existing docs. A shared AGENTS.md (with a CLAUDE.md symlink), per-app TASKS.md and skills are our routines.
• Headless tests as the feedback loop, rather than trusting the agent's own summary.
• A human approval gate for high-risk actions. Nothing ships to an app store without Cong's explicit sign-off, which matches OpenAI's high-risk trigger.

For how we keep those instruction files lean, see stop putting everything in CLAUDE.md.

Sources

• A practical guide to building agents — OpenAI — https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf
• Building Effective Agents — Anthropic — https://www.anthropic.com/engineering/building-effective-agents