Getting started¶
Purpose¶
Run the smallest useful agent — a model, a decoder, one prompt — and know where every capability lives in the package layout.
When to use¶
Start here for a first run or a new project. Every other guide assumes this setup.
How it works¶
An agent is built once with golem.New[Deps, Output] and run many times.
Two collaborators are required: a model.Model (usually a provider
adapter) and an OutputDecoder[Output] — the boundary where untrusted
model output becomes an application value. Everything else —
instructions, tools, budgets, schemas — is an option function.
A run returns a Result[Output] carrying the typed output, the full
normalized conversation in Messages, and cumulative Usage. Errors are
RunError values with an inspectable stage — compare against
golem.StageModel, golem.StageTool, golem.StageDecode,
golem.StageLoop, or golem.StageUsage — that preserve the cause for
errors.Is and errors.As. A run that had begun producing evidence —
completed model turns, reported usage, executed tools — carries it as
RunError.Partial: the conversation through the last completed model
turn, the usage completed turns reported, and the counts of model
requests and tool executions. Partial is nil when the run failed
before any of that; feed Partial.Messages to RunWithHistory to
resume a failed conversation.
Prompt templating¶
Instructions that depend on runtime state are a function:
WithInstructionsFunc evaluates per run against the run's typed
dependencies, and its result replaces any system messages in history,
so guidance never goes stale. When the prompt is genuinely a template,
render it with Go's text/template inside that function — Golem adds
no template engine, on purpose:
var policy = template.Must(template.New("policy").Parse(
"You are the {{.Product}} support agent. Answer in a {{.Tone}} tone."))
agent, _ := golem.New[config, string](client, decoder,
golem.WithInstructionsFunc[config, string](func(_ context.Context, runCtx golem.RunContext[config]) string {
var rendered strings.Builder
if err := policy.Execute(&rendered, runCtx.Deps); err != nil {
return "Instructions are temporarily unavailable: " + err.Error()
}
return rendered.String()
}),
)
Parse the template once at construction so a broken template fails at
startup; execute per run so the prompt follows the dependency value.
Run examples/prompt-template — offline — to see two agents render
the same template differently.
Example¶
Run examples/minimal:
OPENAI_API_KEY=sk-... go run ./examples/minimal
client, _ := openai.New(openai.Config{APIKey: apiKey, Model: "gpt-4o-mini"})
agent, _ := golem.New[struct{}, string](client,
golem.DecodeFunc[string](func(_ context.Context, r model.Response) (string, error) {
return r.Message.Content, nil
}),
)
result, err := agent.Run(ctx, golem.RunContext[struct{}]{}, "Reply with exactly the word: pong")
API surface¶
golem.New[Deps, Output](model, decoder, options ...Option[Deps, Output]) (*Agent[Deps, Output], error)(*Agent).Run(ctx, runCtx, prompt) (Result[Output], error)golem.RunContext[Deps]{Deps: value}golem.DecodeFunc[Output](func(ctx, model.Response) (Output, error))golem.WithInstructionsFunc[Deps, Output](func(ctx, RunContext[Deps]) string)— per-run instructions; compose withtext/templatefor templating
Gotchas¶
- Runs make at most
golem.DefaultMaxIterations(10) model turns; seeWithMaxIterations. - Cancellation and deadline errors ride a
RunErrorlike every other failure and stay matchable witherrors.Is(err, context.Canceled)through the chain — wrapping is what preserves their partial evidence. - Environment variables are read by the application, never by Golem.