zclaw_openfang/docs/references/deerflow-toolcall-reference.md

DeerFlow 工具调用系统参考文档

调研 DeerFlow 的工具调用完整流程，为 ZCLAW 工具调用问题排查提供参考。 分析日期：2026-04-24

---

一、端到端数据流

用户消息
  → FastAPI Gateway (/api/threads/{id}/runs/stream)
    → services.start_run() → asyncio.create_task(run_agent(...))
      → LangGraph Agent Graph (create_agent)
        → LLM Model (ChatOpenAI / Claude)
          → AIMessage (含 tool_calls 列表)
            → 14 层 Middleware 链处理
              → ToolNode (LangGraph 内置, 按 tool_call.name 路由)
                → ToolMessage (执行结果)
                  → 再次调用 LLM (带着 ToolMessage 继续)
                    → StreamBridge.publish() → asyncio.Queue
                      → SSE → 前端 useStream hook
                        → React 组件渲染

二、工具注册与执行

2.1 注册入口

文件: G:/deerflow/backend/packages/harness/deerflow/tools/tools.py — get_available_tools()

工具来自四个来源：

来源	加载方式	示例
Config 工具	YAML 配置 + 反射导入 (module:variable)	deerflow.sandbox.tools:bash_tool
Builtin 工具	硬编码导入	present_file_tool, ask_clarification_tool
MCP 工具	MultiServerMCPClient 从 MCP 服务器缓存获取	第三方 MCP 工具
ACP 工具	build_invoke_acp_agent_tool() 动态构建	外部 agent 调用

2.2 Sandbox 工具清单

文件: G:/deerflow/backend/packages/harness/deerflow/sandbox/tools.py

工具名	功能
bash	沙箱中执行命令
ls	列出目录
read_file	读取文件
write_file	写入文件（触发产物面板自动打开）
str_replace	字符串替换（触发产物面板自动打开）

2.3 Builtin 工具

文件: G:/deerflow/backend/packages/harness/deerflow/tools/builtins/

工具	功能
ask_clarification	向用户提问澄清（中断执行等待回复）
present_file	展示文件给用户（触发产物卡片）
setup_agent	自定义 agent 创建
task_tool	子 agent 任务委派
view_image	图片查看（仅视觉模型）
tool_search	延迟工具搜索（MCP 工具按需暴露）

三、中间件链（14 层）

文件: G:/deerflow/backend/packages/harness/deerflow/agents/lead_agent/agent.py — _build_middlewares()

与工具调用相关的关键中间件：

3.1 DanglingToolCallMiddleware

文件: dangling_tool_call_middleware.py

在 wrap_model_call 中检测消息历史中缺失 ToolMessage 的 AIMessage，自动注入占位 ToolMessage：

ToolMessage(
    content="[Tool call was interrupted and did not return a result.]",
    tool_call_id=tc_id,
    name=tc.get("name", "unknown"),
    status="error",
)

3.2 ToolErrorHandlingMiddleware

文件: tool_error_handling_middleware.py

在 wrap_tool_call 中捕获工具执行异常，转换为错误 ToolMessage 而非让整个 run 崩溃。

3.3 LoopDetectionMiddleware

文件: loop_detection_middleware.py

在 after_model 中检测重复工具调用：

• 阈值 3 次 → 注入警告 HumanMessage
• 阈值 5 次 → 直接清空 tool_calls，强制 LLM 产出文本回答

3.4 DeferredToolFilterMiddleware

文件: deferred_tool_filter_middleware.py

在 wrap_model_call 中过滤延迟注册的 MCP 工具 schema，仅在 LLM 通过 tool_search 发现后才暴露。

3.5 ClarificationMiddleware

拦截 ask_clarification 工具调用，中断执行等待用户回复。

3.6 SubagentLimitMiddleware

截断过多的并行子 agent 调用。

四、工具结果回传

4.1 格式

LangChain 的 ToolMessage，包含：

• content: 执行结果文本
• tool_call_id: 匹配 AIMessage 中的 tool_call ID
• name: 工具名称
• status: "error" 或省略

4.2 特殊工具

present_file_tool 返回 Command 而非纯字符串，同时更新 artifacts 和 messages 两个 state channel。

五、前端工具调用展示

5.1 消息分组

文件: G:/deerflow/frontend/src/core/messages/utils.ts — groupMessages()

分组类型	触发条件	展示
assistant:processing	AI 消息含 tool_calls 或 reasoning	MessageGroup (折叠)
assistant	AI 消息有文本无 tool_calls	MessageListItem (气泡)
assistant:present-files	含 present_files tool call	ArtifactFileList
assistant:clarification	ask_clarification 结果	MarkdownContent
assistant:subagent	含 task tool call	SubtaskCard

5.2 工具状态推断

前端没有显式状态机。通过消息序列推断：

• AI 消息含 tool_calls 但无对应 ToolMessage → 正在执行
• ToolMessage 出现 → 执行完成
• assistant:processing 组由 ChainOfThought 折叠组件包裹

5.3 工具调用 UI

文件: message-group.tsx 第 186-423 行

按工具名渲染不同图标和内容：

• bash → 终端图标 + 命令代码块
• read_file/write_file/str_replace → 文件图标 + 路径链接（点击打开产物面板）
• web_search → 搜索图标 + 结果链接
• 默认 → 扳手图标 + 工具名

六、流式处理中的工具调用

6.1 架构

agent.astream(stream_mode=["values"])
  → StreamBridge (asyncio.Queue per run, maxsize=256)
    → sse_consumer() → SSE frames → 前端

6.2 关键特征

• 工具调用不中断流。LangGraph 自动在 agent_node 和 tool_node 之间路由
• 每次状态变更产出完整的 values 快照，前端通过 seen_ids 去重
• 15 秒心跳包保持 SSE 连接

6.3 前端看到的事件序列

1. values 事件: 含 tool_calls 的 AIMessage
2. values 事件: ToolMessage（工具结果）
3. values 事件: LLM 基于工具结果的最终回答

整个过程连续，不中断 SSE 连接。

七、与 ZCLAW 对比（工具调用）

维度	DeerFlow	ZCLAW
框架	LangGraph (graph-based)	自研 loop_runner (循环)
工具生命周期	LangGraph ToolNode 自动管理	手动 ToolRegistry + loop_runner
after_tool_call 中间件	✅ wrap_tool_call 钩子完整	❌ 流式和非流式模式均未调用
并行工具执行	LangGraph 自动处理	非流式有 JoinSet，流式全串行
悬挂修复	DanglingToolCallMiddleware	DanglingToolMiddleware (有)
错误恢复	ToolErrorHandlingMiddleware (异常→ToolMessage)	ToolErrorMiddleware (计数器)
循环检测	LoopDetectionMiddleware (3次警告/5次强停)	LoopGuardMiddleware (有)
前端状态	消息序列推断	显式 ToolCallStep 状态机
MCP 工具	延迟注册 + tool_search 按需暴露	全量注册

八、关键文件索引

功能	DeerFlow 文件
Agent 工厂	backend/packages/harness/deerflow/agents/lead_agent/agent.py
中间件组装	backend/packages/harness/deerflow/agents/factory.py
工具注册	backend/packages/harness/deerflow/tools/tools.py
Sandbox 工具	backend/packages/harness/deerflow/sandbox/tools.py
Builtin 工具	backend/packages/harness/deerflow/tools/builtins/
错误处理中间件	agents/middlewares/tool_error_handling_middleware.py
悬挂修复中间件	agents/middlewares/dangling_tool_call_middleware.py
循环检测中间件	agents/middlewares/loop_detection_middleware.py
延迟过滤中间件	agents/middlewares/deferred_tool_filter_middleware.py
流式 Bridge	runtime/stream_bridge/memory.py
前端消息分组	frontend/src/core/messages/utils.ts
前端工具调用组件	frontend/src/components/workspace/messages/message-group.tsx