The Gopher as a conductor in a cap, one hand on a tall lever, watches the Ghost, a stone android, ride a loop-the-loop in a car far too small for it, past four stations: a box, a cylinder, a cone, and an arch.

Basics

What an AI agent is, in terms a Go programmer can build

What makes a program an agent, followed through one run that fixes a failing test.

Updated Beginner

On the agent compass The whole loop, all four stages

“Agent” now gets attached to nearly anything that calls a model. A Go programmer needs a definition narrow enough to implement and test, so this site uses this one:

Rather than argue for that definition, this page shows one agent working and then names the pieces you would write to build it.

One agent, four turns

Start with a tiny Go package, duration, whose job is turning a string such as "1h30m" into a time.Duration. Two of its tests fail. The agent is told that the tests fail and asked to find the cause and fix it, and it has four tools to work with: list_files, read_file, edit_file, and run_tests.

A recorded run has anthropic/claude-haiku-5.5 doing exactly this in October 2026. Each row below is one round trip to the model:

Turn The model asked for The program did
1 run_tests, list_files Ran the tests (two failures), listed the two files
2 read_file on both files Sent back their contents
3 edit_file: 'm': time.Second becomes 'm': time.Minute; then run_tests Made the edit; the tests pass
4 Nothing: an answer explaining the typo Stopped and showed the answer

Look at the middle column: it holds nothing but requests. The model has no access to the files and no way to get any: it receives text and replies with text, so everything it knows about the task arrived in the request. The right-hand column is where things happen, and all of it is your Go program: the code that gives read_file its meaning, runs the tests, applies the edit, and notices that the job is over.

One run proves little, so the task was repeated 40 times, ten runs on each of four models. All 40 fixed the bug, each in four to six turns, and no run cost more than a fifth of a cent. (The four models were anthropic/claude-haiku-5.5, openai/gpt-5.6-luna, z-ai/glm-5.3-flash, and deepseek/deepseek-v4.1-flash; you can skip the names on a first read.) That price is counted in tokens, the pieces of text a model reads and writes: a common word, a fragment of a longer word, or a punctuation mark. A provider charges for every token in the request and every token in the reply, at a price per million. The routes differed more than the outcomes. Two of the models repeated an identical sequence of calls in every run; the other two wandered by a turn. In some order, every run surveyed the project, read the source, edited it, and ran the tests to confirm.

Turn 3 in four steps: the request holds the conversation so far and the four tool definitions; the reply holds two calls, call_5 to edit_file and call_6 to run_tests; the harness runs them in order, producing a tool message for each call; the two messages are appended and turn 4 begins.Turn 3 in four steps: the request holds the conversation so far and the four tool definitions; the reply holds two calls, call_5 to edit_file and call_6 to run_tests; the harness runs them in order, producing a tool message for each call; the two messages are appended and turn 4 begins.Turn 3 in four steps: the request holds the conversation so far and the four tool definitions; the reply holds two calls, call_5 to edit_file and call_6 to run_tests; the harness runs them in order, producing a tool message for each call; the two messages are appended and turn 4 begins.Turn 3 in four steps: the request holds the conversation so far and the four tool definitions; the reply holds two calls, call_5 to edit_file and call_6 to run_tests; the harness runs them in order, producing a tool message for each call; the two messages are appended and turn 4 begins.Turn 3 in four steps: the request holds the conversation so far and the four tool definitions; the reply holds two calls, call_5 to edit_file and call_6 to run_tests; the harness runs them in order, producing a tool message for each call; the two messages are appended and turn 4 begins.
One turn of the bug fix: the request carries the conversation and the tool definitions, the reply asks for two tools, and their results join the conversation.

Three ways to use a model

The useful question for telling model programs apart is: who chooses the next step?

Shape Who decides the next step Example
Chatbot The person, one reply at a time A chat window that answers questions
Workflow Your code, at points fixed in advance Summarize each support ticket, then route it by the summary
Agent The model, on each turn, from what the last step returned The bug fix above

Nothing in the bug-fix program told the model to open the test file once it had seen the file list. The listing prompted that choice, and the test output prompted the edit. That is what puts it in the third row. Anthropic draws the line between workflows and agents in “Building effective agents”; the chatbot is added here as the simplest shape. Most real systems mix the shapes: a ticket system can send all tickets through a fixed workflow and pass only the odd cases to an agent.

Often the workflow is the right answer. If you already know the steps, fixing them in code means fewer model calls, the same path on every run, lower cost, and tests that are easy to write. An agent pays for itself only when the step after this one can’t be known until this one has run.

The model only asks

Simon Willison defines an LLM agent as something that runs tools in a loop to achieve a goal. That is accurate as far as it goes, but the model runs nothing. It produces requests, and some program has to carry them out and hold on to the conversation. That program is the harness, and it does two jobs:

  • Run the tools the model asks for, safely, and send back each result.
  • Decide what the model sees on every call. A model remembers nothing from one call to the next. Every request has to include the conversation so far, so whatever you put in the request is the model’s entire knowledge of the task. It also means every turn’s request is bigger than the last, and every token of it is billed again; Tokens, cost, and the context window follows that growth through a run.

The second job is every bit as important as the first. Later pages cover it under the name context management: deciding, as a run gets longer, what stays in the request, what gets cut, and what gets summarized.

Tools have two sides

A tool faces two directions. Toward the model it is a name and a description, plus a JSON Schema (a JSON description of which arguments the tool takes and their types) for its arguments. Toward your program it is a Go function, which the model never sees. The companion code keeps both halves in a single value:

ch01/agent/tools.go
type pathArgs struct {
	Path string `json:"path"`
}

func readFile(fs FS) Tool {
	return Tool{
		Def: ToolDef{
			Name:        "read_file",
			Description: "Read a file in the project.",
			Parameters: jsontext.Value(`{
				"type": "object",
				"properties": {"path": {"type": "string"}},
				"required": ["path"]
			}`),
		},
		Run: func(_ context.Context,
			args jsontext.Value) (string, error) {
			a, err := decodeArgs[pathArgs](args,
				`{"path": "a.go"}`)
			if err != nil {
				return "", err
			}
			return fs.Read(a.Path)
		},
	}
}

A few pieces of syntax here trip up newer Go readers. The backticks around the schema make a raw string, which can span lines and hold double quotes without escaping. Run is a field of the Tool struct that holds a function, which is how one value carries both halves. The _ parameter is the context.Context that this tool doesn’t use, and _ is Go’s way of saying so. The New to Go? box covers these and the rest.

From this, the model learns that a tool called read_file exists, what it is for, and what arguments it takes, so it can ask for it with something like {"path": "duration.go"}. When that request arrives, Run unpacks the JSON into a struct and opens the file. Arguments that fail to unpack produce an error that shows a correct example, which gives the model what it needs to send a better call next time.

Tag every struct field that a model fills with an explicit json name; a struct tag is the backtick text after a field’s type, such as json:"path" in the listing above. The companion code uses encoding/json/v2, part of the standard library in Go 1.27, and it matches names case-sensitively: without a tag, "path" does not land in Path, decoding reports no error, and the tool receives an empty path.

The parts you write

An agent in Go comes down to a handful of plain pieces:

  • A model interface with one method, Generate(ctx, req) (ctx is a context.Context, the value Go code passes along so a caller can cancel the call or set a deadline), so a scripted fake and a real HTTP client are interchangeable.
  • Messages: the conversation as a slice, each with a role (system, user, assistant, or tool).
  • Tools: a definition the model reads and a function the harness calls.
  • The loop: assemble a request, send it, act on any tool calls in the reply, then either finish or take another turn. The agent loop in Go shows it in about 30 lines.
  • Limits: a cap on turns from the very first version, and later a cap on spending, since nothing else stops a loop that never gets an answer.

Every turn of that loop passes through the same four stages, and every page on this site works on one of them or on the whole loop:

The agent compass

  1. Build the request

    Decide what the model sees: instructions, the conversation so far, tool results, and the tools it may call.

  2. Call the model

    Send the request and read the reply, with a deadline and a count of what it cost.

  3. Run the tools

    Carry out the calls the model asked for, and add each result to the conversation.

  4. Decide

    Stop with an answer, stop at a limit, or go around again.

  1. What each call sends
  2. Call 1 sent the tool list and 1 message: 583 tokens.
  3. Call 2 sent the tool list and 4 messages, 3 of them new: 834 tokens.
  4. Call 3 sent the tool list and 7 messages, 3 of them new: 1,846 tokens.
  5. Call 4 sent the tool list and 10 messages, 3 of them new: 2,164 tokens.
  6. In all, the four calls sent 5,427 tokens.

Every call sends the tool list and the whole conversation again: everything the call before it sent, plus the messages added since.

Then back to stage 1, with everything that just happened in the conversation.

You don’t need a framework for any of this, and you don’t need a model to test it. The loop in the companion code runs against a scripted list of replies, so its rules are checked by tests that finish in milliseconds and never touch the network. Frameworks wrap the same loop with extra features, and they are easier to judge once you have built the parts yourself.

When not to build one

Each turn is a network call that takes seconds and is billed. An early mistake carries forward, since every later turn builds on what the model concluded from it. And the same task can follow a different route on a different run, so an agent is harder to test than a function that always does the same thing. When you can list the steps before the program starts, build a workflow. When you can’t, an agent is worth its extra cost and harder testing.

Try it

You need Go 1.27; a go command from 1.21 on downloads that toolchain the first time it reads the module’s go.mod, so the first run pauses for a moment. From the code directory of a clone of the companion repository:

terminal
$ go run ./ch01

This plays back the run from the table through a loop short enough to read in one sitting, with no API key and no network. The ch01 example explains the output line by line.