[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Tool Runtime, Tool Executor

Tool Execution

一句话定义

Tool Execution 是真正执行工具逻辑的过程。在完成参数校验、权限检查后，调用工具的 handler 函数，捕获返回值和异常。

核心原理

执行流程

参数校验通过
    │
    ▼
权限检查通过
    │
    ▼
准备独立可信 context (user_id, session_id)
    │
    ▼
调用 handler
    │
    ├─ 成功 → 返回结果
    ├─ 超时 → 标记等待超时，副作用结果可能未知
    └─ 异常 → 返回错误信息

和执行器的区别

本篇描述一次工具调用的生命周期；Tool Executor描述承载调用的模块及最小适配器。共用示例放在执行器笔记，避免维护两套互相矛盾的身份注入与异步逻辑。

运行时参数来自已认证 context，与模型提供的业务参数分离。执行入口必须覆盖普通调用、重试与恢复；参数或资源版本变化时重新验证授权。同步/异步适配、取消与超时的职责不能靠“调用一下 handler”自动获得。

常见坑

1. 同步 handler 阻塞事件循环：外层异步超时无法及时调度。
2. 直接回传异常原文：数据库连接串或下游响应可能含敏感数据；返回稳定错误类型和筛选后的摘要。
3. 混淆运行时身份与目标 ID：注入 user_id 不能替代对象级权限检查。
4. 超时后直接重做：写操作可能已生效，先确认状态或使用稳定操作标识。

参考资料

• Tool Runtime
• Tool Executor