BabyAgent: A Go Tutorial Repo That Builds an Agent Framework Chapter by Chapter

The gap BabyAgent targets: Go engineers who have never called an LLM

Most agent material assumes Python and some familiarity with model APIs. BabyAgent inverts that. The README states the project is written for engineers who have backend experience and basic Golang but no LLM background, and that it skips mathematical derivation in favour of engineering implementation: why each step is designed that way, what the alternatives are, and which problems show up in real systems. The stated scope is Agent, Tool Calling, Agent Loop, MCP, Memory and RAG, taught through runnable code rather than a framework you import. That framing matters because it changes what counts as a defect. A missing retry policy is a gap in a library and a deliberate omission in a tutorial. The README is explicit about which one this is: it calls the repository a teaching repository, says it is not an out-of-the-box production framework, and says it is not recommended as a base for secondary development in production. Treat that as the project's own boundary, not as modesty. The intended use is principle reference plus prototype validation, with the reader expected to add engineering and safety work for their own scenario.

How the twelve chapters are wired: one directory per concept, no shared runtime

The repository layout is the architecture. Each chapter is a directory, ch01 through ch10 are marked complete in the README, and ch11 and ch12 are marked as planned. There is a shared directory described as holding configuration and MCP code. The README states that each chapter can run independently, and the quick start runs them as separate programs: go run ./ch01/main with a --stream flag and a -q question, go run ./ch02/main with -q, and bare go run ./ch03/main through go run ./ch10/main. Chapter seven is the exception in presentation rather than in structure: the README says it is a standalone index and tool implementation and points to ch07/README.md for usage examples instead of giving a command in the quick start. The progression is deliberate. Chapter one covers the chat/completions request and response shape and SSE parsing for a typewriter effect, and compares raw HTTP against the OpenAI Go SDK. Chapter two introduces function calling declarations, parsing tool calls, and the loop of call, feed back, reason again, along with local tools for reading, writing, editing files and running shell commands. Later chapters layer on reasoning_content parsing and a Bubble Tea TUI, MCP clients and servers, context strategies, two-tier memory, pgvector-backed retrieval, Docker sandboxing, and finally an HTTP service. Nothing in the material suggests a single shared agent binary that all chapters extend, so expect to read each chapter as a self-contained example rather than as a growing codebase.

Running a chapter: Go 1.24, an API key, and one env file

Setup is three steps in the README. Install Go 1.24 or higher. Obtain an API key from an LLM provider, with OpenAI, DeepSeek and GLM named as examples. Then copy the environment template and fill it in: cp .env.example .env, followed by editing .env to insert your API_KEY. The repository root contains that .env file alongside the chapter directories. Every chapter then runs from the repository root with go run and a package path. Chapter one takes flags: go run ./ch01/main --stream -q "用 Go 语言写一个 Hello World". Chapter two takes a question that exercises a tool: go run ./ch02/main -q "请读取 README.md 并总结项目目标". Chapters three through six and eight through ten have no flags in the quick start, and chapter ten is noted as listening on :8080. The material does not list configuration keys beyond API_KEY, does not name the provider-selection mechanism, and does not document a model name setting, so if you need to point a chapter at DeepSeek or GLM rather than OpenAI you will be reading the shared configuration code to find out how. That is a real friction point for a tutorial whose stated audience may not use OpenAI. The README also does not describe a test command, a Makefile, or a build step beyond go run.

Context engineering and memory: the two chapters with the most transferable design

Chapters five and six carry the ideas most likely to survive into your own system. Chapter five frames the problem as window limits, rising cost and degrading quality across turns, then names three strategies: truncation, which the README describes as safely deleting old messages while keeping recent key exchanges; offloading, which stores long messages externally and leaves a recovery hint behind; and summarization, which uses an LLM to compress history. These are exposed through a strategy interface the README calls extensible and composable, with a strategy event system that surfaces execution state in the TUI, and token counting via tiktoken-go for live context measurement. Chapter six splits memory into Global, described as cross-session, and Workspace, described as project-level, behind a pluggable interface, with an LLM extracting and updating memory content, persistence to the filesystem, a memory event stream in the TUI, and injection of memory into the system prompt. The interesting decision is that memory updates are LLM-driven rather than rule-based, which means a bad extraction writes itself into the store and then into every subsequent system prompt. The README does not describe a review step, a confidence threshold, or a rollback path for memory entries. If you port this pattern, that is the part to design yourself.

MCP, RAG and sandboxing: three chapters with different maturity

Chapter four covers MCP as three roles, Client, Server and Tool, and states the motivation as the combinatorial explosion of models times tools. It mentions JSON-RPC 2.0, initialization, tool discovery and tool invocation as optional deeper reading, and describes coexistence between local tools and MCP tools plus namespacing to avoid tool collisions. Namespacing is the concrete takeaway: once you attach more than one server, tool names stop being unique, and the README treats that as a design problem rather than a naming convention. Chapter seven is Agentic RAG, where the agent decides when to retrieve, what to retrieve and how much. The mechanism listed is embedding code fragments, storing vectors in pgvector with incremental updates and deduplication, chunking via LineChunker or ParagraphChunker, semantic recall by vector similarity, reranking with a rerank model, and a Semantic Search Tool. That is a heavier dependency than any other chapter, since it requires a Postgres instance with pgvector plus embedding and rerank model access, and the README gives no setup instructions for the database. Chapter eight is the safety chapter: bash commands run in a Docker container, with Docker auto-detected and graceful degradation when it is absent, human confirmation before dangerous commands with Allow, Reject and Always Allow states, and ESC to cancel the agent loop through context cancellation. Graceful degradation is worth reading literally. When Docker is missing, the isolation is gone, and the README does not say what replaces it.

The tree-shaped history in chapter ten, and what it implies for storage

Chapter ten detaches the agent from the terminal. The README describes the agent emitting a StreamEvent channel without any awareness of HTTP, with the HTTP layer converting those events into SSE for the browser. Persistence uses SQLite for Conversation and ChatMessage rows, where a Rounds field serializes the complete LLM messages, and each message carries a parent_message_id so that a buildHistory function walks the ancestor chain to reconstruct the LLM context. That parent-link design is the part worth studying. It means editing or branching a conversation is a matter of writing new rows with a different parent rather than mutating history in place, and it means context reconstruction is a traversal, not a table scan. The cost is that every request pays for that traversal, and the README does not describe indexing on parent_message_id or a depth limit. For a teaching example the trade-off is fine; the material gives no indication it has been evaluated under load. The chapter also confirms the earlier claim that the agent core does not know about transport, which is the cleanest separation in the whole repository.

What is missing, and when a framework is the better answer

Chapters eleven and twelve are marked as planned in both the chapter list and the project structure, and the README says they are being updated continuously. Eleven would cover Trace and Span modelling, agent-specific metrics such as first token time, tokens per minute and token usage, span attributes, and an OpenTelemetry, Jaeger or Tempo, Prometheus and Grafana stack. Twelve would cover a mock LLM interface, evaluation datasets, automated metrics and quantified prompt comparison. Until those land, the repository has no built-in way to measure whether a change to a prompt or a context strategy helped, which is a notable gap for a project whose fifth chapter is about managing context under cost pressure. The README does not state a release history, and the repository has no releases. If your goal is to ship an agent this quarter, a framework such as LangChain, LlamaIndex or one of the Go agent libraries gives you maintained tool abstractions, provider adapters and tracing out of the box, at the cost of learning someone else's control flow. BabyAgent makes the opposite trade: you write the loop, the tool registry and the context strategies yourself, so nothing is hidden, and nothing is maintained for you either. The README's own guidance points the same way, describing the repository as a starting point for principle reference and prototype validation rather than a production base.

Licence and upkeep: Apache-2.0, no releases, active pushes

The project is licensed under Apache License 2.0, per the README's licence section and the repository metadata. That is a permissive licence with an explicit patent grant, and it permits commercial use and modification, but this is a description of the licence text, not legal advice; if you plan to redistribute modified chapter code, read the LICENSE file and the NOTICE requirements yourself. Upkeep is the harder question. There are no releases, so there is no versioned artefact to pin and no changelog to diff against. The repository is not archived and the last push timestamp is recent, and the README says chapters eleven and twelve are being updated, which suggests ongoing work. What that means in practice is that you should track a commit hash rather than a tag if you build anything on top of it, and expect chapter contents to move. The dependency surface is also worth noting before you start: Go 1.24 or newer, an LLM API key, Bubble Tea for the TUI chapters, tiktoken-go for token counting, pgvector plus a database for chapter seven, and Docker for chapter eight. Each of those is a prerequisite the README names, and none of them comes with a version pin in the material supplied.

Editorial conclusion

Adopt BabyAgent if you are a Go backend engineer who wants to read runnable code for Agent Loop, MCP tool namespacing, context truncation and offloading, and the parent_message_id history rebuild, and you accept that chapters 11 and 12 are still marked as planned. Do not adopt it as a production framework or as a base for a second development effort; the README states that directly. Before committing time, check whether the chapter you actually need is finished, and confirm your Go toolchain is 1.24 or newer, since the repository targets that version and gives no compatibility statement for older ones.

Official sources

1. baby-llm/baby-agent on GitHub
2. Issues
3. License: Apache-2.0
4. README