[!info] related notes

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

Tool Runtime

一句话定义

Tool Runtime 是 AI Service 中负责工具执行的运行时环境。它不只是调用函数，而是在调用前后做参数校验、权限检查、沙箱隔离、超时控制、错误处理和结果归一化。

核心原理

执行流程

LLM 输出 tool_call
    │
    ▼
Tool Runtime
    ├─ 1. 查找工具 (ToolRegistry)
    ├─ 2. 参数校验 (JSON Schema)
    ├─ 3. 权限检查
    ├─ 4. 检查已有授权；需要时新增审批
    ├─ 5. 执行 (带超时和沙箱)
    ├─ 6. 结果归一化
    ├─ 7. 错误处理
    └─ 8. 审计记录（拒绝与执行尝试也需记录）
    │
    ▼
返回 ToolResult

控制协议（示意）

在可信入口解析 actor / tenant / run，限制调用输入大小
从受信注册表解析工具与版本；未知工具拒绝
校验参数语法、schema、目标资源、对象权限与当前业务状态
检查已有授权；如确需新增批准，创建绑定操作和版本的请求
为副作用分配稳定逻辑操作标识，持久记录尝试与必要的审批消费
按剩余 deadline 选择受控执行适配器，调用工具
分类成功、失败、取消与结果未知，记录审计事件
归一化筛选后的结果，按上下文预算返回模型

单个 context.approved 布尔值无法证明当前工具、参数、租户和目标版本已经获批。审批绑定与恢复协议见 Approval Workflow，重试的副作用边界见 Tool Idempotency。

Runtime 组织这些控制；Tool Executor承载实际调用。声明 sandbox 字段或用 asyncio.wait_for 包一层，不代表已实现隔离、强制终止或持久审计。

常见坑

1. 不做参数校验: 模型传了非法参数直接崩溃
2. 不做超时控制: 工具执行卡住
3. 不做沙箱隔离: 工具崩溃影响整个 Agent
4. 错误信息太技术化: 模型看不懂错误信息

参考资料

• Tool Calling 工程化
• Tool Executor