用 Go 手撸 Agent 框架 第10篇：用自己的 Runtime，做一个研究助手

这个系列不是从“怎么设计一个 Agent 框架”开始的。

第 1 篇时，我们甚至还不确定 Agent 里除了模型还有什么。后来才一步步接触到模型调用、ReAct、工具契约、上下文窗口和外部知识。

每向前走一步，新问题才会出现。

模型会说话以后，我们想让它使用工具；工具多了，开始关心契约和分发；对话变长以后，才碰到上下文预算；到第 8 篇，这些认识才被放进一条可以完整运行的 loop。

第 9 篇又遇到了新问题：如果再写一个 Agent，模型适配、工具分发和执行循环都要复制。我们这才尝试把重复部分收成 Runtime。

第 9 篇结束时，Runtime 已经能运行天气和计算器。但它是不是真的可以复用，不能只看接口名字。最直接的办法，是拿它再做一个不同的应用。

这一次，我们来做研究助手。

先让它完成一次研究

这一次，我们给 Runtime 换一个更真实的任务。

用户输入一个话题后，研究助手需要自己完成几件事：

1. 想出搜索关键词。
2. 搜索互联网。
3. 挑选值得读的网页。
4. 读取网页正文。
5. 信息不足就继续搜索。
6. 信息够了就整理成报告，并列出来源。

天气和计算器通常一两次工具调用就能得到结果，研究任务却不一样。它可能要反复搜索、阅读和判断，最后还要把找到的资料整理成一份能读的报告。

虽然任务变了，最底下的执行过程没有变：模型决定是否调用工具，本地执行工具，结果回填给模型，模型再继续判断。

因此这一篇继续使用第 9 篇的 Agent.Run，把注意力放在研究任务新增的工具和规则上。

这次需要新增什么

先看目录：

 复制代码10-research-agent/
  main.go
  progress.go
  tools/
    search.go
    readweb.go
    calculator.goagent/
  agent.go
  provider.go
  tool.go
  memory.go

agent/ 还是上一章的共享 Runtime。

和第 9 篇相比，这次新增的是：

• search：根据关键词搜索互联网。
• read_webpage：读取指定网页并提取文本。
• 一个适合研究任务的 system prompt。
• 一个把每轮模型请求和工具调用打印到终端的 consoleTracer。
• 一段把 provider、工具、memory 和 Runtime 组装起来的 main.go。

天气 Agent 和研究助手的业务能力不同，但都可以沿用同一条执行循环。变化放在 10-research-agent，第 9 篇保留它当时已经跑通的实现。

第一个工具：搜索

研究任务不能只靠模型记忆。模型需要先找到资料。

天气工具根据城市返回天气，计算器根据表达式返回结果。研究任务不一样，我们事先不知道答案藏在哪个网站，所以需要一个能根据关键词寻找资料的工具。

同一个 search 可以查 Go 版本，也可以查数据库文档。它提供的不是某个领域的答案，而是一种寻找公开信息的方式。

搜索有很多接法：直接请求搜索页并解析 HTML，使用搜索引擎官方 API，或者使用返回结构化数据的第三方服务。

这一版使用 Serper。它是一个搜索 API 服务：我们把关键词发给它，它返回标题、链接和摘要等结构化结果。这样就不用先把精力花在解析搜索页面上。

在代码里，Serper 被包在 SearchTool.Execute 内部。模型看到的仍然只是一个名叫 search 的工具，Agent.Run 里也没有出现 Serper。看到这里，我才更具体地理解了“工具”这一层在做什么：它把一个外部服务，整理成了模型能够调用的能力。

工具接收一个 query，返回标题、链接和摘要：

 复制代码type SearchTool struct {
    agent.BaseTool
    APIKey string
}func (t *SearchTool) Definition() agent.ToolDefinition {
    return agent.ToolDefinition{
        Name:        "search",
        Description: "搜索互联网上的信息。返回相关网页的标题、URL 和摘要。适用于查找事实、新闻、技术文档等",
        InputSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "query": map[string]any{
                    "type":        "string",
                    "description": "搜索关键词，如 Go 1.22 新特性",
                },
            },
            "required": []string{"query"},
        },
    }
}

模型看到的是这份定义。它知道有一个名叫 search 的工具，也知道调用时必须提供 query。

HTTP 请求发生在 Execute。它先解析 query，再组装 Serper 请求，最后把结果整理成模型容易读的文本。这部分包含完整的 HTTP 错误处理，直接看配套代码中的 tools/search.go。

真实代码还处理了几个很普通、但不能省略的问题：

• 没有配置 SERPER_API_KEY 时直接报错。
• 搜索关键词为空时不发送请求。
• HTTP 客户端设置 10 秒超时。
• 非 2xx 响应不能当成正常结果解析。
• 没搜到内容时，明确告诉模型换一组关键词。

这些处理和普通 HTTP 客户端没有什么区别。不同的是，请求失败后，错误不会直接结束整条研究流程，而是作为工具结果回到上下文。模型下一轮还能看到这次失败，再决定是换关键词、换来源，还是说明资料不足。

第二个工具：读网页

搜索摘要只能帮我们判断一个链接值不值得打开。要写报告，还得读正文。

read_webpage 接收 URL，发起 HTTP 请求，再从 HTML 中提取文本：

 复制代码type ReadWebTool struct {
    agent.BaseTool
}func (t *ReadWebTool) Definition() agent.ToolDefinition {
    return agent.ToolDefinition{
        Name:        "read_webpage",
        Description: "读取指定 URL 的网页内容，提取正文文本。适用于深入阅读搜索结果中的链接",
        InputSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "url": map[string]any{
                    "type":        "string",
                    "description": "网页 URL，如 2",
                },
            },
            "required": []string{"url"},
        },
    }
}

这段实现故意保持简单：

• 请求超时是 10 秒。
• 最多读取 1 MB 响应。
• 去掉 HTML 标签、script 和 style 内容。
• 返给模型的文本最多保留 8000 个字符。

看完这段实现，它能做什么、不能做什么也比较清楚了。它只是请求一份 HTML，再做简单的文本清理；如果正文需要 JavaScript 执行后才出现，或者网站拒绝普通 HTTP 请求，它就读不到。导航栏、推荐列表这些杂项，也可能混进返回结果。

这一篇先拿这个简单版本跑一次，看看模型拿到搜索结果后，能不能继续选择链接、读取内容，再根据新信息作出下一步判断。

前面学过 RAG，这里正好复习一下两者的区别：

这里没有提前建立文档索引，只是临时读取一个 URL，再把文本放进当前上下文。RAG 还需要文档切分、索引，以及根据问题进行检索和召回。

计算器为什么还留着

研究助手里仍然注册了 calculate。

不是每个问题都会用到它。但当任务涉及比例、增长率或简单数据核对时，与其让模型心算，不如把表达式交给确定性的代码。

这也说明工具不是一条写死的流水线：

 复制代码search -> read_webpage -> calculate

不代表每次都必须按这个顺序执行。

代码里没有规定 search、read_webpage 和 calculate 的固定顺序。每一轮都是模型根据当前上下文选择工具；问题不需要计算时，calculate 就不会被调用。

无论模型选择哪一个工具，底下运行的仍然是第 8、9 篇写过的 loop。

工具有了，模型还不知道怎么做研究

三个工具只说明“能做什么”，没有说明“这次任务应该怎么做”。

system prompt 是每次模型请求都会携带的任务说明。它比当前用户问题更早告诉模型：你扮演什么角色、应该遵守哪些规则、最终要交付什么。

只写一句“你是研究助手”，并没有说明什么时候搜索、什么时候打开原文，也没有说明资料不足时该怎么办。工具已经准备好了，还需要把这次任务的步骤写清楚，于是有了下面这段 system prompt：

 复制代码收到话题后，先分析搜索关键词
使用 search 查找候选资料
对重要链接使用 read_webpage 读取正文
资料不足时更换关键词继续搜索
整理报告时列出来源

完整内容在配套代码的 researchSystemPrompt 中。它还规定了报告格式，并提醒模型优先阅读官方资料，不要把搜索摘要直接当成已经核实的事实。

system prompt 仍然是一段交给模型阅读的文字，不是 Go 代码里的固定分支。模型会结合当前问题、工具结果和这段说明，决定下一步做什么。

第一次运行，我只看到了开始和完成

工具和 prompt 准备好后，我先运行了一次。终端里只有两行过程日志：

 复制代码[Agent] 开始处理: 查一下 Go 1.22 对 for 循环变量做了什么修改……
[Agent] 完成 (耗时 18.6s, 输入 14451 token, 输出 1320 token)

报告确实出来了，但搜索了什么、打开了哪个网页、调用了几轮模型，全都看不见。

顺着日志找到 LoggingMiddleware，原因就清楚了：它先打印“开始”，然后调用一次完整的 Agent.Run，等整条 loop 结束后再打印“完成”。它包住了整次运行，却没有进入 loop 内部。

 复制代码fmt.Printf("[Agent] 开始处理: %sn", req.Message)
resp, err := next.Run(ctx, req)
fmt.Printf("[Agent] 完成 ...n")

不过，Agent.Run 执行每一轮时，本来就知道这些信息：

• 第几轮请求模型；
• 模型返回最终回答，还是要求调用工具；
• 调用了哪个工具，参数是什么；
• 工具是否成功、执行了多久、返回多少内容。

这些是程序真实发生的执行事件，不是模型没有输出的内部思考。我们可以把它们打印出来。

因此这一篇增加了一个很小的 consoleTracer。它接收 Runtime 发出的事件，再转换成读者容易看懂的终端日志。下面是其中最主要的打印代码：

 复制代码func (t *consoleTracer) Record(_ context.Context, event agent.TraceEvent) error {
    switch event.Type {
    case "model_request":
        _, err := fmt.Fprintf(t.w,
            "[Agent] 第 %d 轮：请求模型（%d 条消息，%d 个可用工具）n",
            event.Iteration,
            metadataInt(event.Metadata, "message_count"),
            metadataInt(event.Metadata, "tool_count"),
        )
        return err
    case "model_response":
        result := "返回最终回答"
        switch event.StopReason {
        case "tool_use":
            result = "决定调用工具"
        case "max_tokens":
            result = "输出达到 token 上限"
        }
        _, err := fmt.Fprintf(t.w,
            "[Agent] 第 %d 轮：模型%s（耗时 %dms，输入 %d token，输出 %d token）n",
            event.Iteration,
            result,
            event.DurationMS,
            event.InputTokens,
            event.OutputTokens,
        )
        return err
    case "tool_call":
        input, _ := event.Metadata["input"].(string)
        _, err := fmt.Fprintf(t.w,
            "[Tool] 调用 %s，参数：%sn",
            event.ToolName, singleLine(input),
        )
        return err
    case "tool_result":
        _, err := fmt.Fprintf(t.w,
            "[Tool] %s 完成（耗时 %dms，返回 %d 字节）n",
            event.ToolName,
            event.DurationMS,
            metadataInt(event.Metadata, "result_len"),
        )
        return err
    default:
        return nil
    }
}

为了先看清主线，上面的片段省略了工具失败和 max_tokens 分支；它们也在完整的 progress.go 中。工具参数最多打印 240 个字符并压成一行；网页正文只记录返回长度，不把几千字内容全部刷到终端。这样既能看清执行路径，也不会让真正重要的步骤被大段网页文本淹没。

把现成的 Runtime 组装起来

工具和任务规则准备好后，再到 main.go 里把它们组装起来：

 复制代码provider := agent.NewDeepSeekProvider(
    os.Getenv("DEEPSEEK_API_KEY"),
)registry := agent.NewToolRegistry()
if err := registry.Register(&tools.SearchTool{
    APIKey: os.Getenv("SERPER_API_KEY"),
}); err != nil {
    fmt.Printf("注册搜索工具失败: %vn", err)
    return
}
if err := registry.Register(&tools.ReadWebTool{}); err != nil {
    fmt.Printf("注册网页读取工具失败: %vn", err)
    return
}
if err := registry.Register(&tools.CalculateTool{}); err != nil {
    fmt.Printf("注册计算工具失败: %vn", err)
    return
}researchAgent := agent.NewAgent(provider,
    agent.WithToolRegistry(registry),
    agent.WithSystemPrompt(researchSystemPrompt),
    agent.WithTracer(newConsoleTracer(os.Stdout)),
    agent.WithMemory(agent.NewSummaryMemory(
        agent.NewTruncationMemory(provider, 150000),
        provider,
    )),
    agent.WithMaxIterations(8),
    agent.WithMaxTokens(8192),
    agent.WithMiddleware(agent.LoggingMiddleware()),
)

这一段看起来配置很多，实际可以分成五部分：

• 模型：DeepSeekProvider。
• 能力：注册 search、read_webpage 和 calculate。
• 任务说明：researchSystemPrompt。
• 过程记录：consoleTracer 打印每一轮模型请求和工具调用。
• 运行控制：上下文压缩、最多 8 轮模型判断和整次任务的开始、结束日志。

组装完成后，CLI 只需要把用户输入交给 Agent.Run。

到这里可以第一次具体看见复用发生在哪里：研究助手换了工具和任务说明，却没有再复制“调用模型、执行工具、回填结果、继续判断”这条循环。

跑起来

进入配套代码目录：

 复制代码cd 10-research-agent

在 .env 中配置：

 复制代码DEEPSEEK_API_KEY=...
SERPER_API_KEY=...

DEEPSEEK_API_KEY 用于调用模型。SERPER_API_KEY 用于调用搜索服务，可以在 Serper 官网 注册并从控制台复制。

Serper 只是这一版选择的搜索服务，不要从名称相近的第三方网站申请 Key。

然后运行：

 复制代码go run .

启动后会看到：

 复制代码研究助手 - 输入话题开始研究（每次输入一行，输入 quit 退出）

当前 CLI 按回车就会提交一次，所以一个完整问题要放在同一行。可以先输入：

 复制代码查一下 Go 1.22 对 for 循环变量做了什么修改，为什么这个修改能减少 goroutine 闭包里的常见错误。请优先引用 Go 官方资料。

一次正常运行大致会经历：

 复制代码用户提出研究问题
  -> 模型调用 search
  -> 本地返回搜索结果
  -> 模型选择官方文档并调用 read_webpage
  -> 本地返回网页文本
  -> 模型判断资料是否够用
  -> 输出带来源的报告

具体搜索词、工具调用次数和最终措辞不会每次相同。

现在这些步骤不再只是文章里的流程图。运行过程中会看到类似下面的日志：

 复制代码[Agent] 开始处理: 查一下 Go 1.22 对 for 循环变量做了什么修改……
[Agent] 第 1 轮：请求模型（1 条消息，3 个可用工具）
[Agent] 第 1 轮：模型决定调用工具（耗时 816ms，输入 632 token，输出 32 token）
[Tool] 调用 search，参数：{"query":"Go 1.22 for loop variable change official"}
[Tool] search 完成（耗时 521ms，返回 1846 字节）
[Agent] 第 2 轮：请求模型（3 条消息，3 个可用工具）
[Agent] 第 2 轮：模型决定调用工具（耗时 704ms，输入 1210 token，输出 48 token）
[Tool] 调用 read_webpage，参数：{"url":"https://go.dev/doc/go1.22"}
[Tool] read_webpage 完成（耗时 263ms，返回 8014 字节）
[Agent] 第 3 轮：请求模型（5 条消息，3 个可用工具）
[Agent] 第 3 轮：模型返回最终回答（耗时 1350ms，输入 3962 token，输出 860 token）
[Agent] 完成 (耗时 3.9s, 输入 5804 token, 输出 940 token)

开头和结尾仍然来自 LoggingMiddleware，中间每一轮来自刚加上的 consoleTracer。现在可以从日志里确认：模型先搜索，看到搜索结果后选择了 Go 官方文档，再读取网页，最后才返回报告。

日志里的“模型决定调用工具”不代表我们看到了模型隐藏的思考过程。程序真正收到的是一个结构化的 tool_use 响应；日志只是把这个可以观察到的动作打印出来。同样，“模型返回最终回答”表示这一轮没有继续请求工具，而是返回了文本。

上面是一份示例输出。耗时、token 数、轮数、搜索关键词和读取的网页每次都可能不同，应当以自己终端里实际打印的内容为准。

它为什么听得懂“这个修改”

第一轮报告出来后，我继续输入：

 复制代码这个修改对 Go 1.21 编译出来的旧代码有影响吗？

单独看这句话，“这个修改”指什么并不清楚。但研究助手知道我们刚才讨论的是 Go 1.22 的循环变量变化。

这正好复习第 5 篇讲过的短期记忆。模型 API 并没有在服务端替我们记住上一轮。真正保存历史的是 CLI 里的这个变量：

 复制代码var history []agent.Message

第一次调用 Agent.Run 时，history 还是空的：

 复制代码resp, err := researchAgent.Run(context.Background(), agent.Request{
    Message: input,
    History: history,
})

研究完成后，resp.History 里已经有了这一轮产生的全部消息。CLI 把它保存下来：

 复制代码history = resp.History

这里的“一轮”不只是用户问题和最终报告。按照前面的示例，它还包含搜索和读取网页时产生的工具消息：

 复制代码1. user：研究 Go 1.22 的循环变量修改
2. assistant：调用 search
3. tool result：搜索结果
4. assistant：调用 read_webpage
5. tool result：网页正文
6. assistant：最终研究报告

第二次输入时，这 6 条历史消息又通过 Request.History 传进 Agent.Run，新的问题追加在后面。这时上下文远没有达到压缩阈值，所以模型实际看到的是 7 条消息。

为了让这件事也能从终端里看出来，CLI 现在会打印历史消息数量。两次提问连起来，大致是这样：

 复制代码> 查一下 Go 1.22 对 for 循环变量做了什么修改……
[Agent] 开始处理: 查一下 Go 1.22 对 for 循环变量做了什么修改……
...
[Agent] 完成 (...)
[Session] 本轮结束，当前会话保存 6 条历史消息> 这个修改对 Go 1.21 编译出来的旧代码有影响吗？
[Session] 本轮带入 6 条历史消息
[Agent] 开始处理: 这个修改对 Go 1.21 编译出来的旧代码有影响吗？
[Agent] 第 1 轮：请求模型（7 条消息，3 个可用工具）
...

实际数字取决于第一轮调用了几次工具。这个例子没有触发压缩，所以第二轮日志能直接看见历史消息被原样带了进来。模型能理解“这个修改”，不是因为它自己保留了上一轮状态，而是因为我们的 Go 程序把那几张“聊天纸条”又递给了它。

现在也能把两个容易混在一起的名字分开了：

• history 保存当前 CLI 会话中的消息，让前后两次提问能够关联。
• SummaryMemory 在这些消息接近 token 上限时压缩较早内容，避免上下文继续变长。

这两部分都属于短期上下文管理。退出程序后，history 这个内存变量就没有了；当前代码没有把会话写进文件或数据库，也不是一个能跨程序启动记住用户偏好的长期记忆系统。

跑完以后，我才看见复用发生在哪里

现在可以把两个应用放在一起看：

 复制代码09-agent-runtime
  天气工具 + 计算工具
  固定问题演示10-research-agent
  搜索工具 + 网页读取工具 + 计算工具
  连续研究与追问共享
  Message
  ModelProvider
  ToolRegistry
  Memory
  Agent.Run

天气 Agent 和研究助手使用了同一个 Agent.Run。第 10 篇新增的是工具、system prompt 和 CLI 组装，没有重新写执行循环。

写第 9 篇时，“复用 Runtime”还只是一个想法。现在研究助手真的跑出了报告，我才看见这个复用具体发生在哪里：任务从天气查询变成了资料研究，底下那条 loop 仍然可以继续工作。

再看这一篇新增的代码，search 是我们自己接入 Serper 写成的，read_webpage 也是我们自己实现的。于是新的疑问出现了：如果下一个任务要访问 GitHub、数据库或浏览器，难道还要继续逐个写工具？

回到整条学习路线

研究助手不是突然出现的新项目，也不是一开始就设计好的终点。

从第 1 篇开始，这条路线一直在往前走：先弄清模型如何工作，再尝试 ReAct 循环；有了循环后接入工具，工具能用后又碰到上下文和外部知识问题。第 8 篇把这些理解收进一个最小 Agent，第 9 篇再尝试解决复用问题。

第 10 篇只是当前这一步：把天气工具换成搜索和网页读取，用一个新的任务检查 Runtime 是否真的可以复用。

这一版能运行，也能完成一次小型研究，但它仍然只是我们目前学到这里写出的版本。

它底下跑着的，仍然是前面一步步写出来的 loop：

 复制代码模型决定
  -> 本地执行
  -> 结果回填
  -> 再次决定

写到这里，我现在最想继续弄清楚的，是刚才那个越来越具体的问题：通用 Agent 的工具究竟从哪里来？