🤖 gollem：Go 语言里的生产级 Agent 框架深度解析

gollem —— GO for Large LanguagE Model，一个用 Go 语言编写、面向生产环境的 LLM Agent 框架。

一、故事化开头：为什么又是一个 Agent 框架？

想象一个场景：你的运维团队要在 Go 微服务里接入 AI 助手。团队里没人会用 Python，于是 Python 生态里那套 LangChain / LlamaIndex / CrewAI 全部成了摆设——要么放弃 Go 架构，要么硬把 Agent 服务拆成一个独立的 Python 进程，再通过 RPC 缝合。这条缝补起来有多痛，做过架构改造的人都懂：多一套部署、多一套依赖、多一套协议转换、多一套监控。

gollem（名称是 GO for Large LanguagE Model 的缩写，致敬《最后形成的恐龙》DOOM 里的 GOLLEM）就是为这个痛点而生：让 Go 工程师在原生语言里，用最地道的 Go 方式构建能调用工具、会自己规划、能被观测的 Agent 应用。

它出自日本开发者 m-mizutani 之手。熟悉 Go 生态的人对他不会陌生——goerr/v2（错误处理库）、gt（测试断言库）、jsonex 都是他的作品。作者自嘲"写得慢，所以东西造得慢"，但这个项目从 2025 年 4 月立项，到 2026 年 10 月已经迭代到 v0.30.0，几乎每一两周一个 release，是目前 Go 生态里迭代最勤奋的 Agent 框架之一。

二、背景科普：Agent 框架的三个世代

要理解 gollem 的设计取舍，得先看清 Agent 框架的演进脉络：

第一世代（2023）：链式编排。LangChain 早期那种 LLMChain → PromptTemplate → OutputParser 的线性流水线，本质是把调用过程写死在代码里。可一旦模型需要"根据中间结果决定下一步"，开发者就得手工拆成一堆 if-else，代码迅速腐化。

第二世代（2024）：自主 Agent。ReAct、Function Calling、工具循环（tool loop）成为主流，模型自己决定调用哪个工具、传什么参数。TypeScript 的 Vercel AI SDK、Python 的 LangGraph 都属于这一代。开发者第一次能把"业务逻辑"部分交给模型，但也第一次尝到了"模型不一定听话"的苦。

第三世代（2025-2026）：生产化 Agent。这一代框架要回答的不再是"能不能跑通 Demo"，而是：

• 上下文窗口满了怎么办？（记忆压缩）
• 一次调用烧了多少钱？（Token 成本与缓存观测）
• 出了错谁负责？（Trace 与可观测性）
• 模型输出的 JSON 不合法怎么办？（Schema 校验与自动修复）
• 能不能在生产环境安全地跑？（Guardrails、权限中间件）

gollem 从第一天起就按第三世代的标准来设计。这在 Go 生态里是罕见的——大多数 Go Agent 库还停留在第二世代，把"能调通 API"当作终点。

三、类比解释：gollem 是什么角色？

如果把构建 Agent 想象成开一家餐厅：

• LLM Provider（OpenAI/Claude/Gemini/Ollama） 是食材供应商。你不关心食材从哪个农场来，只关心菜单上能点什么。
• Session（会话） 是餐桌。系统提示词、对话历史、工具定义都是摆在这张桌上的东西。你不必每次点菜都重新介绍一遍自己。
• Tool（工具） 是后厨的灶台。客人（模型）说要"炒个菜"，灶台就负责执行。Tool 可以是自己写的 Go 函数，也可以通过 MCP 接入外部服务。
• Middleware（中间件） 是餐厅的安检与监控摄像头。你可以决定"这道菜不外带""这道菜要先拍张照片留档"。
• Strategy（策略） 是厨师的工作流程。单次执行就是"照单做菜"（simple），ReAct 是"尝一口再决定"（react），Plan Mode 是"先写菜谱再逐步执行"（planexec），Reflexion 是"做完自我复盘重做一遍"（reflexion）。
• Trace（追踪） 是整店的监控录像，能回放每一次下单、每一次炒菜、每一次客人反馈。

gollem 的价值在于：它把这套"餐厅"的骨架搭好了，你只负责写灶台和菜单。

四、核心功能：50+ 能力的 Go 实现

4.1 统一 LLM 接口与四家 Provider

gollem 提供统一的 LLMClient 接口，屏蔽了四家厂商的差异：

Provider	目录	亮点
OpenAI	llm/openai	GPT / o-series，兼容 Chat Completions 与 Responses API
Anthropic Claude	llm/claude	直连 API，也支持经 Google Vertex AI 调用 Claude
Google Gemini	llm/gemini	基于官方 google.golang.org/genai SDK
Ollama	llm/ollama	本地、远程 Ollama 服务器、Ollama Cloud 三种形态

接口层只暴露 Generate / Stream / GenerateEmbedding 三件事，切换厂商只是换一个 client 实例——这正是 Go 里最朴素也最可靠的抽象。

4.2 类型安全的工具定义

type SearchTool struct{}

func (t *SearchTool) Spec() gollem.ToolSpec {
    return gollem.ToolSpec{
        Name:        "search",
        Description: "Search the database",
        Parameters: map[string]*gollem.Parameter{
            "query": {Type: gollem.TypeString, Description: "Search query"},
        },
    }
}

func (t *SearchTool) Run(ctx context.Context, args map[string]any) (map[string]any, error) {
    return map[string]any{"results": doSearch(args["query"].(string))}, nil
}

工具即普通 Go 类型，参数通过 Parameter 声明，配合框架的 schema 转换器生成 JSON Schema 交给模型。与 Python 生态里用装饰器或 Pydantic 声明工具相比，Go 的写法更啰嗦一点，但换来的是编译期类型检查。

4.3 MCP 原生支持

mcpClient, _ := mcp.NewStdio(ctx, "./mcp-server", []string{})
agent := gollem.New(client,
    gollem.WithTools(&SearchTool{}),
    gollem.WithToolSets(mcpClient),
)

MCP（Model Context Protocol）已成为 AI 工具生态的事实标准。gollem 内置 mcp 包，支持 stdio 与 Streamable HTTP 两种传输，WithToolSets 可以同时挂载内置工具和外部 MCP 工具服务器。这是它区别于许多 Go Agent 库的关键一点——MCP 不是事后补丁，而是一等公民。

4.4 结构化输出与泛型查询

这是 gollem 最见功力的一处设计：

type UserProfile struct {
    Name  string `json:"name" description:"User's full name"`
    Age   int    `json:"age" description:"Age in years"`
    Email string `json:"email" description:"Email address"`
}

result, _ := gollem.Query[UserProfile](ctx, client, "Extract: John, 30, john@example.com",
    gollem.WithQuerySystemPrompt("You are a data extractor."),
)
// result.Data 是 *UserProfile —— 类型安全，已解析

Query[T]() 把 schema 生成、会话创建、LLM 调用、JSON 解析合并成一次泛型调用，解析失败自动重试。SessionQuery[T]() 则在保留对话历史的前提下做结构化查询。用泛型把"LLM 返回不确定 JSON"这个最大的工程痛点，压缩成了编译期就能保证类型安全的普通 Go 调用——这一点在 Go Agent 框架里几乎是独一份。

4.5 四种执行策略

策略	目录	适用场景
simple	strategy/simple	一次性问答，无工具循环
react	strategy/react	经典"思考-行动-观察"循环
planexec	strategy/planexec	Plan-Execute 架构：先规划、再逐步执行、每步反思
reflexion	strategy/reflexion	生成-评估-反思-重试，带记忆的自我改进

planexec 的 Plan Mode 文档写得相当扎实，它把传统单轮交互的缺陷讲得很清楚："分析日志找错误"这类任务，如果日志格式和预期不符，第一版计划就会崩；反思环节允许模型在发现新事实后动态调整计划，甚至跳过已完成步骤直接收敛。

4.6 记忆压缩与 Token 成本治理

middleware/compacter 负责在上下文超限前自动压缩历史。更实用的是 Prompt Caching 支持——gollem 能在所有 Provider 上观测缓存命中情况（CacheReadInputToken / CacheCreationInputToken），并针对 Claude 主动写入缓存断点：在 system prompt、tools、以及对话尾部三处打 cache_control 标记。系统提示和工具定义跨轮稳定，首轮之后即为缓存命中；对话尾部断点随对话推进前移，每轮只对新增 token 付全价。

这个细节看似微小，但对长上下文 Agent 循环来说是直接的成本杠杆。多数框架到 v0.30 还没做这一层。

4.7 可观测性

trace 包提供统一的 trace 接口，实现在 trace/logger（日志）和 trace/otel（OpenTelemetry）。配合 go.opentelemetry.io/otel 依赖，可以直接接入现有的 APM 体系。此外还有 trace/as_child_agent.go——支持把子 Agent 的 trace 挂到父 Agent 下，这在多 Agent 场景里至关重要。

4.8 多模态与中间件

图片和 PDF 可以与文本一起作为输入（gollem.NewImage / gollem.NewPDFFromReader）。中间件体系分三类：ContentBlockMiddleware（同步生成）、ContentStreamMiddleware（流式生成）、ToolMiddleware（工具执行），全部是标准的 handler 包装模式，pre/post 处理对称，非常容易上手。工具中间件里做权限校验是最典型的用法。

五、上手门槛：CLI 还是 WebUI？

gollem 是纯库（library），不是应用。它没有 Dockerfile、没有 docker-compose、没有 Web UI、没有 CLI 二进制——因为它不是用来"部署"的，而是用来"被集成"的。

三条典型路径：

1. 库集成（主要方式）：go get github.com/gollem-dev/gollem，在业务代码里 gollem.New(client, ...)。前置条件是 Go 1.26+（go.mod 要求 go 1.26.0）和至少一个 LLM API Key。
2. 示例工程：examples/ 目录有 11 个可运行示例——basic、chat（交互式命令行聊天）、embedding、history、json_schema、mcp、query、reflexion、simple、subagent_middleware、tools。克隆仓库后 go run ./examples/chat 就能跑通一个多轮对话终端。
3. 自建服务：想要 Web 界面就得自己拿 golang.org/x/net 或标准库 net/http 套一层，仓库里没有现成的 HTTP handler（contrib/ 的 HTTP 适配器在另一个仓库 fugue-labs/gollem 里）。

上手成本评估：Go 工程师（熟悉 Go 生态）约 30 分钟跑通 hello world；Python 工程师转 Go 需要 1-2 天熟悉语法与接口设计。真正的门槛不在代码，而在 API Key 成本与对模型行为的调优经验。

六、争议与局限：不回避的问题

1. 生态位拥挤。 搜索"Go Agent 框架"会同时看到 fugue-labs/gollem（另一个同名项目，主打 Agent[T] 泛型与 50+ 原语，37★）、以及大量 Python 移植版。两个同名项目共存会造成认知混淆，gollem-dev/gollem 的星数更高但两者并非同一代码库。

2. v0.x 的稳定性。 最新版本 v0.30.0，仍是 0.x 语义，API 仍可能破坏性变更。README 与文档对"哪些稳定、哪些在演进"的区分做得不如 fugue-labs 版本清晰。

3. Go 版本门槛偏高。 要求 Go 1.26.0，这是相当新的版本要求，团队内如果有老版本构建环境需要升级。注意 go.mod 里大量依赖标注为 indirect 且版本号相当激进（如 google.golang.org/genai v1.53.0），依赖树稳定性值得留意。

4. 无 Web UI / 无开箱即用形态。 相比 Claude Code SDK、OpenAI Agents SDK 等自带交互式 CLI 的方案，gollem 更"底层"——你得到的是零件，不是整机。对于快速验证想法的团队，缺少一个开箱即用的 demo 界面是个摩擦点。

5. 贡献者规模小。 仓库贡献者仅 4 人左右，虽有 gosec、trivy、golangci-lint、完整性校验等五条 CI 工作流，质量门禁相当严格，但巴士因子偏低。维护者 m-mizutani 同时是 goerr、gt、jsonex 的作者，精力分散风险存在。

6. 组织与仓库时间线存疑。 仓库创建于 2025-04-19，但 gollem-dev 这个 GitHub 组织创建于 2026-06-12，且组织内公开仓库仅 5 个。这通常意味着项目是从个人仓库迁移到组织名下，迁移过程中 star 数与 issue 历史的连续性需要留意。

七、行业意义：Go 生态的 AI 缺位与填补

Go 长期是云原生与后端服务的主力语言，却在 AI 应用层明显缺席——这让大量 Go 团队不得不依赖 Python 微服务。gollem 代表了三种填补路径中最"原生"的一种：不跨语言，直接把 Agent 能力做进 Go 的类型系统和并发模型。

它选择的路子有几个明显信号：

• 泛型承载类型安全。Query[T]、SessionQuery[T] 是把 Python 世界里靠 Pydantic + 运行时校验解决的问题，搬到 Go 的编译期。这是 Go 生态独有的语言优势，gollem 用得比较到位。
• 以"生产化"为第一目标。Prompt Cache 观测、成本统计、Trace、Guardrail、Compacter——这些在 Python 框架里也是近年才补齐的能力，gollem 从架构初期就预留了位置。
• MCP 一等公民。在 MCP 成为工具调用事实标准的 2026 年，一个 Go 框架把 MCP 写进核心 API 而非插件，意味着作者对生态趋势有准确判断。

从发布节奏看（2025-04 到 2026-10 近 30 个 release，平均一两周一次），这是一个仍在快速演进、方向明确、有真实工程经验支撑的项目。星数（200★）在 Go Agent 框架中属于头部，与 Python 生态动辄数万星不可同日而语，但考虑到 Go 语言的开发者基数和迁移门槛，这个数字已经相当不错。

给决策者的建议：如果你的后端主体是 Go、需要 Agent 有明确的类型契约、需要深度集成现有 OpenTelemetry 监控、并且团队不打算引入 Python——gollem 是当前 Go 生态里工程完成度最高的选择，值得进入技术预研。但如果团队需要开箱即用的 Web 界面、快速 Demo，或需要 Python 生态里那 90% 的现成模型封装与社区工具，Python 侧的选择仍然更省心。

八、技术画像速览

维度	结论
主语言	Go（177 万行字符，100% Go）
许可证	Apache-2.0
核心依赖	anthropic-sdk-go、go-openai、google genai、modelcontextprotocol/go-sdk、otel
架构风格	接口抽象 + 策略模式（strategy）+ 中间件链（middleware）
测试情况	单测文件与源码近乎 1:1（gollem_test.go 63KB、subagent_test.go 51KB、schema_test.go 34KB），含跨厂商消息往返测试数据集
CI 门禁	gosec（安全扫描）、trivy（漏洞扫描）、golangci-lint（静态检查）、测试、完整性校验
可观测性	trace/logger + trace/otel，内置 OpenTelemetry 依赖
版本状态	v0.30.0（2026-10-03），仍在 0.x
活跃度	最后提交 2026-10-24，issue 仅 2 个开放