Build an agent from scratch in Go
Understand how an agent works through each interaction, then verify it with code and experiments.
Mino is a project to build an agent from scratch in Go. This book follows it as each chapter adds one capability. Starting with a terminal conversation, you trace what the model receives and what the program handles, then check the result and its limits for yourself.
Ready to read: Chapter 01: A terminal conversation · Chapter 02: JSONL conversation history · Chapter 03: The Agent loop and Bash · Chapter 04: Recovering tool turns · Chapter 05: Multiple sessions · Chapter 06: Context compaction · Chapter 07: Skills · Chapter 08: File tools · Chapter 09: MCP tools · Chapter 10: Guardrails · Chapter 11: Evals · Chapter 12: Sandbox · Chapter 13: User memory · Chapter 14: Subagents · Chapter 15: Custom subagents. Chapters 01–15 are released; the latest is available in chapter-15 (version 0.15.0). The chapter roadmap records every chapter's status.
About the author
qqling | AI Builder is a senior developer with time at large companies and startups, and a long-time AI practitioner focused on putting large models and agents to work. I want to build an agent of my own from scratch, and Mino is where that begins. For each new capability, the book explains the problem it solves, how it works, and how to verify the result, so readers new to agents can follow along one step at a time.
Who this book is for
This book is for readers new to agents who want to understand them by building. Reading the source requires Go variables, functions, and basic error handling; you can start with Chapter 01 even if model APIs are new to you. HTTP requests, context, and tool calls are introduced when the program needs them.
The exercises target macOS. Running a downloaded Mino release requires no Go installation; building or running Mino from source requires Go. See setup and installation for the steps.
What each chapter gives you
- Observe an interaction. Start with a concrete action, such as entering a question and seeing an answer, to establish the problem the chapter addresses.
- Separate the model's role from the program's. Use diagrams and versioned source links to trace how input, context, and responses move.
- Verify with an experiment. Inspect requests or run mock tests to establish where a capability comes from and when it can fail.
For example, Chapter 01 inspects requests to explain why two questions in the same terminal have no shared memory. Chapter 02 then verifies how saved history becomes part of the next request. A model's correct guess cannot replace a check of the program's behavior.
What is ready to read
Chapters 01–10 were released on 2026-10-21 as chapter-01 through chapter-10, with application versions 0.1.0 through 0.10.0; chapter-10 was republished on 2026-10-26, Chapters 11 and 12 followed on 2026-10-26 as chapter-11 (version 0.11.0) and chapter-12 (version 0.12.0), Chapter 13 on 2026-10-27 as chapter-13 (version 0.13.0), Chapter 14 on 2026-10-28 as chapter-14 (version 0.14.0), and Chapter 15 on 2026-10-29 as chapter-15 (version 0.15.0). Chapter 10 consolidates the earlier controls into one guardrail decision with permission modes you choose; Chapter 11 measures the Agent with declared eval cases; Chapter 12 runs each approved Bash command inside an operating-system sandbox on macOS; Chapter 13 carries what you tell Mino into later sessions as data; Chapter 14 hands a large exploration to subagents that work in their own context; Chapter 15 gives those subagents project roles with narrower tools. Each released lesson identifies the source tag for its experiments.
| Stage | The question you will explore |
|---|---|
| 01 A terminal conversation | How does a line of input become an HTTP request and then an answer? |
| 02 JSONL conversation history | What survives a restart, and which saved records become model context? |
| 03 The Agent loop and Bash | Who approves and executes a command, and how does its result return to the model? |
| 04 Recovering tool turns | When a command may have run but its result was lost, how does the model find out? |
| 05 Multiple sessions | How do you select one conversation's context, keep another, and safely clear the current one? |
| 06 Context compaction | How do manual and automatic compaction share a budget and preserve useful context? |
| 07 Skills | How does a fixed catalog guide the model to request task knowledge with skill_view? |
| 08 File tools | How can the program confine the model's project-file reads and bind each approved write to the file you saw? |
| 09 MCP tools | How do tools hosted by remote services or local processes join the loop, and what does each approval decide? |
| 10 Guardrails | How are actual permissions enforced as one policy in code? |
| 11 Evals | How do you check repeatably whether a change to the SOUL, a tool description, or the loop changed what the Agent does? |
| 12 Sandbox | How can the kernel, rather than your reading of a command, bound what an approved Bash command may touch? |
| 13 User memory | How does a fact you told Mino in one session reach the next one, as data rather than an instruction? |
| 14 Subagents | How does a large exploration stay out of the main conversation's context, and who approves what a subagent does? |
| 15 Custom subagents | How does a project give subagents reusable roles and narrower tools without giving them more authority? |
Read alongside the code
Each released chapter identifies its applicable version and uses its matching chapter-NN source tag. The newest chapter in this version of the book, Chapter 15, follows chapter-15; the source setup explains how to run the same snapshot locally.
Release tags follow chapter-NN; the application version is 0.<chapter>.<patch>. A patch such as chapter-05.1 produces version 0.5.1 and updates the relevant lesson without creating an extra chapter.
Users of earlier 0.1.0 or 0.2.0 builds should follow the update instructions.
Start with setup and installation, or go directly to Chapter 01.