接收模型的工具调用决策

模型接收到请求后，会进行意图判断与工具选择：

场景	模型响应	后续动作
需要外部工具	返回 JSON 格式的工具调用指令（包含工具名称与入参）	进入步骤 3，执行工具
无需外部工具	返回 自然语言格式的直接回复	流程结束，直接呈现给用户

模型在此阶段扮演"决策者"角色，它只生成调用指令，并不实际执行工具。

在应用端执行工具

应用程序接收到 JSON 指令后，进入工具执行层：

• 解析指令中的工具名称与参数
• 在应用端（或沙箱环境）运行对应工具
• 捕获工具输出结果（成功返回数据，或失败返回错误信息）

第二次模型调用

获取工具输出后，应用程序需要将结果回注上下文，再次发起模型调用。此时的消息序列（Messages）结构为：

[用户问题] → [模型工具调用指令] → [工具执行结果]

这相当于告诉模型："你刚才要求执行的操作已完成，这是结果，请基于这些信息继续推理。"

---

接收模型的最终响应

模型整合以下信息进行最终推理：

• 原始用户问题
• 工具输出结果
• 中间推理过程（Chain-of-Thought）

最终生成自然语言格式的回复，直接呈现给用户，完成整个交互闭环。

---

流程本质总结

轮次	角色	动作
第一轮	模型	决策（是否需要工具）+ 规划（调用哪个工具）
应用端	应用	执行（实际运行工具）
第二轮	模型	整合（基于结果生成回复）

我们从 GitHub - shareAI-lab/claw0: 0 - 1 learn OpenClaw: sections to build an claw-AI agent from scratch · GitHub 的文档中也可以窥见端倪。

工具 = 数据 (schema) + 处理函数映射表. 模型选一个名字, 你查表执行.

• TOOLS: JSON schema 字典列表, 告诉模型有哪些工具可用.
• TOOL_HANDLERS: dict[str, Callable], 将工具名映射到 Python 函数.
• process_tool_call(): 字典查找 + **kwargs 分发.
• 内层循环: 模型可能连续调用多个工具, 然后才生成文本.
• 工具结果放在 user 消息中 (Anthropic API 的要求).

    User Input
        |
        v
    messages[] --> LLM API (tools=TOOLS)
                       |
                  stop_reason?
                  /          \
            "end_turn"    "tool_use"
               |              |
             Print    for each tool_use block:
                        TOOL_HANDLERS[name](**input)
                              |
                        tool_result
                              |
                        messages[] <-- {role:"user", content:[tool_result]}
                              |
                        back to LLM --> may chain more tools
                                          or "end_turn" --> Print

0x02 核心代码作用与特色总结

Nanobot Agent 工具系统的核心实现包括：

• Tool抽象基类：
  • 定义了 Agent 工具的标准化接口规范（名称、描述、参数 Schema、执行逻辑），提供通用的参数校验能力（基于 JSON Schema）和 OpenAI 函数 Schema 转换能力，是所有自定义工具的 “模板”，保证了工具体系的一致性和可扩展性。
  • 所有工具只需实现指定抽象方法即可接入 Agent，无需修改核心逻辑，同时基类内置通用能力（参数校验、Schema 转换），减少重复开发。
• ExecTool工具类：
  • 基于Tool基类实现的具体工具，为 Agent 提供安全可控的 Shell 命令执行能力，支持超时控制、工作目录限制、危险命令拦截、路径遍历防护、工作目录限制、允许列表等安全机制，既满足 Agent 与系统交互的核心需求，又规避了 Shell 执行的典型安全风险。

具体如下图所示。

0x03 实现

3.1 整体逻辑关系图

架构图如下：

工具调用流程如下：

3.2 TOOLS.md

TOOLS.md 是本地工具提示。脚本存放在哪里，哪些命令可用。这样 Agent 就不需要去猜，而是确切知道。AGENTS.md 定义行为流程，TOOLS.md 定义能力边界。简单说，它是智能体的"工具箱说明书"，告诉智能体可以使用哪些工具、怎么用、什么时候用。

# Tool Usage Notes

Tool signatures are provided automatically via function calling.
This file documents non-obvious constraints and usage pat