09. Tools 实战：给研究型 Agent 增加一个工具能力

实战目标

这一篇不追求写一个复杂工具。

目标是设计一个适合研究型 Agent 的工具能力：输入清楚，输出可控，失败时能解释。

可以先做一个“资料摘要清洗工具”：给它一段抓取到的网页正文，让它返回更适合报告使用的结构化片段。

为什么选这个工具

研究型 Agent 最常见的问题不是不会写，而是资料太乱。

搜索结果、网页正文、复制出来的公告，经常混着导航、广告、脚注和重复内容。

如果直接塞给模型，报告很容易变散。

工具输入设计

输入不要太多。

source_url
raw_text
focus_question

这三个就够。

不要一开始设计十几个参数。参数越多，Agent 越容易传错。

工具输出设计

输出也要短。

建议返回：

title
source_url
key_points
evidence_snippets
unknowns

unknowns 很重要。它提醒后续报告不要把不确定信息写成事实。

放在哪里

可以参考内置工具目录：

backend/packages/harness/deerflow/tools/builtins/

真正落地时，要结合工具注册逻辑，把新工具加入 Agent 可用工具列表。

验证方式

不要直接让 Agent 写长报告。

先单独验证工具：

给一段短网页正文
看输出是否稳定
看失败信息是否可读
看 key_points 是否足够短

然后再放进完整任务流。

这一篇你要记住

自定义 Tool 不要追求“万能”。

越窄、越清楚、越容易验证，越适合交给 Agent 调用。

常见坑

第一个坑是把工具做得太大。

比如一个工具同时负责搜索、抓取、摘要、评分、写文件。看起来省事，但 Agent 一旦调用失败，你不知道是哪一步坏了。

更好的方式是拆成几个小工具，每个工具只做一件事。

第二个坑是输出太自由。

工具输出如果是一大段自然语言，后续 Agent 很难稳定使用。尽量返回结构化字段，哪怕只是简单的 JSON-like 文本。

第三个坑是没有失败样例。

工具一定会失败。网页打不开、API 超时、正文为空、权限不足，这些都要有可读的错误信息。

实践：练手小作业

给“资料摘要清洗工具”准备三组固定输入，不急着接入完整 Agent：

样例 A：一段包含标题、正文和广告的正常网页文本
样例 B：空字符串
样例 C：正文很短，无法回答 focus_question

先直接调用工具，再检查输出。

完成标准

• 正常输入能返回 title、key_points、evidence_snippets 和 unknowns；
• key_points 数量受控，不是一整篇改写；
• 每条证据可以回到原文核对；
• 空正文返回可读错误，而不是堆栈；
• 证据不足时写进 unknowns，不编造答案；
• 输出能被下一步直接序列化或写入报告。

完成这些后，再把工具接入现有工具集合，并用同一段材料比较接入前后的报告片段。

多走一步

给输出增加一个 content_hash 或等价的来源标识。重复处理同一份正文时，检查是否能识别重复材料，避免研究报告反复引用同一来源。

做完后怎么判断有价值

一个工具是否值得保留，可以看三个问题：

它是否减少了 Agent 的猜测？
它的输出是否能被下一步直接使用？
它失败时是否方便排查？

如果三个答案都是否定的，这个工具大概率只是增加复杂度。