Search

Every page

The loop

• 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.
• 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.
• 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.
• 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.
• 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.
• Streaming repliesA streamed chat completion arrives as server-sent events. This page reads one with a bufio.Scanner and an iterator, reassembles tool calls from their fragments, and stops a stream that stops sending.
• 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.

Design

• 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.
• Structured outputIf a program reads an agent’s answer, prose is a poor format, since a parser breaks the first time the wording changes. A final tool, whose arguments are the answer, gives you a typed result from any tool-calling model and a place to check the answer before you accept it.
• 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.
• 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.
• Parallel tool callsA single model reply often requests several tools. This page covers which of those calls can safely overlap, a runner built on sync.WaitGroup.Go and a semaphore that returns answers in the model’s order, and why the time it saves on a coding agent is measured in milliseconds.
• Sub-agentsA sub-agent is your agent loop run again from inside a tool, with an empty history, to answer one self-contained question. This page covers building one in Go, reporting one that ran out of turns, limiting nesting to one level, and a measured case where it didn’t pay off.
• MCP in GoThe Model Context Protocol lets any agent use tools a separate program offers. What the protocol is on the wire, how a Go client matches responses to calls and stops a server in the order the protocol asks, what the extra process costs, how much to trust another program’s tools, and when to use the official Go SDK.

Production

• 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.
• 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.

Run it

• 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.
• 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.
• ch07: One crash report, triagedThe crash-triage agent’s first run on a real Go web service, replayed offline. Four crash reports, two already filed, one bug that lives away from the line that crashed; fourteen tools, a final answer in a fixed shape, and a grade from the crash catalog.
• Streaming to a browserA server written with net/http alone sends an agent’s events, as they happen, to a page that reads them with EventSource. The headers, the flush, a deadline per write, a heartbeat, a client that leaves, and a shutdown that ends open streams, from a tested example.
• ch10: Filing issues over MCPThe crash-triage agent reaching its issue tracker only through the Model Context Protocol, with the server started as a separate process. Replay the run offline, serve the tracker to any MCP client, and pin the server’s tool definitions so a changed description stops the run.
• ch16: One task, three implementationsThe same approval-gated diagnosis written on the book’s agent package, on Eino, and on Genkit, run against the same scripted replies through a transport that records every request. Run the comparison, time a cancellation during a retry, and read what each version sends.

Providers and frameworks

• How two provider APIs differThe same agent request, sent as OpenAI-style chat completions through OpenRouter and as Anthropic’s Messages API, differs in twelve places, from where the system prompt goes to how a stream ends. A table of each difference, with the chapter and the code that handles it.
• Providers and SDKsHow to run one agent loop against providers whose APIs disagree on almost everything. An official SDK wrapped in your own interface with its retries off and its errors translated, a hand-written client for Anthropic’s Messages API, reasoning that has to return to the provider and host that produced it, and one task run through three clients.
• Go agent frameworks comparedFive Go agent frameworks set against the parts of an agent harness, as their source stood in October 2026, plus one approval-gated task ported to Eino and Genkit, what the code measured, and eight questions to put to any framework.
• More providersA reference for writing a third adapter. How the native APIs of Google’s Gemini, Ollama, Amazon Bedrock, and Cohere carry the system prompt, tool calls, tool results, stop reasons, and usage, whether each offers an OpenAI-compatible endpoint, and its official Go library, from each provider’s documentation as of October 18, 2026.
• 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.

Findings

• 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.
• 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.
• One sentence decided 79 of 80 first movesA sentence added to an MCP tool’s description, a tool the model hadn’t called yet, steered the first move of four models in 79 of 80 replies. A label marking the text as the server’s cut that to 57. What was tested, what it can’t show, and the defenses that work upstream of the model.
• How a tool error’s wording changed the turnsChapter 4 made a tool fail on every call and changed only the wording of its error. Told “the file is locked”, three of four models kept retrying and hunting for ways around the lock; told that retrying couldn’t help, every model stopped after one attempt.
• Workflow or agent, measuredChapter 1 fixed one Go bug on four models in two ways, as a three-step workflow written in code and as an agent that picks its own steps. The workflow was cheaper and faster on every model, and its single failure shows what it trades away.
• Fan-out, measuredChapter 9 triaged a batch of 99 crash reports two ways, with one agent per cause running four at a time and with a single agent over the whole batch. The fan-out took about as long and cost more, though its cost was steadier and its requests stayed small.
• Two identical runs, 15 points apartChapter 13 ran the same agent twice on each of 20 tasks and scored the second run against the first, as though one were a new version. The second came out 15 points ahead, with nothing changed. How to tell a real improvement from that, with ranges, paired comparisons, and counts.
• 910 crashes, no duplicatesChapter 15 crashed the agent’s run at every point a crash could land, restarted it, and counted duplicate issues. Saving once per turn duplicated work at 8 of its 18 crash points; idempotency keys removed every duplicate, and attempt markers without keys did too, at the price of 669 questions to a person.

Other pages

• 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.
• The bookLearn how AI agents work by building one in Go, from the first request to production, using the standard library. A book for Go developers, with every example runnable offline.
• 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.
• GlossaryThe vocabulary of building AI agents, from agent and harness to idempotency key and tool poisoning, each in a sentence or two, with the chapter of the book that covers it.
• 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.
• Start hereThree 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.
• Work with meDayna Blackwell of Blackwell Systems helps teams build, review, measure, and run AI agents in Go. Architecture and production reviews, eval design, AI cost optimization, hands-on team workshops, and AI opportunity assessments.