08. Tools 源码：工具是怎么注册和调用的

这一篇看哪些文件

工具源码主要在：

backend/packages/harness/deerflow/tools/

建议先看这些文件：

tools.py
types.py
sync.py
mcp_metadata.py
skill_manage_tool.py
builtins/

不要一上来把所有 builtins 都读完。先看工具的结构，再看具体工具。

types.py：先看工具长什么样

types.py 通常会定义工具相关的数据结构。

读源码时先找这些问题：

工具输入怎么描述？
工具输出怎么描述？
是否有 metadata？
错误信息怎么表达？

这比直接看某个工具实现更有效。

tools.py：工具怎么组织

tools.py 通常是工具集合和注册逻辑的核心位置。

你要看：

内置工具在哪里加载
外部工具怎么并入
工具列表如何提供给 Agent

如果以后要加一个自定义 Tool，大概率会从这里找到入口。

builtins：内置工具参考实现

内置工具目录：

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

这里的文件适合作为模板。

例如：

clarification_tool.py
task_tool.py
tool_search.py
view_image_tool.py
present_file_tool.py

读这些工具时，不要只看函数体。重点看它们如何定义参数、如何返回结果、如何把错误交给 Agent。

MCP 工具转换

MCP 不是直接变成 Agent 能用的 Python 函数。

中间需要转换和 metadata 处理。相关文件包括：

mcp_metadata.py
backend/packages/harness/deerflow/mcp/tools.py

这也是为什么 18、19 两篇会单独讲 MCP。

实践：源码定位练习

这次不改代码，只沿着一个内置工具走一遍。建议选择 clarification_tool.py，完成下面几项：

• 在 builtins/ 中找到它的实现；
• 找到工具的名称、输入参数和返回值；
• 回到 tools.py，确认它怎样进入工具集合；
• 找到工具最终提供给 Agent 的位置；
• 记下一个失败或异常分支。

完成标准

不看本文，你仍然能重新说出这条线：

具体工具实现
→ 工具聚合
→ Agent 获得工具列表
→ 模型发起调用
→ 工具结果返回

路径名称不必背，但你要能在仓库里重新找到它们。

多走一步

再选一个实现方式明显不同的工具，例如 view_image_tool.py。比较两个工具的输入、输出和错误处理，写下它们为什么不能共用同一种返回结构。

这一篇你要记住

加工具前，先弄清工具系统的三层：

类型定义
|
注册/聚合
|
具体工具实现

下一篇会动手设计一个给研究型 Agent 用的工具能力。