
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.
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.
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:
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)(ctxis acontext.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, ortool). - 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
- Build the request
Decide what the model sees: instructions, the conversation so far, tool results, and the tools it may call.
- Call the model
Send the request and read the reply, with a deadline and a count of what it cost.
- Run the tools
Carry out the calls the model asked for, and add each result to the conversation.
- Decide
Stop with an answer, stop at a limit, or go around again.
- What each call sends
- Call 1 sent the tool list and 1 message: 583 tokens.
- Call 2 sent the tool list and 4 messages, 3 of them new: 834 tokens.
- Call 3 sent the tool list and 7 messages, 3 of them new: 1,846 tokens.
- Call 4 sent the tool list and 10 messages, 3 of them new: 2,164 tokens.
- In all, the four calls sent 5,427 tokens.
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:
$ 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.
type pathArgs struct {
Path string `json:"path"` // <1>
}
type pathArgs struct { Path string `json:"path"` // <1> }. In ch01/agent/tools.go, line 54.
field Path string `json:"path"`
field Path string `json:"path"`. In ch01/agent/tools.go, line 55.
type string string
string is the set of all strings of 8-bit bytes, conventionally but not necessarily representing UTF-8-encoded text.
string is the set of all strings of 8-bit bytes, conventionally but not necessarily representing UTF-8-encoded text. type string string. Documented at pkg.go.dev, builtin.string.
func readFile(fs FS) Tool
func readFile(fs FS) Tool. In ch01/agent/tools.go, line 58.
type FS map[string]string
FS is a small in-memory file system: file names and their contents.
FS is a small in-memory file system: file names and their contents. type FS map[string]string. In ch01/agent/memfs.go, line 12.
type Tool struct {
Def ToolDef
Run func(ctx context.Context, args jsontext.Value) (string, error)
}
Tool is the harness's side of a tool: the definition the model sees, and the Go function that runs it.
Tool is the harness's side of a tool: the definition the model sees, and the Go function that runs it. type Tool struct { Def ToolDef Run func(ctx context.Context, args jsontext.Value) (string, error) }. In ch01/agent/types.go, line 65.
type ToolDef struct {
Name string
Description string
Parameters jsontext.Value // a JSON Schema
}
ToolDef describes a tool to the model.
ToolDef describes a tool to the model. type ToolDef struct { Name string Description string Parameters jsontext.Value // a JSON Schema }. In ch01/agent/types.go, line 41.
field Description string
field Description string. In ch01/agent/types.go, line 43.
field Parameters jsontext.Value
a JSON Schema
a JSON Schema field Parameters jsontext.Value. In ch01/agent/types.go, line 44.
package jsontext ("encoding/json/jsontext")
Package jsontext implements syntactic processing of JSON as specified in RFC 4627, RFC 7159, RFC 7493, RFC 8259, and RFC 8785.
Package jsontext implements syntactic processing of JSON as specified in RFC 4627, RFC 7159, RFC 7493, RFC 8259, and RFC 8785. package jsontext ("encoding/json/jsontext"). Documented at pkg.go.dev, encoding/json/jsontext.
type Value []byte
Value represents a single raw JSON value, which may be one of the following:
Value represents a single raw JSON value, which may be one of the following: type Value []byte. Documented at pkg.go.dev, encoding/json/jsontext.Value.
field Run func(ctx context.Context, args jsontext.Value) (string, error)
field Run func(ctx context.Context, args jsontext.Value) (string, error). In ch01/agent/types.go, line 67.
package context ("context")
Package context defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes.
Package context defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes. package context ("context"). Documented at pkg.go.dev, context.
type Context interface {
// Deadline returns the time when work done on behalf of this context
// should be canceled. Deadline returns ok==false when no deadline is
// set. Successive calls to Deadline return the same results.
Deadline() (deadline time.Time, ok bool)
// Done returns a channel that's closed when work done on behalf of this
// context should be canceled. Done may return nil if this context can
// never be canceled. Successive calls to Done return the same value.
// The close of the Done channel may happen asynchronously,
// ...
}
A Context carries a deadline, a cancellation signal, and other values across API boundaries.
A Context carries a deadline, a cancellation signal, and other values across API boundaries. type Context interface { // Deadline returns the time when work done on behalf of this context // should be canceled. Deadline returns ok==false when no deadline is // set. Successive calls to Deadline return the same results. Deadline() (deadline time.Time, ok bool) // Done returns a channel that's closed when work done on behalf of this // context should be canceled. Done may return nil if this context can // never be canceled. Successive calls to Done return the same value. // The close of the Done channel may happen asynchronously, // ... }. Documented at pkg.go.dev, context.Context.
var args jsontext.Value
var args jsontext.Value. In ch01/agent/tools.go, line 70.
type error interface {
Error() string
}
The error built-in interface type is the conventional interface for representing an error condition, with the nil value representing no error.
The error built-in interface type is the conventional interface for representing an error condition, with the nil value representing no error. type error interface { Error() string }. Documented at pkg.go.dev, builtin.error.
func decodeArgs[T any](args jsontext.Value, example string) (T, error)
decodeArgs decodes a tool call's arguments.
decodeArgs decodes a tool call's arguments. func decodeArgs[T any](args jsontext.Value, example string) (T, error). In ch01/agent/tools.go, line 41.
var nil Type
nil is a predeclared identifier representing the zero value for a pointer, channel, func, interface, map, or slice type.
nil is a predeclared identifier representing the zero value for a pointer, channel, func, interface, map, or slice type. var nil Type. Documented at pkg.go.dev, builtin.nil.
func (fs FS) Read(name string) (string, error)
Read returns a file's contents.
Read returns a file's contents. func (fs FS) Read(name string) (string, error). In ch01/agent/memfs.go, line 20.

