GopherAgent is a Golang multi-agent LLM framework — deterministic ReAct loops, parallel tool execution, streaming, sub-agents, and multi-model routing. Your PM writes a YAML file. Your engineer registers a Go tool. GopherAgent wires them together at runtime — no recompile, no redeploy.
# agent.yaml — your PM creates this
agent:
name: "Customer Support"
system_prompt: |
You are a customer support agent. Look up orders before answering.
Be polite and concise. Escalate billing issues to a human.
tools_required:
- "lookup_order"
- "web_search"// main.go — your engineer writes this once
catalog := builder.NewGlobalCatalog()
catalog.Register(&LookupOrderTool{db: db})
catalog.Register(webSearchTool)
loop, _, _, _ := builder.BuildFromYAML("agent.yaml", catalog, provider, nil)
loop.RunIteration(ctx, sessionKey, userMessage)That's it. Change the YAML, get a different agent. No code changes.
go get github.com/hung12ct/gopheragent- YAML-defined agents — file or
//go:embed, with knowledge-base injection. - Skills with progressive disclosure — an Agent Skills
loader over any
io/fs.FS; descriptions sit in the prompt, full instructions load only when a skill is used. - Deterministic ReAct loop — dependency-aware parallel tool scheduling with
<output_of:ID>refs, anti-loop detection, token-budget-aware pruning. - Streaming & HITL — SSE streaming, human approvals, plan mode, self-critique.
- Custom tools — one interface, schema derived from a Go struct; a middleware chain for logging, timing, rate limiting, and tracing.
- Multi-provider — OpenAI, Anthropic, Gemini, Vertex, and OpenAI-compatible backends, each in its own subpackage; multi-model routing; sampling controls.
- Sub-agents & async — sub-agent streaming, conversation forking, background workers, first-class task tracking.
- Cross-session memory — a post-session consolidator distills transcripts into notes the loader prepends to future sessions.
- Observability — OpenTelemetry traces + metrics (one trace per turn, nested LLM/tool spans, GenAI-convention token metrics), zero-cost when off.
- Evaluation — grade trajectory + answer + HITL with
pkg/evaland a CI-readygopherevalsCLI.
| Guide | Use it for |
|---|---|
| Getting started | Install, the YAML builder, persistent sessions |
| Tools | Built-in tools, writing custom tools, middleware |
| Skills | Progressive disclosure — catalog in the prompt, instructions on demand |
| Permissions & HITL | Confirmation gates, permission DSL, autonomous approvals |
| Providers | Providers, multi-model routing, sampling, multimodal |
| Observability | OpenTelemetry traces & metrics, collectors, debugging a conversation |
| Evaluation | Grade an agent with pkg/eval + gopherevals |
Full API reference: pkg.go.dev.
| Example | What it shows |
|---|---|
examples/demo |
Full chat UI — web research, memory sidebar, Python execution, live HITL, SSE streaming, OTLP export |
examples/agent_eval |
Agent evaluation — trajectory + answer + judge graders, JUnit/Markdown reports, CI gate |
examples/creative_studio |
AI Creative Director — DALL-E 3 images + Veo 2 video clips generated inline |
examples/media_chat |
Media Q&A — upload image/video/doc, native multimodal history, multi-turn references |
examples/hitl_server |
Human-in-the-loop approvals over HTTP (async bridge) |
examples/yaml_agents |
Multiple YAML-defined agents sharing a catalog, plus a skills-driven assistant |
cd examples/demo
printf "LLM_PROVIDER=openai\nOPENAI_API_KEY=sk-...\n" > .env
go run .
# open http://localhost:8888Apache 2.0