工具系统实践与注意事项

适用版本：v4.0.8.2

1. 入口选择图

如何阅读这张图

• generate_tool_command() 是正式入口，因为它明确表达“只规划、不执行”。
• must_call() / async_must_call() 仍能工作，但应理解为兼容层，不应继续作为新设计的中心。

2. 协议稳定性优先

• 新代码统一输出 next_action + execution_commands[]
• execution_commands[*].todo_suggestion 不要省略
• 不要把 tool_commands 当主字段继续写进新系统

3. 规划与执行分层

• 规划器负责“决定做什么”
• 执行器负责“真正调用工具”
• 最终回复再消费 action_results

这能显著降低循环失控和日志不可审计的问题。

4. generate_tool_command() 的定位

generate_tool_command() 是正式的“只规划不执行”入口，适用于：

• 外部审批
• 自定义执行沙箱
• 多系统编排

must_call() / async_must_call() 仅保留兼容意义。

5. Browse 的正确定位

Browse 返回的是“可读文本证据”，不是最终答案本身。

推荐链路：

1. Search 找候选来源
2. Browse 读取正文
3. 模型基于正文回答
4. 最终回复引用证据或 URL

6. 安全边界

• Cmd 这类高风险工具必须做 allowlist
• 对外部写操作不要只依赖模型自律
• 对 Browse、Search 的返回结果做长度和异常检查

7. 并发与超时

• 先保守设置 max_rounds=3~5
• 外部依赖不稳定时，把 concurrency 设低
• Browse 走 Playwright 时，超时和资源占用都更高

8. 观测与排障

优先检查：

• extra.tool_logs
• 每条记录的 success
• error
• todo_suggestion

若需要调试完整链路，可开启：

• runtime.show_tool_logs

9. Daily News Collector 的经验

Agently-Daily-News-Collector 在 v4.0.8.2 中默认开启 BROWSE.enable_playwright: true，因为新闻站点经常需要浏览器渲染后才能得到稳定正文。

这说明一个实践原则：

• 对动态网页，优先把 Browse 当多 backend 读取器使用
• 不要再把 Playwright/PyAutoGUI 当独立业务工具体系设计