SAGE Tools: 模块化工具系统介绍

欢迎来到 SAGE Lib 的工具（Tools）模块。该模块提供了一个标准化的框架，用于创建、管理和调用各种原子化的功能单元（即“工具”）。这些工具是 SAGE Agent 实现复杂任务规划与执行能力的基础。

该系统的核心由两部分组成：BaseTool 基类和 ToolRegistry 注册表。

---

1. BaseTool: 工具的基石

BaseTool 是一个抽象基类，为所有具体的工具提供了一个统一的接口和结构。任何希望被 SAGE 系统识别和调用的自定义功能，都应该继承自 BaseTool。

核心设计

• 元数据驱动: 每个工具都通过元数据（Metadata）来声明其身份和能力。这包括：

  • tool_name: 工具的唯一标识符。
  • tool_description: 对工具功能的清晰描述，主要供大语言模型（LLM）理解和选择。
  • input_types / output_type: 明确定义工具的输入输出格式。
  • demo_commands: 提供示例用法，便于人类和机器理解。

• 标准化执行接口: 所有工具都必须实现一个 execute 方法。这是工具执行其核心逻辑的入口点，确保了 Agent 可以用统一的方式调用任何工具。

• LLM 资源声明: 通过 require_llm_engine 属性，工具可以声明其执行是否需要 LLM 的参与。这使得系统可以更高效地分配资源。

如何创建一个工具？

1. 继承 BaseTool: 创建一个新类，并使其继承自 BaseTool。
2. 定义元数据: 在 __init__ 方法中，调用 super().__init__() 并传入工具的名称、描述、输入输出类型等元数据。
3. 实现 execute 方法: 重写 execute 方法，在其中实现工具的具体功能逻辑。

---

2. ToolRegistry: 工具的管理器

ToolRegistry 扮演着工具“注册中心”和“管理器”的角色。它维护了一个所有已注册工具的列表，并提供了一套简单的方法来管理这些工具。

核心功能

• 注册与注销:

  • register(tool): 将一个 BaseTool 的实例添加到注册表中，使其可被系统发现和调用。
  • unregister(name): 从注册表中移除一个工具。

• 查找与列举:

  • get(name): 根据工具名称精确地获取一个工具实例。
  • list_tools(): 返回当前所有已注册工具的列表，这对于 Agent 在规划时“看到”所有可用技能至关重要。

• 全局访问: ToolRegistry 通常作为一个单例存在，确保在系统的任何地方都可以访问到同一份工具列表。

---

总结：工作流程

一个典型的工具使用流程如下：

1. 开发: 开发者通过继承 BaseTool 来创建一个或多个具有特定功能的工具。
2. 注册: 在系统初始化阶段，创建这些工具的实例，并将它们一一注册到全局的 ToolRegistry 中。
3. 发现与调用: 当一个 SAGE Agent 需要执行任务时，它会向 ToolRegistry 查询可用的工具列表。通过分析每个工具的元数据（特别是 tool_description），Agent 会选择最适合当前子任务的工具。
4. 执行: Agent 调用所选工具的 execute 方法，并传入所需的参数，完成任务的一个步骤。

通过这种松耦合、标准化的设计，SAGE 的工具系统实现了极高的灵活性和可扩展性，让开发者可以专注于实现具体的功能，而无需关心底层的调用和管理细节。