Registered users can read the full content for free
Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.
Page
1
A practical
guide to
building agents
Page
2
Contents What is an agent? 4 When should you build an agent? 5 Agent design foundations 7 Guardrails 24 Conclusion 32 2 Practical guide to building agents
Page
3
Introduction Large language models are becoming increasingly capable of handling complex, multi-step tasks. Advances in reasoning, multimodality, and tool use have unlocked a new category of LLM-powered systems known as agents. This guide is designed for product and engineering teams exploring how to build their first agents, distilling insights from numerous customer deployments into practical and actionable best practices. It includes frameworks for identifying promising use cases, clear patterns for designing agent logic and orchestration, and best practices to ensure your agents run safely, predictably,
and effectively. After reading this guide, you’ll have the foundational knowledge you need to confidently start building your first agent. 3 A practical guide to building agents
Page
4
What is an agent? While conventional software enables users to streamline and automate workflows, agents are able to perform the same workflows on the users’ behalf with a high degree of independence. Agents are systems that independently accomplish tasks on your behalf. A workflow is a sequence of steps that must be executed to meet the user’s goal, whether that's resolving a customer service issue, booking a restaurant reservation, committing a code change,
or generating a report. Applications that integrate LLMs but don’t use them to control workflow execution—think simple chatbots, single-turn LLMs, or sentiment classifiers—are not agents. More concretely, an agent possesses core characteristics that allow it to act reliably and consistently on behalf of a user: 01 It leverages an LLM to manage workflow execution and make decisions. It recognizes when a workflow is complete and can proactively correct its actions if needed. In case
of failure, it can halt execution and transfer control back to the user. 02 It has access to various tools to interact with external systems—both to gather context and to take actions—and dynamically selects the appropriate tools depending on the workflow’s current state, always operating within clearly defined guardrails. 4 A practical guide to building agents
Page
5
When should you build an agent? Building agents requires rethinking how your systems make decisions and handle complexity. Unlike conventional automation, agents are uniquely suited to workflows where traditional deterministic and rule-based approaches fall short. Consider the example of payment fraud analysis. A traditional rules engine works like a checklist, flagging transactions based on preset criteria. In contrast, an LLM agent functions more like a seasoned investigator, evaluating context, considering subtle patterns, and identifying suspicious activity even when clear-cut rules aren’t violated. This nuanced reasoning capability is exactly what enables agents to manage complex, ambiguous situations effectively.
Page
6
As you evaluate where agents can add value, prioritize workflows that have previously resisted automation, especially where traditional methods encounter friction: 01 Complex
decision-making: Workflows involving nuanced judgment, exceptions, or
context-sensitive decisions, for example refund approval
in customer service workflows. 02 Difficult-to-maintain rules: Systems that have become unwieldy due to extensive and intricate rulesets, making updates costly or error-prone,
for example performing vendor security reviews. 03 Heavy reliance on unstructured data: Scenarios that involve interpreting natural language,
extracting meaning from documents, or interacting with
users conversationally, for example processing a home insurance claim. Before committing to building an agent, validate that your use case can meet these criteria clearly. Otherwise, a deterministic solution may suffice. 6 A practical guide to building agents
Page
7
Agent design foundations In its most fundamental form, an agent consists of three core components: 01 Model The LLM powering the agent’s reasoning and decision-making 02 Tools External functions or APIs the agent can use to take action 03 Instructions Explicit guidelines and guardrails defining how the
agent behaves Here’s what this looks like in code when using OpenAI’s Agents SDK. You can also implement the same concepts using your preferred library or building directly from scratch. Python 1 2 3 4 5 6 weather_agent = Agent( name= instructions= tools=[get_weather], ) "Weather agent" "You are a helpful agent who can talk to users about the weather.", 7 A practical guide to building agents
Page
8
Selecting your models Different models have different strengths and tradeoffs related to task complexity, latency, and cost. As we’ll see in the next section on Orchestration, you might want to consider using a variety
of models for different tasks in the workflow. Not every task requires the smartest model—a simple retrieval or intent classification task may be handled by a smaller, faster model, while harder tasks like deciding whether to approve a refund may benefit from a more capable model. An approach that works well is to build your agent prototype with the most capable model for every task to establish a performance baseline. From there, try swapping in smaller models to see
if they still achieve acceptable results. This way, you don’t prematurely limit the agent’s abilities, and you can diagnose where smaller models succeed or fail. In summary, the principles for choosing a model are simple: 01 Set up evals to establish a performance baseline 02 Focus on meeting your accuracy target with the best models available 03 Optimize for cost and latency by replacing larger models with smaller ones
where possible You can find a comprehensive guide to selecting OpenAI models here. 8 A practical guide to building agents
Page
9
Defining tools Tools extend your agent’s capabilities by using APIs from underlying applications or systems. For legacy systems without APIs, agents can rely on computer-use models to interact directly with those applications and systems through web and application UIs—just as a human would. Each tool should have a standardized definition, enabling flexible, many-to-many relationships between tools and agents. Well-documented, thoroughly tested, and reusable tools improve discoverability, simplify version management, and prevent redundant definitions. Broadly speaking, agents need three types of tools: Type Description Examples Data Enable agents to retrieve context and information necessary for executing the workflow. Query transaction databases or systems like CRMs, read PDF documents, or search the web. Action Enable agents to interact with systems to take actions such as adding new information to databases, updating records, or sending messages. Send emails and texts, update a CRM record, hand-off a customer service ticket to a human. Orchestration Agents themselves can serve as tools for other agents—see the Manager Pattern in the Orchestration section. Refund agent, Research agent, Writing agent. 9 A practical guide to building agents
Page
10
For example, here’s how you would equip the agent defined above with a series of tools when using the Agents SDK: Python 1 2 3 4 5 6 7 8 8 10 11 12 from import def agents Agent, WebSearchTool, function_tool @function_tool save_results(output): db.insert({ : output, : datetime.time()}) return "File saved" search_agent = Agent( name= , instructions= tools=[WebSearchTool(),save_results], ) "output" "timestamp" "Search agent" "Help the user search the internet and save results if asked.", As the number of required tools increases, consider splitting tasks across multiple agents
(see Orchestration). 10 A practical guide to building agents
Page
11
Configuring instructions High-quality instructions are essential for any LLM-powered app, but especially critical for agents. Clear instructions reduce ambiguity and improve agent decision-making, resulting in smoother workflow execution and fewer errors. Best practices for agent instructions Use existing documents When creating routines, use existing operating procedures, support scripts, or policy documents to create LLM-friendly routines. In customer service for example, routines can roughly map to individual articles in your knowledge base. Prompt agents to break
down tasks Providing smaller, clearer steps from dense resources
helps minimize ambiguity and helps the model better
follow instructions. Define clear actions Make sure every step in your routine corresponds to a specific action or output. For example, a step might instruct the agent to ask the user for their order number or to call an API to retrieve account details. Being explicit about the action (and even the wording of a user-facing message) leaves less room
for errors in interpretation. Capture edge cases Real-world interactions often create decision points such as how to proceed when a user provides incomplete information
or asks an unexpected question. A robust routine anticipates common variations and includes instructions on how to handle them with conditional steps or branches such as an alternative step if a required piece of info is missing. 11 A practical guide to building agents
Page
12
You can use advanced models, like o1 or o3-mini, to automatically generate instructions from existing documents. Here’s a sample prompt illustrating this approach: Unset 1 “You are an expert in writing instructions for an LLM agent. Convert the following help center document into a clear set of instructions, written in a numbered list. The document will be a policy followed by an LLM. Ensure that there is no ambiguity, and that the instructions are written as directions for an agent. The help center document to convert is the following {{help_center_doc}}” 12 A practical guide to building agents
Page
13
Orchestration With the foundational components in place, you can consider orchestration patterns to enable
your agent to execute workflows effectively. While it’s tempting to immediately build a fully autonomous agent with complex architecture, customers typically achieve greater success with an incremental approach. In general, orchestration patterns fall into two categories: 01 Single-agent systems, where a single model equipped with appropriate tools and instructions executes workflows in a loop 02 Multi-agent systems, where workflow execution is distributed across multiple coordinated agents Let’s explore each pattern in detail. 13 A practical guide to building agents
Page
14
Single-agent systems A single agent can handle many tasks by incrementally adding tools, keeping complexity manageable and simplifying evaluation and maintenance. Each new tool expands its capabilities without prematurely forcing you to orchestrate multiple agents. Tools Guardrails Hooks Instructions AgentInput Output Every orchestration approach needs the concept of a ‘run’, typically implemented as a loop that lets agents operate until an exit condition is reached. Common exit conditions include tool calls,
a certain structured output, errors, or reaching a maximum number of turns. 14 A practical guide to building agents
Page
15
For example, in the Agents SDK, agents are started using the method, which loops over the LLM until either: Runner.run() 01 A final-output tool is invoked, defined by a specific output type 02 The model returns a response without any tool calls (e.g., a direct user message) Example usage: Python 1 Agents.run(agent, [UserMessage( )])"What's the capital of the USA?" This concept of a while loop is central to the functioning of an agent. In multi-agent systems, as you’ll see next, you can have a sequence of tool calls and handoffs between agents but allow the model to run multiple steps until an exit condition is met. An effective strategy for managing complexity without switching to a multi-agent framework is to use prompt templates. Rather than maintaining numerous individual prompts for distinct use cases, use a single flexible base prompt that accepts policy variables. This template approach adapts easily to various contexts, significantly simplifying maintenance and evaluation. As new use cases arise, you can update variables rather than rewriting entire workflows. Unset 1 """ You are a call center agent. You are interacting with {{user_first_name}} who has been a member for {{user_tenure}}. The user's most common complains are about {{user_complaint_categories}}. Greet the user, thank them for being a loyal customer, and answer any questions the user may have! 15 A practical guide to building agents
Page
16
When to consider creating multiple agents Our general recommendation is to maximize a single agent’s capabilities first. More agents can provide intuitive separation of concepts, but can introduce additional complexity and overhead,
so often a single agent with tools is sufficient. For many complex workflows, splitting up prompts and tools across multiple agents allows for improved performance and scalability. When your agents fail to follow complicated instructions
or consistently select incorrect tools, you may need to further divide your system and introduce more distinct agents. Practical guidelines for splitting agents include: Complex logic When prompts contain many conditional statements
(multiple if-then-else branches), and prompt templates get difficult to scale, consider dividing each logical segment across separate agents. Tool overload The issue isn’t solely the number of tools, but their similarity
or overlap. Some implementations successfully manage
more than 15 well-defined, distinct tools while others struggle with fewer than 10 overlapping tools. Use multiple agents
if improving tool clarity by providing descriptive names,
clear parameters, and detailed descriptions doesn’t
improve performance. 16 A practical guide to building agents
Page
17
Multi-agent systems While multi-agent systems can be designed in numerous ways for specific workflows and requirements, our experience with customers highlights two broadly applicable categories: Manager (agents as tools) A central “manager” agent coordinates multiple specialized agents via tool calls, each handling a specific task or domain. Decentralized (agents handing off to agents) Multiple agents operate as peers, handing off tasks to one another based on their specializations. Multi-agent systems can be modeled as graphs, with agents represented as nodes. In the manager pattern, edges represent tool calls whereas in the decentralized pattern, edges represent handoffs that transfer execution between agents. Regardless of the orchestration pattern, the same principles apply: keep components flexible, composable, and driven by clear, well-structured prompts. 17 A practical guide to building agents
Page
18
Manager pattern The manager pattern empowers a central LLM—the “manager”—to orchestrate a network of specialized agents seamlessly through tool calls. Instead of losing context or control, the manager intelligently delegates tasks to the right agent at the right time, effortlessly synthesizing the results into a cohesive interaction. This ensures a smooth, unified user experience, with specialized capabilities always available on-demand. This pattern is ideal for workflows where you only want one agent to control workflow execution and have access to the user. Translate ‘hello’ to Spanish, French and Italian for me! Manager Task Spanish agent Task French agent Task Italian agent 18 A practical guide to building agents
Page
19
For example, here’s how you could implement this pattern in the Agents SDK: Python 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 from import "manager_agent" "You are a translation agent. You use the tools given to you to translate." "translate_to_spanish" "Translate the user's message to Spanish" "translate_to_french" "Translate the user's message to French" "translate_to_italian" "Translate the user's message to Italian" agents Agent, Runner manager_agent = Agent( name= , instructions=( "If asked for multiple translations, you call the relevant tools." tools=[ spanish_agent.as_tool( tool_name= , tool_description= , french_agent.as_tool( tool_name= , tool_description= , italian_agent.as_tool( tool_name= , tool_description= , 19 A practical guide to building agents
Page
20
24 25 26 27 28 29 30 32 32 33 ) main(): msg = input( ) orchestrator_output = await Runner.run( manager_agent,msg) message orchestrator_output.new_messages: (f" - {message.content}") async def for in print "Translate 'hello' to Spanish, French and Italian for me!" Translation step: Declarative vs non-declarative graphs
Some frameworks are declarative, requiring developers to explicitly define every branch, loop, and conditional in the workflow upfront through graphs consisting of nodes (agents) and edges (deterministic or dynamic handoffs). While beneficial for visual clarity, this approach can quickly become cumbersome and challenging as workflows grow more dynamic and complex, often necessitating the learning of specialized domain-specific languages. In contrast, the Agents SDK adopts a more flexible, code-first approach. Developers can
directly express workflow logic using familiar programming constructs without needing to
pre-define the entire graph upfront, enabling more dynamic and adaptable agent orchestration. 20 A practical guide to building agents
The above is a preview of the first 20 pages. Register to read the complete e-book.
AI Reading Assistant
Whole-book reading guide from stratified index samples; jump to passages in the text
AI guide
【One-Line Pitch】
A concise, vendor-flavored field manual for product and engineering teams who want to move from LLM demos to dependable agents—covering when an agent is actually warranted, how to structure its model/tools/instructions, and how to orchestrate and guard it safely.
【Book Arc】
- **Opening (~0%–13%)**: Defines what counts as an agent versus ordinary LLM features, then gives a use-case filter—favor workflows with nuanced judgment, unwieldy rulesets, or heavy unstructured-language input, and fall back to deterministic automation otherwise.
- **Early (~13%–33%)**: Lays out the three building blocks—model, tools, instructions—with practical guidance on model selection (baseline with the strongest model, then downshift for cost/latency), tool taxonomy (data, action, orchestration), and writing unambiguous, edge-case-aware instructions.
- **Middle (~33%–60%)**: Introduces orchestration, starting with the single-agent run loop and prompt templates, then explains when splitting into multiple agents pays off (complex branching logic, overlapping tools) and contrasts manager-style versus decentralized handoff designs.
- **Late (~60%–67%)**: Walks through the decentralized pattern in code—triage agents handing off to specialists—and contrasts declarative graph frameworks with a flexible code-first approach.
- **Ending (~67%–100%)**: Moves into guardrails and closing guidance on running agents safely, predictably, and effectively; the excerpts thin out here, so the guardrail specifics are only partially visible.
【Key Takeaways】
- **An agent is defined by control, not by using an LLM** (Opening): it must manage workflow execution, decide when the task is done, self-correct, and hand control back on failure—simple chatbots and classifiers don't qualify.
- **Earn the agent** (Opening): if a rules engine or deterministic pipeline can do the job, use it; agents are for ambiguity, brittle rule sprawl, and natural-language-heavy work like claims or refund decisions.
- **Start with the strongest model, then optimize down** (Early): establish an eval baseline with the best model available, hit your accuracy target, then swap in smaller models where results hold—avoid premature capability limits.
- **Tools are the agent's hands, and clarity beats quantity** (Early): standardize, document, and reuse tools across data, action, and orchestration categories; tool overlap, not raw count, is what usually breaks performance.
- **Instructions are engineered artifacts** (Early): derive routines from existing policy docs, break dense material into explicit steps with defined actions, and encode edge cases as branches rather than hoping the model improvises.
- **Maximize one agent before splitting** (Middle): a single agent with tools and a run loop is often enough; split only when prompts become branch-heavy or tool selection keeps failing despite better naming and descriptions.
- **Choose manager vs. decentralized by who should own the conversation** (Middle–Late): manager-as-tools keeps one agent in control and synthesizes results; handoffs suit triage and letting specialists fully take over.
- **Guardrails are part of the design, not an afterthought** (Ending): the guide positions safety and predictability as a first-class layer around model, tools, and instructions—though the excerpts only sketch this section.
【Reading Tips】
- Read the opening two sections closely even if you're eager to code—the "should you build an agent" filter will save you the most wasted effort.
- Treat the code samples as illustrations of structure (agent definitions, run loops, handoffs), not as a tutorial; the concepts transfer to any framework or a from-scratch build.
- Skim the orchestration patterns on a first pass, then return to the manager/decentralized comparison once you know whether your workflow needs central synthesis or specialist takeover.
- Deep-read the instructions and tools sections—they contain the most immediately actionable checklists for reducing agent errors.
- Don't skip the guardrails chapter; it's the least excerpted here and likely the most consequential for production readiness.
【Coverage Limits】
This guide is based on stratified excerpts covering roughly the first two-thirds of the book in detail; the guardrails and conclusion sections are only partially represented, so their specific recommendations are not summarized here.
Passage locations
Page 4
anage workflow execution and make decisions. It recognizes when a workflow is complete and can proactively correct its actions if needed. In case
of failur...
View in text
Excerpt 2
6 7 search_agent = Agent( 8 name="Search agent", 8 instructions="Help the user search the internet and save results if 10 asked.", 11 tools=[WebS...
View in text
Excerpt 3
nts are started using the Runner.run() method, which loops over the LLM until either: 01 A final-output tool is invoked, defined by a specific output type 02...
View in text
Page 20
{message.content}") Declarative vs non-declarative graphs
Some frameworks are declarative, requiring developers to explicitly define every branch, loop, an...
View in text
Recommended for You
{{#thumbnailUrl}}
{{/thumbnailUrl}}
{{^thumbnailUrl}}
{{/thumbnailUrl}}
Loading recommended books...
Failed to load, please try again later
Tip the Site
Scan the WeChat Pay or Alipay code to tip. No login required.
WeChat Pay
Alipay