A Go-first framework for building dependable, production-grade AI agents.
Compile-time type safety, zero external dependencies, explicit execution control, and deep MCP integration.

Read the Documentation »

Why Golem? • Quick Start • Supported Providers • Architecture • Common Tools & MCP • Testing • Guides Index • Examples • Contributing

---

Why Golem?

Python frameworks like Pydantic AI made agent prototyping accessible with typed schemas and clean ergonomics. However, deploying AI agents to mission-critical production systems demands the strengths of Go: high-throughput concurrency, predictable memory usage, fast execution, small deployment binaries, and compile-time correctness.

Golem bridges that gap by offering idiomatic, enterprise-ready agent abstractions designed specifically for Go engineers:

• 🛡️ Compile-Time Type Safety & Generics: Agents are declared as Agent[Deps, Output]. Tools access strongly-typed dependencies (databases, auth contexts, HTTP clients) via RunContext[Deps]. No map[string]any spaghetti or unexpected runtime reflection errors.
• 📦 Zero External Dependencies: Built exclusively on Go's standard library. Instant compilation, tiny container images, and a clean security profile free of supply-chain vulnerabilities.
• 🌐 Provider Agnostic: Native adapters for OpenAI, Anthropic (with prompt caching and thinking signatures), Google Gemini, AWS Bedrock (Converse API with SigV4), Azure OpenAI, and local offline models with Ollama and LM Studio.
• 🔌 Native Model Context Protocol (MCP): Full-featured MCP client supporting both stdio and streaming HTTP transports, effortlessly turning external MCP servers into typed agent tools.
• 🔄 Production Resilience & Self-Correction: In-loop model self-correction (ModelRetry), automated multi-model fallbacks, exponential backoff, per-tool deadlines, and clean in-tool cancellation (tool.Canceled).
• 📊 Auditable & Observable Evidence: Every run produces normalized messages, durable additive JSON, live streamable run events, reasoning/thinking token capture, and RunError.Partial—preserving all intermediate tool results even when a run fails or gets cancelled.
• ⏸️ Human-in-the-Loop & Deferred Execution: Pause agent runs cleanly when tools require human sign-off or external async triggers, and resume deterministically with full preserved state.
• 🛠️ Batteries-Included Tooling: Layout-aware PDF extraction (pdfextract), multi-format document extraction (docextract: Word, Excel, PowerPoint, Markdown, CSV), SSR web reader (webfetch), workspace file accessor (fileread), shell command execution (shell), and Agent Skills progressive loading (skills).
• 💰 Budget & Cost Guards: Pre-send token estimation, token-budgeted history truncation, client-side untrusted history sanitization (SanitizeHistory), and user-defined price tables to calculate and cap dollar costs per run.

---

Architecture

Golem orchestrates agents through a transparent, observable execution loop:

                         ┌────────────────────────────────────────┐
                         │         golem.RunContext[Deps]         │
                         │        (Typed Run Dependencies)        │
                         └───────────────────┬────────────────────┘
                                             ▼
┌─────────────────┐          ┌───────────────────────────────┐          ┌─────────────────┐
│     Prompt      │ ───────► │     golem.Agent[Deps, Out]    │ ───────► │  Typed Output   │
│ (Text, Images,  │          │                               │          │  Result[Output] │
│ Docs, Audio)    │          │  ┌─────────────────────────┐  │          └─────────────────┘
└─────────────────┘          │  │ Observable Loop         │  │                   │
                             │  │ - Self-Correction       │  │                   ▼
                             │  │ - Retries & Fallbacks   │  │          ┌─────────────────┐
                             │  │ - Token & Cost Bounds   │  │          │ Durable Evidence│
                             │  │ - Run Events Stream     │  │          │ (Messages, Cost,│
                             │  └────────────┬────────────┘  │          │  Token Usage)   │
                             └───────────────┼───────────────┘          └─────────────────┘
                                             │
                      ┌──────────────────────┴──────────────────────┐
                      ▼                                             ▼
        ┌───────────────────────────┐                 ┌───────────────────────────┐
        │      Model Adapters       │                 │      Tools & Protocols    │
        │  • OpenAI & Azure OpenAI  │                 │  • Strongly Typed Tools   │
        │  • Anthropic Claude       │                 │  • MCP Client (stdio/HTTP)│
        │  • Google Gemini          │                 │  • PDF & Doc Extractors   │
        │  • AWS Bedrock (SigV4)    │                 │  • Web Fetch & Shell      │
        │  • Local (Ollama/LMStudio)│                 │  • Agent Skills (SKILL.md)│
        └───────────────────────────┘                 └───────────────────────────┘

---

Installation

go get github.com/abubakarsiddik31/golem

Requires Go 1.26.5 or newer. Zero external dependencies.

---

Quick Start

1. Minimal Agent

Initialize a model adapter, create a typed agent, and execute a prompt:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/abubakarsiddik31/golem"
	"github.com/abubakarsiddik31/golem/model"
	"github.com/abubakarsiddik31/golem/providers/openai"
)

func main() {
	client, err := openai.New(openai.Config{
		APIKey: os.Getenv("OPENAI_API_KEY"),
		Model:  "gpt-4o-mini",
	})
	if err != nil {
		panic(err)
	}

	agent, err := golem.New[struct{}, string](client,
		golem.DecodeFunc[string](func(_ context.Context, r model.Response) (string, error) {
			return r.Message.Content, nil
		}),
	)
	if err != nil {
		panic(err)
	}

	result, err := agent.Run(context.Background(), golem.RunContext[struct{}]{}, "Why is Go ideal for AI agents?")
	if err != nil {
		panic(err)
	}

	fmt.Println(result.Output)
	fmt.Printf("Tokens: %d input, %d output\n", result.Usage.InputTokens, result.Usage.OutputTokens)
}

2. Typed Tools with Dependency Injection

Golem tools are strongly typed and receive dependencies via RunContext[Deps]. No global state, no untyped maps:

type Database struct {
	Users map[int]string
}

// Declare a tool typed to Database dependencies
getUser := tool.MustNew(tool.Tool[Database]{
	Name:        "get_user",
	Description: "Look up a user name by their ID.",
	Schema: json.RawMessage(`{
		"type": "object",
		"properties": {"id": {"type": "integer"}},
		"required": ["id"]
	}`),
	Exec: func(ctx context.Context, db Database, args json.RawMessage) (tool.Result, error) {
		var input struct {
			ID int `json:"id"`
		}
		if err := json.Unmarshal(args, &input); err != nil {
			return tool.Result{}, err
		}
		name, ok := db.Users[input.ID]
		if !ok {
			return tool.Text("User not found"), nil
		}
		return tool.Text(name), nil
	},
})

// Create an agent parameterized with Database dependencies
agent, err := golem.New[Database, string](client,
	golem.DecodeFunc[string](func(_ context.Context, r model.Response) (string, error) {
		return r.Message.Content, nil
	}),
	golem.WithTools[Database, string](getUser),
)

// Run passing the typed dependency instance
db := Database{Users: map[int]string{42: "Alice"}}
result, err := agent.Run(ctx, golem.RunContext[Database]{Deps: db}, "Who is user 42?")

3. Structured Output & Schema Validation

Guarantee your agent returns strongly-typed Go structs with golem.DecodeJSON[T]() and strict schema enforcement:

type WeatherReport struct {
	City        string  `json:"city"`
	Temperature float64 `json:"temperature_celsius"`
	Condition   string  `json:"condition"`
}

agent, err := golem.New[struct{}, WeatherReport](client,
	golem.DecodeJSON[WeatherReport](),
	golem.WithOutputSchema[struct{}, WeatherReport](json.RawMessage(`{
		"type": "object",
		"properties": {
			"city": {"type": "string"},
			"temperature_celsius": {"type": "number"},
			"condition": {"type": "string"}
		},
		"required": ["city", "temperature_celsius", "condition"],
		"additionalProperties": false
	}`)),
)

result, err := agent.Run(ctx, golem.RunContext[struct{}]{}, "Forecast for Lagos, Nigeria.")
fmt.Printf("%s: %.1f°C (%s)\n", result.Output.City, result.Output.Temperature, result.Output.Condition)

---

Supported Providers

Golem ships with standard-library-only adapters for all major frontier and open-weight models:

---

Batteries-Included Tools

Golem includes pre-built common tools written entirely in pure Go:

---

Testing Without a Provider

Never mock HTTP endpoints or pay for tokens in unit tests. Golem includes testmodel, a fully deterministic, offline model implementation:

package main

import (
	"context"
	"testing"

	"github.com/abubakarsiddik31/golem"
	"github.com/abubakarsiddik31/golem/model"
	"github.com/abubakarsiddik31/golem/testmodel"
)

func TestAgent(t *testing.T) {
	client := testmodel.New().Respond(
		model.Response{Message: model.Message{Role: model.RoleAssistant, Content: "pong"}},
	)

	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(context.Background(), golem.RunContext[struct{}]{}, "ping")
	if err != nil || result.Output != "pong" {
		t.Fatalf("unexpected result: %v, output: %s", err, result.Output)
	}
}

---

Documentation

The feature guides provide complete references for each capability and mirror the published documentation site at abubakarsiddik31.github.io/golem.

Design records live in docs/adr/; each guide links the ADR that decided its behavior.

---

Examples

Runnable programs live in examples/; provider-backed examples read their API key from the environment and exit cleanly with instructions when unset.

To run any example:

# Run with OpenAI
OPENAI_API_KEY=sk-... go run ./examples/minimal

# Run locally with Ollama or LM Studio
GOLEM_LOCAL_BASE_URL=http://localhost:11434/v1 go run ./examples/local-models

# Run offline examples (no credentials needed)
go run ./examples/testing-without-a-provider
go run ./examples/pdf-extract
go run ./examples/deferred-tools
go run ./examples/partial-evidence

---

Package Structure

golem/        Agent configuration and typed run API
model/        Provider-neutral model request/response contract
tool/         Tool declarations and execution contracts
mcp/          Model Context Protocol client (stdio & streaming HTTP)
pdfextract/   Common tool: layout-aware PDF parser (tables, images, text)
docextract/   Common tool: Word, Excel, PowerPoint, CSV, and Markdown extractor
webfetch/     Common tool: fetch a URL as agent-readable text
fileread/     Common tool: read a file as agent-readable text
shell/        Common tool: run one command, return combined output
skills/       Common tool: standard SKILL.md folder progressive loader
providers/    Stdlib-only adapters implementing model.Model
testmodel/    Deterministic in-memory model doubles for unit testing
internal/     Execution runner loop and private mechanics
examples/     Runnable programs per capability
docs/guides/  Feature guides (source of truth for behavior)
docs/adr/     Decisions that shape public contracts

---

Status & Roadmap

Golem is currently at v0.8.5.

The core execution contract is frozen and verified with continuous race-detector CI, memory fuzzing, and deterministic offline tests. The public API adheres strictly to additive-only changes on the road to v1.0.0.

• Resilient Execution: Self-correction loops (ModelRetry), fallback models, exponential backoff, per-tool timeouts, in-tool cancellation (tool.Canceled), and partial evidence preservation (RunError.Partial).
• Comprehensive Multimodal: Text, images, PDF documents, audio, and video inputs mapped natively across all model adapters.
• Observability & Durability: Normalized conversation messages, durable additive JSON serialization, reasoning/thinking token capture with provider signatures, and streamable run events.
• Production Guardrails: Pre-send token estimation, token-budgeted history truncation, client-side untrusted history sanitization (SanitizeHistory), history repair (NormalizeHistory), and user-configurable cost/token bounding.
• Rich Tool Ecosystem: First-class Model Context Protocol (MCP) client over stdio and HTTP, layout-aware PDF extraction, multi-format doc parsing, sandboxed shell execution, SSR web fetch, and progressive Agent Skills loading.
• Zero Dependencies: Built exclusively on the Go standard library.

For architecture rationale, read the foundation brief. For upcoming milestones, read the development roadmap.

---

Development

Run the test suite and verification checks:

go test ./...
go test -race ./...
go vet ./...

The feature guides publish as the official documentation site; preview it locally with mkdocs serve (see docs/website.md). Brand assets and guidelines live in assets/brand/.

---

Community & Contributing

Golem is an open-source project and actively welcomes community contributions!

• Good First Issues — approachable issues scoped for newcomers
• Roadmap to v1.0.0 — roadmap progress, open items, and design decisions
• GitHub Discussions — ask questions, share architectures, and propose RFCs
• Contributing Guide — instructions for setting up, running checks, and submitting changes
• Security Policy — guidelines for privately reporting vulnerabilities
• Code of Conduct — standards for participation

---

License

Released under the MIT License.