构建AI智能体的模式

PATTERNS FOR BUILDINGAI AGENTS SAM BHAGWAT MICHELLE GIENOW Copyright © 2025 by Sam Bhagwat & Michelle Gienow All rights reserved. No part of this book may be reproduced in any form or by any electronic ormechanical means, including information storage and retrieval systems,without written permission from the author, except for the use of briefquotations in a book review. Formatted with Vellum CONTENTS Introductionv PART ICONFIGURE YOUR AGENTS From wishlist to working agent31.Whiteboard Agent Capabilities52.Evolve Your Agent Architecture83.Dynamic Agents124.Human-in-the-Loop14 PART IIENGINEER AGENT CONTEXT Intro to context engineering19Parallelize Carefully 5.216.Share Context Between Subagents247.Avoid Context Failure Modes268.Compress Context299.Feed Errors Into Context33 11.List Critical Business Metrics41 12.Cross-Reference Failure Modes and SuccessMetrics43 16.Create Datasets from Production Data54 17.Evaluate Production Data57 PART IVSECURE YOUR AGENTSAutonomy is a two-edged sword6318.Prevent the Lethal Trifecta6519.Sandbox Code Execution6820.Granular Agent Access Control7021.Agent Guardrails72PART VTHE FUTURE OF AGENTS22.What’s Next(ish)77Notes79Also by Sam Bhagwat85 INTRODUCTION Here at Mastra, the open source Typescript framework forbuilding AI agents, we’ve had a front-row seat to how peopleare building agents. Back in February 2025 (practically ancient times, in AIworld), we published the popular guidePrinciples of BuildingAI Agents. In May, we updated the guide to include MCP, agenticRAG, and a few other emerging principles. But our work was far from finished. 2025 is the year of agents and, over the summer, we began tosee a set of stories and guides emerging from prominent AIcompanies, model labs, and early-stage AI startups. The people pushing agents into production werepublicly describing their successes (and failures). Principleswas textbook-style knowledge. This wasmessier and rough, expressed inah-ha!moments, lessonslearned, and retrospectives — knowledge that sprawled across social media posts, Substacks, eng blogs, and Gitrepos. Collecting and wrangling these lessons for our userseventually led to this book:Patterns for Building AI Agents—now Volume 2 of an eventual trilogy. Principles are conceptual, patterns are pragmatic. WhilePrinciples of Building AI Agentscovered what to build,Patternscovers how to build. Principleswill get you through the first few weeks ofbuilding, butPatternsshould be on your desk until itscontents are imprinted in your mind. We start off by sharing patterns for agent design andarchitecture, then dive into the art and science of contextengineering. Next, we dig into the discipline of evals, thestandard way for iterating on and refining agent quality. Finally, we talk about agent security, a field evolving inresponse to novel attack patterns. Agents are in the hands ofearly adopters — and attackers are enthusiastic earlyadopters! Thanks for coming along as we all learn together. Thisbook is a work in progress and a living document. Perhaps as you build, you’ll discover a new pattern thatmakes it into our next edition! PART I CONFIGURE YOURAGENTS Building AI agents often starts with a whiteboard full ofpossibilities: dozens of processes to automate and tasks tooffload amid grand visions of “AI can solve everything!”efficiency. How do you go from wishlist to working agent? Teams struggle not because an agent can’t handle their usecases, but because they didn’t break down the problem in away that maps to buildable systems. The agent design patterns in Part I address the funda-mental configuration challenges that determine whetheryour agent will succeed or stall: Organizing dozens of capabilities into a coherentagent architecture.Building everything at once vs. discovering yoursystem iteratively.Facing the reality that different users needdifferent agent behaviors.Letting agents run autonomously vs. with humancheckpoints. These patterns may seem simple, but if you follow themyou can build agents that are not just powerful but also reli-able, maintainable, and trusted by their users. WHITEBOARD AGENT CAPABILITIES We’re in the decade of agents. There’s a hugenumber of valuable processes, currentlyperformed by humans, that could be performedwith some amount of AI assistance and automation. Deciding where to start, and how to build, is where therubber meets the road. Problem: Agent feature overload There are two ways of specing out an agent: outside-in andinside-out.1The outside-in view is the grand view thatgenerates enthusiasm: seeing dozens or hundreds of busi-ness problems and processes that you could potentiallybuild or automate. The inside-out one, though, is the one that gets the jobdone. Often, it arrives by way of the exec team putting amassive wish list in front of an engineer who’s like,Yo, holdyour horses. Solution: Organizational design, for your agents Imagine you were hiring a human team. What are the tasks