Hi, I’m Sam, the cofounder/CEO of Mastra, the Typescript agent framework. I wrote a book on building agents and wanted to share it with HN.

The book is called Principles of Building AI Agents. Right now it has 34 chapters and 148 pages covering LLMs, prompting, agents, workflows, RAG, evals, multi-agent, tracing, deployment, MCP, tool use, and a few other topics.

The backstory here is that last October when we started working on Mastra we knew very little about AI engineering, and had to learn as we were building.

In January, we started going to local AI meetups. We met a lot of people who were where we’d been. Somehow, we turned from students to teachers. Whenever an explanation seemed to stick we’d go home and put it in our docs or blog.

One day my cofounder Shane turned to me and was like, what if you wrote a book on this stuff?

I was initially skeptical, but I tried writing an outline and it was pretty natural. So I spent the next couple weekends trying to hammer our posts into book form, and fill in the gaps. Surprisingly it worked. The initial version was 92 pages, in 27 very short chapters.

We were going to call it Principles of AI Engineering but a founder author friend convinced me to use the word Agents instead, so Principles of Building AI Agents it was.

The first reaction we got was surprise. We handed it out at the same meetups we’d gone to earlier.

We started seeing people post book reviews on social media. A couple founder friends told us the book changed their agent architecture or their interface design. An engineer turned videographer came to our office and shot a mini-documentary.

People asked us a lot how we’d keep the book up to date. We didn’t really know. Then MCP and Studio Ghibli happened, and we knew we needed to update it.

I sat down in May to write for another weekend. I ended up with another 50 pages. In addition to MCP and image gen, there was a lot of stuff to write about web browsing, workflow streaming, code gen, agentic RAG. We republished the book as the 2nd edition.

The single thing that people comment on the most is a page where I give a partial excerpt from the leaked Bolt.new system prompt. It’s the first time many people have read a production-grade prompt.

The book has become pretty popular recently. We've given out thousands of copies at AI meetups and conferences, and it's even gone viral on LinkedIn (of all places).

In terms of actual mechanics, I wrote the book in Notion, then pasted it into a desktop app called Vellum, which spits out ePubs and PDFs. Amazon’s KDP lets you upload those and publish your book (they’ll print it for you). Having a nice CI/CD helped, as did having docs and blog posts as sort of intermediate artifacts in a content pipeline. It meant that when I was writing I could pull from a warm cache. The process felt O(n) rather than O(n log n).

Enjoy reading, and please let me know what you think! (You probably just want to download the book and read it in your favorite reader, rather than use Github's PDF reader)

I’ll be starting on a third edition soon, and I want to know what topics feel like they’re missing, if anything feels outdated, and so on.