Planning¶
Purpose¶
Give an agent a task list it owns and updates through tools, so a long run keeps track of what it set out to do and what is left.
When to use¶
Multi-step work where the model must plan, execute, and revise — a research task, a refactor, a debugging session. For a single-turn answer the plan tools only add prompt weight; for deterministic orchestration, write the pipeline in Go with the Orchestration guide instead.
How it works¶
planning.Tools returns five ordinary tools:
write_plancreates or replaces the whole plan from ordered steps.read_planreturns the plan with step IDs, statuses, and progress.add_taskappends one pending step.update_task_statusmoves one step betweenpending,in_progress,completed, andcancelled.remove_taskdeletes one step.
Step IDs are stable strings; removal never reuses an ID. Every mutating tool ends its result with the full plan rendered as a checklist, so the latest plan rides the conversation's tool channel instead of the system prompt. Editing the plan therefore does not change the cached prompt prefix.
The plan lives behind planning.Store, which the application supplies:
Load(ctx, key) and Save(ctx, key, plan). Config.Key derives the
key from the run's dependencies, so one store can hold one plan per
tenant or conversation; a nil Key uses a single empty key.
planning.Memory is the in-process implementation. The package never
reads the environment, clock, or working directory.
planning.Instructions is the guidance the tools assume — keep one step
in progress and update the plan as work advances. The package does not
install it; add it with golem.WithInstructions so the agent's
instructions stay the application's decision.
Bad model input — empty content, an unknown ID, an unsupported status,
malformed JSON — returns &tool.Failed, so the model sees the reason
and can correct the call without aborting the run. A store failure is
an infrastructure error and aborts the run at the tool stage.
Example¶
examples/planning runs offline
against a scripted model and prints each plan tool result:
tools, err := planning.Tools(planning.Config[struct{}]{Store: planning.NewMemory()})
agent, err := golem.New[struct{}, string](client, decoder,
golem.WithInstructions[struct{}, string](planning.Instructions),
golem.WithTools[struct{}, string](tools...),
)
API surface¶
planning.Tools[Deps](planning.Config[Deps]) ([]tool.Tool[Deps], error)planning.Config[Deps]{Store Store, Key func(Deps) string}planning.Store—Load(ctx, key) (Plan, error)andSave(ctx, key, Plan) errorplanning.Memory,planning.NewMemory()planning.Plan,planning.Item,planning.Status(Pending,InProgress,Completed,Cancelled)planning.Instructions- Tool names:
write_plan,read_plan,add_task,update_task_status,remove_task
Gotchas¶
- The toolset serializes its own load-mutate-save steps, but two toolsets sharing one store and key are separate writers. Scope keys per run or tenant, or serialize in the store.
- History compaction can drop earlier plan results. The plan is still in
the store; the model can call
read_planto restore it, but the package does not re-inject it automatically before each request. write_planreplaces the whole plan, including IDs. Useadd_taskandupdate_task_statusto preserve progress.- A plan is prompt content, not a security boundary. Do not store secrets in step text, and re-check high-stakes actions in the tool that performs them.
- The deciding design record is
docs/adr/0044-planning-tools.md.