go-agents

README

go-agents

A lightweight Go library for building LLM-based agents with the Anthropic API.

Overview

go-agents provides reusable infrastructure for agentic workflows so you can focus on domain-specific behavior rather than plumbing. The library manages the agent loop (LLM calls, tool dispatch, streaming) and conversation state, instrumented with OpenTelemetry tracing and structured logging.

Core components:

• Agent -- drives the agent loop, coordinates tool execution and conversation history
• Completer -- stateless adapter bridging to the Anthropic Go SDK
• Tool Registry -- manages tool definitions and dispatch
• Conversation State -- maintains message history across turns

Capabilities layer on progressively: tool use, human-in-the-loop approval, extended thinking, deterministic loop hooks (interpose non-LLM logic at PreLLMCall, PreToolUse, and PostToolUse), sub-agent composition (run a separate agent loop as a tool), and prompt caching (cache-control breakpoints on stable prefixes, enabled by default).

Why This Exists

go-agents is both a working library and a deliberate exercise in applying requirements engineering rigor to agent development. The code is intended to be useful on its own terms, but the project is also an experiment in whether a disciplined, PEGS-structured requirements process produces better design decisions than jumping straight to implementation — a question that feels especially sharp for LLM-based systems, where the problem space is fluid and conventions are still forming.

Readers interested in the methodology rather than the API should start with requirements/README.md, which documents the PEGS structure used here and links to the four requirements books.

Quick Start

package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/rfbigelow/go-agents/agent"
)

func main() {
	client := anthropic.NewClient() // reads ANTHROPIC_API_KEY from env
	completer := agent.NewAnthropicCompleter(client)
	registry := agent.NewToolRegistry()

	a := agent.NewAgent(completer, registry, agent.Config{
		System:    "You are a helpful assistant.",
		Model:     anthropic.ModelClaudeSonnet4_5,
		MaxTokens: 1024,
	})

	err := a.Run(context.Background(), "Hello!", func(e agent.Event) {
		if e.Type == agent.EventTextDelta {
			fmt.Print(e.Text)
		}
	})
	if err != nil {
		panic(err)
	}
	fmt.Println()
}

Installation

go get github.com/rfbigelow/go-agents

Requires Go 1.26+ and an Anthropic API key.

Running the Examples

export ANTHROPIC_API_KEY=sk-ant-...
go run ./examples/chat/       # basic streaming chat (+ extended thinking)
go run ./examples/tool-use/   # tool use: current time + calculator
go run ./examples/hitl/       # tool use with human approval gate
go run ./examples/sub-agent/  # parent agent delegating to sub-agents

Project Status

M1 (Basic Conversation), M2 (Tool Use), M3 (HITL Example), M4 (Extended Thinking), M5 (Deterministic Logic), M7 (Sub-Agent Composition), M8 (Prompt Caching), M9 (Conversation Resumption), and M10 (Context Compaction) are implemented: streaming completions, conversation state management, tool registration, parallel tool dispatch with a working human approval gate (see examples/hitl/), Extended Thinking with adaptive and enabled modes plus output_config.effort (see examples/chat/), typed loop hooks at PreLLMCall, PreToolUse, and PostToolUse for interposing deterministic non-LLM logic on the agent loop, sub-agent composition where a tool runs a separate agent loop — one-shot or multi-turn, with optional attributed stream forwarding and HITL propagation (see examples/sub-agent/), prompt caching with cache-control breakpoints on stable prefixes (enabled by default, opt-out via Config), conversation resumption via NewAgentWithHistory — construct an agent from persisted message history, validated against the S2.15 resumption invariants, opt-in conversation compaction — a CompactionStrategy extension point with library-provided hybrid-summarization and sliding-window strategies, manual, proactive (token-threshold), and reactive (on context overflow) triggers, token usage reporting via Agent.Usage, and archival of the replaced prefix for lossless resume — and observability (OTEL tracing + slog logging) across LLM calls, tool-dispatch batches, individual tool executions, and sub-agent invocations.

Planned milestones: Example Application (M6) — the dog-food application remains in progress.

See requirements/ for the full PEGS requirements.

Dependencies

• Anthropic Go SDK
• OpenTelemetry Trace API
• Go standard library (slog, context)

Contributing

This is a personal project and isn't open to outside contributions at this time. The development workflow — protected main, PR-based, gated by CI (gofmt, go vet, go build, go test) — is documented in CONTRIBUTING.md for reference.

License

MIT