GO AGENT 开发指南
用 Go 构建 Agent：从 Loop 到多 Agent 协作
一个能上线的 Agent 不只是一次模型请求。它需要控制循环、验证工具参数、记录可恢复状态，并在多 Agent 场景中明确任务所有权。本文用 Modu 的真实模块边界说明这四层如何组合。
本文适合已经会写 Go、正在评估 Agent 框架或准备从单次 LLM 调用升级到可恢复工作流的开发者。 如果只想先跑起来，请直接看 Modu 快速开始。
01 · ARCHITECTURE
先把 Agent 拆成四层
“Agent 框架”容易被误解为一个模型 SDK。真正困难的部分是：模型决定调用工具之后，谁验证参数、谁 执行副作用、失败后从哪里继续、多个执行者如何交接。把这些职责混在一个函数里，短期代码少，长期却 很难测试和恢复。
pkg/providers 处理协议、流式响应与 Provider 注册，不持有业务状态。
pkg/agent 负责 ReAct 风格循环、工具执行、事件、中断与队列。
pkg/runtime 为已提交消息追加检查点，支持恢复与回退分支。
pkg/mailbox 管理注册、收件箱、任务、项目、验收与会话记录。
应用仍然拥有 Prompt、工具目录、持久化策略和部署。这个边界很重要：框架提供执行机制，不应该替应用 决定业务权限或数据生命周期。
02 · AGENT LOOP
从最小 Agent Loop 开始
先只接一个模型和一个 Prompt，确认 Provider、模型 ID 与事件流都能工作。下面的结构与仓库中的 agent_demo 一致；Ollama 和 LM Studio 可以通过 OpenAI 兼容端点接入。
providers.Register(openai.New(
"ollama",
openai.WithBaseURL("http://localhost:11434/v1"),
))
model := &types.Model{
ID: "llama3.2", Name: "Llama 3.2", ProviderID: "ollama",
}
a := agent.NewAgent(types.Config{
InitialState: &types.State{
SystemPrompt: "你是一个有帮助的助手。",
Model: model,
},
})
err := a.Prompt(context.Background(), "用三句话解释 Modu")
需要自己管理消息状态时，可以直接使用 agent.Loop；需要 Prompt 助手、订阅、队列与中断
状态时，使用 agent.Agent。不要在第一步就引入持久化或多 Agent。
03 · TOOLS
把工具视为受控副作用
工具不是普通函数注册表。每个工具都要提供名称、说明、参数 Schema 和执行方法；循环会在执行前检查
参数。对文件写入、外部 API 或命令执行，还应通过 ApproveTool 明确审批边界。
context.Context，让超时和取消能传递到外部请求。如果工具已经修改外部系统，但结果还没写入会话就发生崩溃，恢复对话并不能撤销副作用。需要“恰好一次” 的操作必须在工具自己的 API 或数据库边界上使用幂等键或事务。
04 · RECOVERY
状态恢复要和业务事务分开
pkg/runtime 在每条已提交消息后写入检查点。进程重启后，Resume 会加载最新
状态并修复没有结果的中断工具调用；Rewind 则把旧检查点作为新的分支头，不删除后续历史。
store, err := runtime.NewFileStore("./checkpoints")
rt := runtime.New(agent.NewAgent(cfg), store, "session-123")
err = rt.Run(ctx, "完成这项任务")
resumed, err := rt.Resume(ctx)
内存 Store 适合测试；FileStore 使用每会话一个追加式 JSONL 文件并在追加后执行
fsync。对数据库或对象存储，实现同一个 Store 接口即可。
05 · MULTI-AGENT
只有任务边界清晰时才增加 Agent
多 Agent 不等于让多个模型自由聊天。先定义谁分派、谁执行、谁验收以及失败后回到哪个状态。Mailbox 本身不调用 LLM，它只维护协调状态，因此可以独立测试任务流转。
mailbox.NewHub() 默认使用进程内状态。需要跨进程恢复任务、项目、角色与对话时，选择
SQLite Store；调用方还要处理收件箱已满、目标不存在和重试策略。
06 · PRODUCTION
上线前检查这七件事
NEXT
用可运行示例验证选型
不要先搭完整平台。按目标选择一个示例，用真实模型端点走通最短链路：
# 单 Agent 与工具调用
go run ./examples/agent_demo
# 检查点、恢复与回退
go run ./examples/runtime_demo
# 协调者驱动的多 Agent 工作
go run ./examples/agent_teams