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 an LLM interface for the reasoning step, a Tool interface for dispatch, and a []HistoryEntry slice for context accumulation. Injecting the model behind an interface keeps the loop testable: the demo scripts the model’s steps deterministically, while production swaps in a real API client without touching the loop.

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.NextStep()"]
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

gofmt ✓

package main

import "context"

// LLM produces the next reasoning step from the conversation history.
// Production implementations call a model API and parse the structured
// response; demos and tests can script deterministic steps.
type LLM interface {
	NextStep(ctx context.Context, history []HistoryEntry) (Step, error)
}

// 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 {
	llm           LLM
	tools         map[string]Tool
	maxIterations int
}

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

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

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

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

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

		if step.IsFinal {
			history = append(history, HistoryEntry{Role: "answer", Content: step.Answer})
			return step.Answer, history, nil
		}

		// A tool failure is fed back as an observation instead of aborting,
		// so the model can recover — retry, pick another tool, or give up.
		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 "", history, errors.New("agent exceeded maximum iterations without a final answer")
}

// 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"
	"strconv"
	"time"
)

// calculatorTool multiplies two numeric arguments. Real agents would expose
// search, database, or API tools through this same interface.
type calculatorTool struct{}

func (calculatorTool) Name() string { return "calculator" }
func (calculatorTool) Description() string {
	return "Multiplies two numbers. Args: a (number), b (number)."
}

func (calculatorTool) Execute(_ context.Context, args map[string]any) (string, error) {
	a, aOK := args["a"].(float64)
	b, bOK := args["b"].(float64)
	if !aOK || !bOK {
		return "", fmt.Errorf("calculator requires numeric args %q and %q", "a", "b")
	}
	return strconv.FormatFloat(a*b, 'f', -1, 64), nil
}

// scriptedLLM stands in for a real model client so the demo is deterministic.
// It requests a tool call on the first step, then reads the observation from
// history to produce the final answer — the same shape a real LLM run has.
type scriptedLLM struct {
	step int
}

func (s *scriptedLLM) NextStep(_ context.Context, history []HistoryEntry) (Step, error) {
	s.step++
	if s.step == 1 {
		return Step{
			Thought:    "I need the total unit count. 42 pallets with 18 units each — use the calculator.",
			Action:     "calculator",
			ActionArgs: map[string]any{"a": 42.0, "b": 18.0},
		}, nil
	}

	observation := lastByRole(history, "observation")
	return Step{
		Thought: "The calculator returned the product, so I can answer directly.",
		IsFinal: true,
		Answer:  fmt.Sprintf("The warehouse holds %s units (42 pallets × 18 units).", observation),
	}, nil
}

func lastByRole(history []HistoryEntry, role string) string {
	for i := len(history) - 1; i >= 0; i-- {
		if history[i].Role == role {
			return history[i].Content
		}
	}
	return ""
}

func main() {
	fmt.Println("=== Agent Loop (ReAct) in Go ===")

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	agent := NewReactAgent(&scriptedLLM{}, 10, calculatorTool{})

	answer, trace, err := agent.Run(ctx, "How many units are in the warehouse?")
	if err != nil {
		log.Fatalf("agent error: %v", err)
	}

	fmt.Println("--- reasoning trace ---")
	for _, entry := range trace {
		fmt.Printf("%-12s %s\n", entry.Role+":", entry.Content)
	}
	fmt.Printf("\nAnswer: %s\n", answer)
}

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 returned by Run is your primary debugging artifact.
Hide the model behind a narrow LLM interface so unit tests can script steps deterministically instead of burning tokens.
Check ctx.Err() at the top of each iteration so cancellation and deadlines stop the loop between steps.

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.

Agent Loop (ReAct)