Golem · Author & Maintainer

Typed, inspectable agent runs in Go.

A Go framework for building AI agents with typed dependencies and outputs, explicit tools, and inspectable runs, verified by a 19-check live harness.

quick start
client, err := openai.New(openai.Config{
    APIKey: os.Getenv("OPENAI_API_KEY"),
    Model:  "gpt-4o-mini",
})
agent, err := 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(ctx, golem.RunContext[struct{}]{}, "Reply with exactly the word: pong")
Version
v0.8 · additive API
Language
Go 1.26+ · stdlib only
Verification
19 live checks
Providers
OpenAI, Claude, Gemini, Bedrock + local
The contract

What a run returns.

Each call returns the typed output, the full normalized conversation as durable, additive-only JSON (result.Messages), and cumulative token, request, and tool-call usage. Failures return a RunError with an inspectable stage (model, tool, decode, loop, or usage) that preserves the underlying cause for errors.Is and errors.As. To debug a run, you inspect the returned value instead of replaying logs.

Capabilities

What the core covers.

Typed agents & outputs

Generic agents with typed dependencies and decoded, validated results.

Structured output

Schema mode and tool mode, including providers that reject schema and tools in the same request.

Tools with typed dependencies

Explicit tool declarations, forced tool choice, per-tool deadlines.

Ordered parallel execution

Opt-in parallel tool calls that keep deterministic ordering.

Self-correction

Output and tool validation loops with bounded retries.

Fallbacks & retries

Retry with backoff and fallback models per run.

Streaming

Streaming on every adapter, including Bedrock.

Bounded runs

History trimming, token/request/tool-call usage limits.

Multimodal input

Images, PDFs, audio, and video alongside text, mapped natively per adapter.

Agent delegation

Compose agents that call other agents as tools.

MCP client

Bridge external server tools over stdio or streamable HTTP.

Common tools

Web fetch, file read, shell, layout-aware PDF and Office document extraction, and a SKILL.md loader.

Provider adapters: OpenAI-compatible APIs (twelve services), Anthropic, Google Gemini, Azure OpenAI, and AWS Bedrock, plus an MCP client that brings external tool servers into the same typed tool loop.

Verification

A live verification harness.

Every capability above maps to a live check that runs against a real provider (Gemini by default). Offline checks are deterministic and run without an API key; live checks skip when no key is set, and each one reports a clear pass or fail.

verification harness (golem-lab)
go run . verify                  # full live suite
go run . verify --offline-only   # deterministic, no key
go run . verify --list           # catalog all 19 checks
go run . verify structured self-correction   # filter by substring
Design decisions

Design decisions.

01

Compile-time contracts

Typed dependencies and outputs surface errors at build time instead of at runtime. The API is written for Go rather than ported from a Python framework.

02

Explicit over magic

context.Context, explicit error handling, and small interfaces. Model calls, tool execution, iteration limits, and usage are visible in the run result.

03

Replaceable infrastructure

Applications choose models, tracing, storage, and transport through narrow interfaces, so no vendor is hard-wired.

04

A small public API

Additive changes only until v1. The foundation brief gates every new public abstraction.

Get started

Install.

install
go get github.com/abubakarsiddik31/golem

# deterministic offline tests, no API key needed
go test -race ./...

Golem needs Go 1.26.5 or newer and depends only on the Go standard library. Provider adapters are separate imports, so you only pull in the ones you use. Full guides are on the documentation site.