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.
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
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.
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.
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.
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 substringDesign decisions.
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.
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.
Replaceable infrastructure
Applications choose models, tracing, storage, and transport through narrow interfaces, so no vendor is hard-wired.
A small public API
Additive changes only until v1. The foundation brief gates every new public abstraction.
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.