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 的猜测？
它的输出是否能被下一步直接使用？
它失败时是否方便排查？

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