Preface

Your PoC works on your laptop. The classifier hits the label most of the time, the model returns the structured output you asked for, the stakeholders nodded at the demo. The PoC has a deployment URL now. Your manager calls it production.

It is not production.

Production is what happens after the demo. Production is the morning you change the system prompt and quality drops 8% on traffic you cannot see. Production is the agent that worked yesterday and refuses to escalate today, and you cannot tell which is the bug. Production is the model that quietly cost $4,300 last month because nobody put a budget on it. Production is the on-call engineer at 11:42pm trying to roll back a prompt change with no rollback plan, no version history, and no idea which deploy made the agent confidently wrong.

None of these are AI problems. They are engineering problems. You already know how to solve them, for APIs. Your team versions API responses. Your team writes contract tests. Your team has SLOs, canaries, rollback procedures, a postmortem template, and someone whose job it is to own the alert at 3am. That discipline is what is missing from how teams ship LLMs today, and the gap is not because agents are exotic. The gap is because teams forget, the moment a model is involved, that everything they already know about shipping software still applies.

This book closes that gap. Agents are software. The engineering discipline you already have for APIs is the discipline you need for agents - translated, not replaced. Pydantic AI is the framework where that translation is natural, because typed outputs and dependency injection are the seams that let you test, version, and roll back the parts of the system that other frameworks leave loose.

This book is for Sam. Sam is a senior engineer - Python fluent, comfortable with Docker, on the Slack channel where the on-call alerts arrive - who has shipped a couple of LLM proof-of-concepts. They know what an embedding is, what a percentile is, what an SLO is. They have called the OpenAI or Anthropic SDK enough times to have an opinion about both. They have just been told, by a tech lead or by their own product instinct, that the next agent has to be real. Real customers, real traffic, real on-call rotation. Sam is one bad incident away from a difficult conversation, and the question they need answered is not “how do I build an agent” but “how do I build one I would trust to leave running while I sleep.”

If that is you, the book is for you.

The project that runs through every chapter is an open-source maintainer assistant: a Pydantic AI agent that triages incoming issues on a GitHub repository. Issue data comes from **triage-lab**, a companion repository of curated fixtures (50 closed issues, golden datasets for eval and retrieval). Chapter 2 classifies those fixtures on your laptop. Chapter 3 ships the agent to your fork of triage-lab via a CLI cron job - posting comments on real issues, minimally, and on purpose. The classification is rough. Every new issue gets the same public comment whether confidence is 0.51 or 0.97 - no escalation, no draft reply, no tools. It will mislabel duplicates and gray-zone cases, that is the point. Every subsequent chapter fixes one specific issue with a test, a metric, and a rollback plan attached.

Chapter 1 is the argument. Chapter 2 is the smallest possible Pydantic AI agent, running on your laptop against closed issues from triage-lab. Chapter 3 ships that agent to your fork via a CLI cron job - minimally, and on purpose.

From chapter 4 forward, every chapter fixes one specific way the v0 agent is wrong. Tools and dependency injection. Retrieval that does not lie. The versioned output contract. Unit tests for the deterministic seams. The eval suite - the chapter you probably bought the book for. Observability. Cost engineering. Human-in-the-loop and the kill switch. Canary rollout and quality SLOs. And the runbook that turns the agent from deployed into operated.

This book is not for everyone. It is not for first-time LLM users; if you have never sent a structured-output request and parsed the response, the first 50 pages of the Pydantic AI documentation will serve you better than this book will. It is not for readers looking for prompt-engineering tricks. The book treats prompts as deployable artifacts with rollback plans, not as the place where the magic happens. It is not for fiction writers, founders evaluating AI as a category, or managers shopping for an AI strategy. It is for the engineer who has the agent in a notebook and has been told it needs to be in production by the end of the quarter. If that is the conversation you are having this week, turn the page.