Golem guides¶
Guides are the source of truth for user-facing behavior. Each one covers a capability end to end — purpose, contract, a runnable example, the API surface, and gotchas — and links the ADR that decided it. The README indexes them; it must not drift ahead of them.
New guides start from TEMPLATE.md in this directory (excluded from the
published site). A behavior change is only complete when its guide, its
example, and the README index agree.
Reading order¶
- Getting started — the smallest agent and where everything lives.
- Providers — connecting OpenAI-compatible and Anthropic APIs.
- Embeddings — the text-to-vector port: queries, documents, and usage.
- Retrieval — the search half: an index port, cosine top-k, and the agent's search_documents tool.
- Token counting — pricing a request before it is sent: counters, budgets, pre-send limits.
- Tools and dependencies — typed tools that receive run dependencies.
- Web fetch — the webfetch common tool: URLs as agent-readable text.
- File read — the fileread common tool: workspace files as agent-readable text.
- Command execution — the shell common tool: one command, combined output.
- PDF extract — the pdfextract common tool: PDF documents as structured Markdown with tables and images.
- Document extract — the docextract common tool: Word, Excel, PowerPoint, Markdown, CSV, and multi-format documents.
- Agent skills — the skills common tool: standard SKILL.md folders loaded on demand.
- MCP client — bridging Model Context Protocol servers into agent tools.
- Agent delegation — one agent as another agent's tool.
- Orchestration — multi-agent workflows in plain Go: fan-out, pipeline, router.
- Tool timeouts — context-aware deadlines for individual tool calls.
- Conversations and history — multi-turn runs, durable message JSON, and history trimming.
- Compaction — keeping long conversations bounded: trimming, token budgets, and summarization.
- Sessions — conversations that persist between runs: the
session.Storeport andWithSession. - Multimodal input — images in prompts, per-provider mapping.
- Structured output — declaring the answer shape and decoding it.
- Self-correction — rejection budgets for output and tools.
- Retries — surviving transient model failures and falling back to another model.
- Streaming — fragments as they arrive, same canonical result.
- Run events — observing attempts, tool calls, and corrections as they happen.
- Tracing — spans for runs, provider attempts, and tool calls, through a port an OpenTelemetry SDK implements.
- Thinking — reasoning models: requesting thinking, keeping signatures, replay.
- Usage limits — bounding tokens, requests, and tool calls.
- Cost — user-supplied pricing: Result.Cost and cost bounds.
- Testing without a provider — deterministic fakes and what to assert.
- Deferred tools — pausing a run for approvals or external results, and resuming.
- Tool search — deferred tool loading: keeping a large catalog out of every request.
- Planning — a model-owned task plan behind a small store port.
- Web search — the
websearchcommon tool: a backend port and a keyless DuckDuckGo default. - Content filter — provider safety stops: the default signal and the opt-in typed failure.
- Memory — a persistent, namespaced Markdown notebook behind a store port.
- Prompt context — per-run user-role context from typed deps.
- Loop detection — bounding repeated identical tool calls in one run.
- MCP server — exposing one Golem agent as an MCP tool over stdio or stateless HTTP.