Agent 的工具执行器如何实现？

核心回答

工具执行器是把模型提出的调用转换成可控、可观测的实际操作的运行时组件。它接收工具名、调用ID和参数，完成注册表查找、参数及权限校验、调度、执行、结果规范化，再将观察返回Agent；模型本身不直接执行后端函数。

在Coding Agent里，执行器可能承接文件读写、命令、测试或远程工具。它与模型循环分开，便于统一处理超时、并发、取消和恢复，而不是在每个Prompt里重复写错误处理。

核心内部结构

工具注册表保存稳定名称、参数Schema、执行适配器、资源范围、超时和结果契约。适配器可以调用本地函数、子进程或远程服务，执行器不应把模型生成的任意名称直接当成程序或类加载。

调用解析与校验先确认完整消息。流式参数应按调用标识累积，等边界完整后解析，再检查类型、必填项、枚举与业务语义。模型参数不覆盖可信身份、工作目录和访问范围，Schema合法也不等于路径或对象可访问。

执行调度根据依赖、资源和动作性质决定串行或并行，设置并发上限、超时及取消信号。命令执行优先使用明确参数与受限环境；需要shell时应明确其语义，不能简单拼接未校验输入。文件操作规范化路径，并处理符号链接等实际访问边界。

结果归一化返回调用ID、状态、数据、错误类型和产物引用，区分空结果、失败、取消和仍在运行。大日志只返回摘要与可回查位置，保留退出码和关键异常；不能只截最后一行再丢掉失败原因。

错误与恢复怎样做

参数错误交回模型修正，权限错误或未知工具不能伪装成正常空结果；临时网络错误可以有限退避重试。超时后进程是否真正停止、远程动作是否已完成需要单独确认。

读操作通常较容易重试，写文件、提交业务操作或发送消息要有幂等设计或结果核对。工具执行成功但状态落盘失败时，恢复应依据调用记录、产物和业务结果判断，避免盲目再次执行。任务取消也应清理子进程和关联资源，而不只是停止前端显示。

怎样观察和验证

每次调用关联任务、步骤与Trace，记录排队、开始、结束、工具版本、结果状态和耗时；敏感参数做必要处理。由此区分模型没发起调用、等待资源、工具卡住与结果回传失败。

验证未知工具、非法参数、路径越界、超时、部分输出、取消、并行冲突和恢复重放。工具层“兜底”指这些明确职责，不能解释为执行器可以擅自猜参数、绕过失败或保证所有调用成功。技术亮点是以统一契约承接不同工具，并让副作用和失败状态可追踪、可恢复。

对应教程

参考资料