第六章：工具链与工具集

工具系统概述

Hermes Agent 的核心能力之一是其丰富的工具系统。工具（Tool）是 Agent 与环境交互的桥梁，它决定了 Agent 能够执行哪些操作、如何获取信息以及如何影响外部系统。每个工具都是一个独立的、可调用的功能单元，拥有明确的输入输出接口。

与传统的函数调用不同，Hermes Agent 的工具系统具备以下特性：

• 动态发现：Agent 在运行时自动感知可用工具及其能力边界
• 智能选择：基于当前任务上下文，自主决定调用哪些工具及调用顺序
• 错误恢复：工具调用失败时，Agent 能够分析错误原因并尝试替代方案
• 组合编排：多个工具可以组合成工具集（Toolset），实现更复杂的工作流

内置工具详解

Hermes Agent 内置了四大类核心工具，覆盖了日常开发的大部分场景。

文件系统工具 (Filesystem Tools)

文件系统工具是 Agent 最常用的工具之一，提供了对项目文件的各种操作能力：

// 文件系统工具的典型配置
{
  name: "read_file",
  description: "读取指定文件的内容",
  parameters: {
    type: "object",
    properties: {
      path: { type: "string", description: "文件路径" },
      offset: { type: "number", description: "起始行号" },
      limit: { type: "number", description: "读取行数" }
    },
    required: ["path"]
  }
}

Shell 工具 (Shell Tools)

Shell 工具允许 Agent 在终端中执行命令，这是实现自动化操作的关键：

# Agent 内部执行的 shell 命令示例
npm run build          # 构建项目
python -m pytest       # 运行测试
git log --oneline -5   # 查看最近提交
docker compose up -d   # 启动服务

Git 工具 (Git Tools)

Git 工具封装了常见的版本控制操作，使 Agent 能够自主管理代码版本：

• git_status：查看工作区状态
• git_diff：查看变更内容
• git_commit：创建提交
• git_push：推送至远程
• git_branch：分支管理

网络工具 (Network Tools)

网络工具赋予 Agent 访问外部资源的能力：

工具集（Toolset）概念与组合策略

工具集（Toolset）是 Hermes Agent 中一组相关工具的集合。通过将多个工具组合为一个逻辑单元，工具集可以实现更复杂的任务编排。

工具集的定义方式

# toolset.yaml - 定义一个代码审查工具集
toolsets:
  code_review:
    description: "执行代码审查工作流"
    tools:
      - read_file          # 读取待审查代码
      - search_file        # 搜索特定模式
      - git_diff           # 查看变更内容
    workflow:
      - step: 1
        tool: read_file
        purpose: "获取代码全文"
      - step: 2
        tool: search_file
        purpose: "搜索潜在问题模式"
      - step: 3
        tool: git_diff
        purpose: "对比历史变更"

组合策略

选择工具组合策略时，需要考虑以下因素：

1. 任务复杂度：简单任务使用单一工具即可，复杂任务需要工具链协作
2. 依赖关系：某些工具的输出可能是另一些工具的输入
3. 并行度：无依赖的工具可以并行调用以提升效率
4. 容错性：关键任务应配备备选工具

工具选择规则：Agent 如何决定用什么工具

Hermes Agent 的工具选择机制是一个多阶段决策过程：

1. 意图分析：Agent 首先分析用户请求的意图，确定需要完成的核心目标
2. 能力匹配：将目标与各工具的描述进行语义匹配，生成候选工具列表
3. 上下文评估：考虑当前环境状态（如工作目录、是否在 Git 仓库中）
4. 优先级排序：根据工具的效率、安全性和历史成功率进行排序
5. 执行与反馈：调用选定工具，根据返回结果决定下一步操作

// 工具选择决策逻辑（伪代码）
function selectTools(task: Task): Tool[] {
  const intent = analyzeIntent(task.description);
  const candidates = toolRegistry.matchByIntent(intent);
  const filtered = applyContextFilters(candidates);
  return rankByPriority(filtered);
}

自定义工具开发接口

Hermes Agent 提供了标准的工具开发接口，允许开发者扩展 Agent 的能力边界。自定义工具需要实现以下接口：

from hermes.tool import BaseTool, ToolResult
from pydantic import BaseModel

class MyCustomToolParams(BaseModel):
    query: str
    max_results: int = 10

class MyCustomTool(BaseTool):
    name = "my_custom_tool"
    description = "执行自定义查询操作"
    parameters = MyCustomToolParams

    async def execute(self, params: MyCustomToolParams) -> ToolResult:
        # 实现自定义逻辑
        result = await self._do_query(params.query, params.max_results)
        return ToolResult(success=True, data=result)

实战：编写一个自定义 API 调用工具

下面我们通过一个实际案例来演示如何编写自定义工具。我们将创建一个用于查询 GitHub 仓库统计信息的工具。

from hermes.tool import BaseTool, ToolResult
from pydantic import BaseModel, Field
import httpx

class GitHubStatsParams(BaseModel):
    repo: str = Field(description="仓库名称，格式为 owner/repo")
    include_contributors: bool = Field(
        default=False, description="是否包含贡献者信息"
    )

class GitHubStatsTool(BaseTool):
    name = "github_stats"
    description = "获取 GitHub 仓库的统计信息，包括 Star、Fork、Issue 数量等"
    parameters = GitHubStatsParams

    async def execute(self, params: GitHubStatsParams) -> ToolResult:
        url = f"https://api.github.com/repos/{params.repo}"
        async with httpx.AsyncClient() as client:
            resp = await client.get(url)
            if resp.status_code != 200:
                return ToolResult(
                    success=False,
                    error=f"API 请求失败: {resp.status_code}"
                )
            data = resp.json()
            stats = {
                "stars": data["stargazers_count"],
                "forks": data["forks_count"],
                "open_issues": data["open_issues_count"],
                "language": data["language"],
                "description": data["description"],
            }
            if params.include_contributors:
                contrib_url = data["contributors_url"]
                contrib_resp = await client.get(contrib_url)
                if contrib_resp.status_code == 200:
                    stats["top_contributors"] = [
                        c["login"] for c in contrib_resp.json()[:5]
                    ]
            return ToolResult(success=True, data=stats)

注册自定义工具

# 在配置中注册自定义工具
from hermes import Agent
from my_tools import GitHubStatsTool

agent = Agent(
    tools=[GitHubStatsTool()],
    # ... 其他配置
)

工具安全沙箱配置

工具的执行安全是 Hermes Agent 的重要考量。系统提供了多层级的安全保障：

# .hermes/security.yaml
security:
  # 文件系统访问控制
  filesystem:
    allowed_paths:
      - /workspace/project
      - /tmp/hermes
    denied_paths:
      - /etc
      - /home/*/.ssh
    max_file_size: 10MB

  # 网络访问控制
  network:
    allowed_domains:
      - "*.github.com"
      - "api.openai.com"
      - "pypi.org"
    denied_domains:
      - "*.internal.company.com"
    allow_private_ip: false

  # Shell 执行限制
  shell:
    allowed_commands:
      - npm
      - python
      - git
      - docker
    denied_commands:
      - rm -rf /
      - sudo
    timeout: 60
    max_output_size: 1MB

  # 资源限制
  resources:
    max_memory: 512MB
    max_cpu: 2
    max_disk: 1GB

通过合理配置工具安全沙箱，可以在保证 Agent 功能完整性的同时，有效防范潜在的安全风险。下一章我们将深入讨论沙箱终端与安全机制的实现细节。