smhanov/agentloop

If you are building an agent in Go and keep reimplementing the same send-tool-result-repeat loop, agentloop is worth a look before the scaffold grows. It is a small, focused library rather than a platform, and its main value is that the loop and its guardrails are already defined and observable.

The problem

A developer wants a Go program that asks a model a question, executes whatever tools the model requests, feeds results back and stops on a final answer. Doing this by hand means dispatching calls, appending result messages, bounding iterations and aggregating token usage — code that is easy to get subtly wrong and tedious to repeat per agent. agentloop changes that step: you define tools and options, call Ask, and get back an Answer containing text, a tool trace and usage. The result is a working loop with a recorded transcript instead of a hand-rolled state machine.

What's different

Provider access is delegated to the sister project llmhub, so the same agent code can target OpenAI, Anthropic, Gemini, Ollama, xAI, OpenRouter, Z.AI or a custom provider without talking to vendor APIs directly (project instructions). The distinctive design choice is the single Hooks struct: logging, tracing, streaming UIs, approval gates, cost caps, steering and context compression are all expressed as hook functions around the loop, and the shipped search and bash presets are built on that same surface. That matters if you expect to add observability or a human-approval step later, because you are extending the run rather than forking an internal loop.

The trade-off is that hooks are synchronous and a returning error aborts the run, apart from a specific skip signal; anything you keep from an event must be copied because the event is only valid during the call (project instructions). It is a compact core with a narrow opinion: every run is bounded by tool-call and step budgets, which is sensible for unattended agents but means long exploratory runs need those ceilings raised consciously. This is not a general graph-orchestration system, and the README does not present it as one.

Who should try it

A good fit is a Go team that wants a search-grounded question-answering agent or a bash-style coding agent and is comfortable owning tool implementations. The included presets and the examples/ask runner give a concrete starting point, and Answer.Tools gives a trace to inspect when a run stops early. A poor fit is someone wanting a language-agnostic platform, a visual workflow builder, or agents in Python or TypeScript; agentloop is a Go library and its API reference is Go-only (API reference). Teams that need every provider's tool-calling quirks handled for them should check llmhub's coverage first, since agentloop inherits that boundary.

Requirements and limitations

Go 1.21 or newer is required, the single dependency is llmhub, and the search preset additionally needs a serper.dev API key at runtime (project instructions, serper). The bash preset has its own caveat: models that struggle with the text-action protocol can produce repeated format errors, and the documented remedy is switching to tool protocol or lowering temperature. Budget exhaustion and duplicate-call stops are normal outcomes, not crashes; the troubleshooting notes point to raising WithMaxToolCalls / WithMaxSteps and checking tool output size. Ongoing upkeep means tuning budgets and watchdog settings per model and keeping the loop's tool results small enough that the model can finish.

HotRepo's take

HotRepo's only dated observation is a 2026-10-27 NEW-REPOSITORY board (新项目榜, not the overall board) placement at #4 with 112 total stars, one day after creation. That sample cannot establish whether interest persists. Given the young age, the practical thing to verify is whether llmhub covers the provider and model you intend to use, since the loop's usefulness depends on that integration.