Start here
Three reading paths through the site, each an ordered list of guides, for learning how agents work, for shipping one at work, and for leading a team that builds them.
This site is for Go developers who want to build AI agents and understand what happens inside them. It assumes you can write and run Go code; nothing about models or machine learning is assumed, and none of the examples needs an API key.
Pick the path that matches why you’re here. Each one is a list of guides in the order they build on each other, and every guide on a path links to the step before and after it, so you can follow it without coming back to this page.
Learning how agents work
For a Go developer who has never built an agent. It starts with what an agent is and a loop you can run with no model at all, then attaches a real model, explains what the model does with each request, and ends with the agent the book finishes with and how well it did.
- What an agent isAn agent is a program where the model picks each next step and your Go code carries it out. This page follows one agent through a failing test, compares it with chatbots and workflows, and lists the parts you write.
- ch01: A scripted agent loopRun a complete agent loop that fixes a failing Go test, driven by a script of replies recorded from a real model. No API key and no network, with tests that run in milliseconds.
- The agent loopAn agent is a model inside a loop, and the loop is plain Go. This page reads the whole loop, about 30 lines, stage by stage, along with the rules that keep it correct.
- Tool calling on the wireWhat a tool call looks like as JSON on an OpenAI-compatible chat completions API, how a Go client sends tool definitions and reads calls back, and the rules that keep a conversation valid.
- How models pick the next tokenA language model gives every possible next token a probability and picks one. A toy model in Go shows why answers vary, why temperature matters, why fluent text can be false, why code costs more tokens than English, and why a tool call is text the model writes.
- Calling a model from GoUnder two hundred lines of standard-library Go make a client for an OpenAI-compatible chat completions API, with a per-call deadline that records its cause, errors checked in every place they can appear, and the finish reason passed back to the caller.
- ch04: A real agent fixes a failing testThe same 30-line loop, now driven by a real model’s recorded replies, with tools that run go test for real on your machine. Replay two models’ different paths to the same fix, and a run that recovers from three bad tool calls.
- Tokens, cost, and contextAn agent’s requests grow with every turn. This page shows that growth in recorded numbers, what a run costs, which tokens you pay for before the model reads the task, and why the size of the context window is a poor planning target.
- Why the agent stoppedA production agent loop names every way a run can end. API errors become a type that says whether to retry, sentinels form a tree checked with errors.Is, a dollar budget is checked before each call, replies are checked before they are kept, and cancellation still answers every tool call.
- Workflow or agent?Programs that call a model come in five shapes, from a fixed sequence of calls to several cooperating agents. Pick the simplest one that handles the task, go further only when the task forces you to, and mix shapes when a task has a routine part and an open-ended part.
- Designing toolsThe caller of an agent’s tools reads a name, a description, and a schema, and never your code. This page covers task-shaped tools, short results, schemas generated from Go structs, strict argument checks, useful errors, and a cheap test of tool choice.
- The finished agentThe crash-triage agent the book ends with, measured on 20 held-out tasks with three models. Pass rates with their ranges, the cost of each passing run, how the failed runs went wrong, and how to point the agent at a Go service of your own.
Shipping an agent at work
For an engineer who already knows the loop and has a deadline. It opens with the decision that shapes everything after it, a workflow or an agent, then the launch checklist and the mistakes behind it, and then one guide for each part of the checklist, in the checklist’s order.
- Workflow or agent?Programs that call a model come in five shapes, from a fixed sequence of calls to several cooperating agents. Pick the simplest one that handles the task, go further only when the task forces you to, and mix shapes when a task has a routine part and an open-ended part.
- Launch checklistTwenty-three checks for an agent that will run unattended and spend money, grouped by what can go wrong, each with the chapter that builds it and, where the book measured one, the failure that shows why it matters.
- Measured mistakesEvery failure on this page happened in a recorded run of the book’s code, and each comes with its task, its models, how many runs it rests on, the date, and the chapter. What went wrong, how often, and what the code changed because of it.
- Designing toolsThe caller of an agent’s tools reads a name, a description, and a schema, and never your code. This page covers task-shaped tools, short results, schemas generated from Go structs, strict argument checks, useful errors, and a cheap test of tool choice.
- Context managementEach turn, an agent resends everything so far, so long runs get expensive and then hard for the model to follow. This page shows five context policies in Go (prompt caching, clearing old tool results, trimming turns, compaction, and notes) and what each did on a 99-report batch.
- Why the agent stoppedA production agent loop names every way a run can end. API errors become a type that says whether to retry, sentinels form a tree checked with errors.Is, a dollar budget is checked before each call, replies are checked before they are kept, and cancellation still answers every tool call.
- Retries and observabilityWhich failures deserve a retry and which never do, full-jitter backoff measured against plain backoff, a retry budget and circuit breaker shared across agents, tool retries limited to tools that are safe to repeat, and logs and OpenTelemetry GenAI spans that show where a run’s time and money went.
- Testing an agent offlineAn agent’s tests should never call a live model. Use a scripted model for the loop’s rules, an http.RoundTripper that replays recorded API calls for the client and tools, hand-written fixtures for failures you can’t trigger, outcome checks in place of transcript checks, and testing/synctest for timeouts.
- Evals for an agentHow to tell whether an agent is good, and whether a change improved it. A tiered eval set, graders written as code with hidden tests, unscored runs kept out of the pass rate, rates reported with ranges, task-by-task comparisons, and the places a model reviewer and a model judge fit.
- Prompt injection and sandboxingAn agent that reads strangers’ text, holds keys, edits code, and sends text out is an attractive target. A one-page threat model, a ladder of sandboxes for the code the agent runs, and five layers of defense from strongest to weakest, with what 237 measured runs could and couldn’t show.
- Human approvalHow to put a person in front of an agent’s risky calls. A gate in tool middleware that the model can’t route around, raw evidence shown safely, a yes tied to a hash of exactly what was shown, denials that hold for the whole run, runs that pause and resume instead of blocking, and an audit log that reveals edits.
- Durable runsHow to make an agent survive a crash without losing its work or doing it twice. What to save, the five moments to save it, a checkpoint write that a crash can’t tear, a lock and a restart limit, resuming by phase, and idempotency keys, attempt markers, and a three-step ladder for calls whose outcome nobody recorded.
- An agent as a serviceWhat changes when nobody is watching the agent. A static binary that picks up its own unfinished runs, a shutdown that cancels and saves inside the platform’s grace period, a container that keeps the key out of every environment, and a service that takes crash reports over HTTP, queues work in a directory, keeps its spending on disk, and parks decisions in a review queue.
- Libraries and SDKsThe provider SDKs, the MCP SDK, OpenTelemetry, and the five Go agent frameworks that the book’s code imports or measures, each with its pinned version, what it does well, what it costs, and the part of a harness it stands in for.
- The finished agentThe crash-triage agent the book ends with, measured on 20 held-out tasks with three models. Pass rates with their ranges, the cost of each passing run, how the failed runs went wrong, and how to point the agent at a Go service of your own.
Leading a team
For whoever decides whether a team spends its time here. It covers what the work costs, what the team ends up able to build, the risks and how they are handled, and what the material leaves out, mostly in pages with no code to read.
- For leadsA short page for whoever approves a team’s time on AI agents in Go. What live runs cost, what the team ends up able to build, the risks and how the material handles each one, what it leaves out, and how to get a team started.
- Workflow or agent?Programs that call a model come in five shapes, from a fixed sequence of calls to several cooperating agents. Pick the simplest one that handles the task, go further only when the task forces you to, and mix shapes when a task has a routine part and an open-ended part.
- Measured mistakesEvery failure on this page happened in a recorded run of the book’s code, and each comes with its task, its models, how many runs it rests on, the date, and the chapter. What went wrong, how often, and what the code changed because of it.
- Launch checklistTwenty-three checks for an agent that will run unattended and spend money, grouped by what can go wrong, each with the chapter that builds it and, where the book measured one, the failure that shows why it matters.
- The finished agentThe crash-triage agent the book ends with, measured on 20 held-out tasks with three models. Pass rates with their ranges, the cost of each passing run, how the failed runs went wrong, and how to point the agent at a Go service of your own.
- Beyond crash triageThe book’s agent triages crashes in a Go service, and its parts carry over to agents with other jobs. A support-ticket resolver, a SQL analyst, and a research assistant, each with the shape it needs, what goes wrong without the right parts, and how to measure it.
- Evals for an agentHow to tell whether an agent is good, and whether a change improved it. A tiered eval set, graders written as code with hidden tests, unscored runs kept out of the pass rate, rates reported with ranges, task-by-task comparisons, and the places a model reviewer and a model judge fit.
- ScopeThe ground this site and Building AI Agents in Go cover, the topics both leave out on purpose, such as retrieval, memory across runs, and multi-agent planning, and why, so you can tell before reading whether they answer your question.
- Why GoAn agent spends most of its time waiting on a network, running work side by side, and deciding when to stop. Four places where Go’s standard tools did that job in the book’s code, with the numbers, and what Go costs you here.
Browsing instead
If you’d rather look something up, each section in the header collects the guides on one subject, search finds a page by its title or headings, and the glossary defines the vocabulary. Every runnable program is listed in Run it, with the command that runs it offline.