Agent Loop (ReAct) in Go

The Problem

A single LLM call rarely solves complex tasks. The model may need to look up information, run a calculation, check a file, and then synthesize the results — steps that can’t all happen in one prompt. Without a loop, the agent is blind: it can’t act on what it learned.

The Solution

The ReAct (Reason + Act) pattern gives the agent a tight loop. Each iteration asks the model to reason about the current state, decide on one action, observe the result, and repeat. The loop terminates when the model emits a final answer or the iteration cap is reached. In Go, this translates naturally to a for range maxIterations loop with a Tool interface for dispatch and a []HistoryEntry slice for context accumulation.

Structure

Agent Loop (ReAct) Pattern

Step 1 of 5

Query Entry

The caller passes a natural-language query to ReactAgent.Run(). The agent initializes a History slice with one user entry and starts the loop.

flowchart TD
User["User Query"]
Agent["ReactAgent.Run()"]
LLM["LLM (think)"]
Parse["Parse Response"]
Final{"IsFinal?"}
Dispatch["Tool.Execute()"]
History["Append to History"]
Answer["Return Answer"]
Error["Return Error (max iterations)"]

User --> Agent
Agent --> LLM
LLM --> Parse
Parse --> Final
Final -->|"yes"| Answer
Final -->|"no"| Dispatch
Dispatch --> History
History --> LLM
Agent -->|"cap exceeded"| Error

Implementation

package main

import "context"

// Tool is a named, executable capability the agent can call.
type Tool interface {
	Name() string
	Description() string
	Execute(ctx context.Context, args map[string]any) (string, error)
}

// HistoryEntry records one turn in the agent's reasoning trace.
type HistoryEntry struct {
	Role    string // "thought", "action", "observation", "answer"
	Content string
}

// Step represents one iteration of the ReAct loop.
type Step struct {
	Thought    string
	Action     string
	ActionArgs map[string]any
	IsFinal    bool
	Answer     string
}

package main

import (
	"context"
	"errors"
	"fmt"
)

// ReactAgent drives the Reason→Act loop until a final answer or iteration cap.
type ReactAgent struct {
	tools         map[string]Tool
	maxIterations int
}

func NewReactAgent(maxIterations int, tools ...Tool) *ReactAgent {
	m := make(map[string]Tool, len(tools))
	for _, t := range tools {
		m[t.Name()] = t
	}
	return &ReactAgent{tools: m, maxIterations: maxIterations}
}

// Run executes the ReAct loop for the given query and returns the final answer.
func (a *ReactAgent) Run(ctx context.Context, query string) (string, error) {
	history := []HistoryEntry{{Role: "user", Content: query}}

	for i := range a.maxIterations {
		step, err := a.think(ctx, history)
		if err != nil {
			return "", fmt.Errorf("iteration %d: %w", i, err)
		}

		history = append(history, HistoryEntry{Role: "thought", Content: step.Thought})

		if step.IsFinal {
			return step.Answer, nil
		}

		observation, err := a.act(ctx, step)
		if err != nil {
			observation = fmt.Sprintf("tool error: %v", err)
		}
		history = append(history,
			HistoryEntry{Role: "action", Content: step.Action},
			HistoryEntry{Role: "observation", Content: observation},
		)
	}

	return "", errors.New("agent exceeded maximum iterations without a final answer")
}

// think calls the LLM (stubbed) and parses its output into a Step.
func (a *ReactAgent) think(_ context.Context, history []HistoryEntry) (Step, error) {
	// In production: serialize history into a prompt, call the LLM API,
	// and parse the structured response into a Step.
	_ = history
	return Step{IsFinal: true, Answer: "42"}, nil
}

// act dispatches the chosen tool and returns its observation.
func (a *ReactAgent) act(ctx context.Context, step Step) (string, error) {
	tool, ok := a.tools[step.Action]
	if !ok {
		return "", fmt.Errorf("unknown tool %q", step.Action)
	}
	return tool.Execute(ctx, step.ActionArgs)
}

package main

import (
	"context"
	"fmt"
	"log"
)

// echoTool is a minimal tool that returns its input for demonstration.
type echoTool struct{}

func (e *echoTool) Name() string        { return "echo" }
func (e *echoTool) Description() string { return "Returns the input string unchanged." }
func (e *echoTool) Execute(_ context.Context, args map[string]any) (string, error) {
	msg, _ := args["message"].(string)
	return msg, nil
}

func main() {
	agent := NewReactAgent(10, &echoTool{})

	answer, err := agent.Run(context.Background(), "What is the meaning of life?")
	if err != nil {
		log.Fatalf("agent error: %v", err)
	}

	fmt.Printf("Answer: %s\n", answer)
	// Output: Answer: 42
}

Real-World Analogy

A researcher solving a problem doesn’t write the whole answer from memory. They read a source, take notes, look up a reference, cross-check a fact, and only then write the conclusion. The ReAct loop is the same workflow: think, act, observe, repeat until done.

Pros and Cons

Pros	Cons
Handles multi-step tasks that require intermediate lookups	Each iteration costs one LLM API call
Clean separation between reasoning (LLM) and execution (tools)	Errors compound — a bad observation can mislead subsequent reasoning
History slice gives the model full context for complex chains	Requires careful prompt design for the LLM to emit structured Steps
Iteration cap prevents runaway loops	Long chains exhaust the context window

Best Practices

Keep maxIterations low (5–10) in production; long chains are usually a sign of unclear tool design.
Represent History as a typed slice, not a raw string — it makes serialization and testing easier.
Return structured errors from tools so the agent can reason about failures, not just observe opaque strings.
Log every Step at DEBUG level; the reasoning trace is your primary debugging artifact.
Test the think stub independently from the loop to avoid burning LLM tokens during unit tests.

When to Use

Tasks that require multiple sequential information-gathering steps before an answer is possible.
Agentic workflows where the model needs to call tools, evaluate results, and adapt its plan.
Automated research, code generation with verification, or multi-step form filling.

When NOT to Use

Simple single-turn question answering — one LLM call is cheaper and faster.
Workflows where the steps are fully known in advance — use a pipeline instead.
Real-time latency-sensitive paths where multiple sequential LLM calls are unacceptable.

Tool Use in Go Register typed tools by name so an agent can dispatch LLM-selected function calls to the right handler without embedding dispatch logic in the agent itself. State in Go Change an object’s behavior when its internal state changes by delegating transitions and rules to state-specific types. Template Method in Go Define the skeleton of an algorithm once while letting concrete steps vary through narrow hook methods. Orchestrator-Subagent in Go Decompose a complex task by having a root agent spawn and coordinate specialized subagents, each responsible for one concern, then aggregate their results.