Principles and Patterns of Building AI Agents: An Honest Review of Mastra's Free Two-Book Series

Most books about AI agents land in one of two piles: 500-page reference tomes you never finish, or blog posts stretched into an ebook. Sam Bhagwat's two Mastra books are neither. Principles of Building AI Agents and its companion Patterns for Building AI Agents, both free downloads from mastra.ai/book, are short enough to read in a weekend and dense enough to keep on your desk. Together they trace the full arc from your first working agent to one that survives real users, and this review covers both.

To be upfront about what this review is: I read both cover to cover as an engineer trying to keep a mental model current, not as someone who shipped a Mastra app to production. So I am reviewing the ideas and the teaching, not the framework's runtime. That distinction matters, and I will come back to it.

The short version: this is one series in two volumes, and reading them as a pair is the point. Principles tells you what to build. Patterns tells you how to keep it alive once real users touch it.

01What are Principles and Patterns of Building AI Agents?

Principles of Building AI Agents is a short, conceptual guide to modern agents, now in its 3rd edition (March 2026). It runs about 134 pages across 33 chapters and ten parts: prompting an LLM, building an agent, tools and MCP, graph-based workflows, RAG, multi-agent systems, observability and evals, development and deployment, coding agents, and a grab-bag "everything else" on multimodal. It is deliberately pocket-sized.

Patterns for Building AI Agents is Volume 2 (October 2025), co-written with Michelle Gienow. It is roughly 92 pages of 22 numbered patterns grouped into four working parts: configure your agents, engineer agent context, evaluate agent responses, and secure your agents. Where Principles is textbook, Patterns is a collection of lessons learned from teams pushing agents into production.

Both are written by Sam Bhagwat, CEO of Mastra, the open-source TypeScript agent framework, and previously a co-founder of the Gatsby React framework. Both are free.

02The thesis: what to build, then how to build

Bhagwat states the relationship between the two books plainly, and it is the most useful framing in either one:

That is not marketing filler. It is an accurate description of how the two books actually feel to read. Principles gets you fluent. Patterns is where the scar tissue lives.

03Principles: a primer that respects your time

The best decision in Principles is its length. Bhagwat says in the foreword that it "should fit in your back pocket," and that you should be able to get something working in a day or two. He keeps that promise. There is no throat-clearing.

A few things it does genuinely well:

It anchors on a clean definition. It borrows Simon Willison's line that an agent "calls tools in a loop to achieve a goal," then lays agency out as a spectrum, from binary choices in a decision tree, to memory and retries, up to planning, subtask decomposition, and self-correction across long horizons. That ladder is a better mental model than the usual "agents are magic" hand-waving.

It has a spine of engineering judgment. The line I kept coming back to is "make it work, make it right, make it fast/cheap, in that order." It shows up when choosing a provider, when picking model size, and when deciding whether to move workloads to cheaper open models later. It is the kind of advice that sounds obvious and that people ignore constantly.

Tool design gets the emphasis it deserves. The chapter on tool calling argues that designing your tools is the single most important step, and it should happen on paper before you write code. The illustration, investor Alana Goyal's book-recommendation agent, is a clean before-and-after: dumping every book into the context window failed, and breaking the problem into specific tools ("get books by genre," "get recommendations by investor") made the agent behave like a real analyst. Think like an analyst, then write each operation as a tool.

Memory is treated as a design choice. Principles names three memory types (working memory, semantic recall, and observational memory) and spends real pages on observational memory, where an "observer agent" compresses raw sessions into structured observations and a "reflector agent" garbage-collects when they overflow. That is a more honest picture of production memory than "just stuff it in the context window."

Where Principles is weakest is the flip side of its virtue: it is thin. Some chapters are two pages. If you already build agents, several sections will feel like a table of contents with commentary. That is a fair trade for a free primer, but it is why I score it a notch below its sequel.

04Patterns: the half worth paying for (even though it is free)

Patterns is the one I would hand to a team about to ship. It is organized as problem, then solution, then a real example, and the examples are specific enough to be useful rather than decorative. Three parts stood out.

Context engineering, treated as its own discipline

The context section is the clearest short treatment of context engineering I have read. It names five concrete failure modes rather than waving at "the model got confused":

The example that sells it: a Google Gemini team benchmarking a Pokemon-playing agent watched accuracy start degrading around 125k tokens, even with a 500k-token window. By filtering with RAG, pruning irrelevant context, and assembling a compiled context string before every call, they took a research agent from 34% to reliably over 90% accuracy. The book's blunt summary is that "context is not free," and every token influences behavior for better or worse.

Evals as engineering, not vibes

The evals part is built around a recurring, believable case study: a medical necessity-review agent for health insurers, whose north-star metric is "false approvals." The workflow it lays out is the honest version of quality work: list your failure modes and why they happen, connect engineering metrics to a business metric, cross-reference the two, then iterate against a benchmark in CI so a fix "here" does not silently break something "there."

The pattern I found most quietly important is "Have SMEs Label Data." The argument is that software engineers are not your domain experts, so they should not be the ones judging whether a medical approval was correct. Outsourcing annotation breaks the loop between seeing a failure and understanding it. That is a governance point disguised as a labeling tip.

"Benchmarks are the difference between engineering and experimentation."

Security, written for the way agents actually break

The security part opens with the right observation: traditional security assumes humans click buttons and code runs deterministically, and agents break both assumptions by interpreting instructions from anywhere and acting across systems.

Its centerpiece is Simon Willison's "lethal trifecta": access to private data, exposure to untrusted content, and the ability to communicate externally. Combine all three and a prompt-injection attack can read your secrets and exfiltrate them. The GitHub MCP server is the worked example, and it covers the whole trifecta at once. The practical advice is to remove one leg, usually the exfiltration path, via input processors. The rest of the part is equally grounded: sandbox untrusted code (with fast-start runtimes like E2B or Daytona, since a Docker cold start is too slow), grant granular just-in-time access rather than broad roles, and add real-time guardrails on both inputs and outputs.

05The patterns that stuck with me

These are the ideas I expect to actually reuse, pulled from across both books.

06Where the series falls short

No book earns a real review without the criticism, so here is mine.

Breadth beats depth, and Principles feels it most. This is the same complaint you will find on Goodreads, and it is fair. Principles skims. It is a wide, shallow tour by design, so anyone hoping to master RAG or multi-agent orchestration from it will be disappointed. It is a map, not the territory.

It is Mastra's book, and it shows. The concepts are portable, but the code and several APIs are Mastra-specific and TypeScript-first. That is reasonable for a free book from a framework company, and the plugs are examples rather than hard sells, but Python engineers should know the snippets will not copy-paste.

The stack will age faster than the ideas. Both books name specific models, token thresholds, and tools. Useful now, dated in eighteen months. The durable parts are the distinctions: single-threaded versus parallel, generation versus verification, autonomy versus guardrails.

Patterns is a field guide, not a manual. At 92 pages it is dense and original, but each pattern is a strong sketch, not an end-to-end implementation. You will still need docs and code to actually ship any one of them.

07How the two books compare

08Who should actually read it

Read Principles if you are a developer, ideally in TypeScript, who wants a fast and jargon-light on-ramp to how agents work. You can finish it in an evening and immediately hold better conversations about agents.

Read Patterns if you have a working prototype and are staring down the gap between "it demos well" and "it survives real users." That is the book's whole reason to exist, and it delivers there.

If you want a deeper, Python-first, and far more exhaustive treatment of agent architectures, the two Mastra books pair well as the lean counterpart to a heavier text. I wrote about one such book, a 542-page pattern library, in my review of 30 Agents Every AI Engineer Must Build. Read together, the contrast is instructive: one is a comprehensive reference you study, the other is a pocket guide you keep open while you work.

09Final word

Bhagwat's series wins on a rare axis: respect for the reader's time. Principles (4 / 5) gets you fluent in an evening. Patterns (4.5 / 5) is the one I would keep open while building, because it is about the part everyone skips: what happens after the demo works. That the whole thing is free, and this good, is faintly ridiculous.

Thank you to Sam Bhagwat and Michelle Gienow for writing them, and for giving them away. You can download both at mastra.ai/book, or grab print copies of Principles and Patterns on Amazon. If you read them, I would like to know which pattern you reached for first.