模块 4 / 10

工具系统 (Tools)

Agent 的"双手"——通过工具操作终端、文件、浏览器和网络，把想法变成行动。

预计阅读时间：15 分钟

📑 本模块目录

什么是 Hermes 工具？
内置工具全景
Toolsets —— 按需组合
自定义工具开发
安全机制
常见疑问

1 什么是 Hermes 工具？

工具（Tool）是 Agent 和外部世界交互的唯一通道。没有工具，Agent 只能"想"不能"做"。有了工具，它才能读写文件、执行命令、搜索网络、操作浏览器。

每个工具本质上是：一个 Python 函数 + 一个 JSON Schema（告诉 LLM 怎么调用）。当 LLM 返回 tool call 时，Hermes 根据 Schema 找到对应函数，传入参数，执行后把结果追加回上下文。

flowchart LR A["LLM 返回 Tool Call"] --> B["Hermes 解析
函数名 + 参数"] B --> C["执行 Python 函数"] C --> D["结果 JSON 序列化"] D --> E["追加到 messages"] E --> A

📌 要点

工具是 Agent 的行动能力来源
每个工具 = 函数 + JSON Schema
LLM 决定调用哪个工具、传什么参数

2 内置工具全景

类别	工具	功能
文件	`read_file`	读取文件内容（带行号）
	`write_file`	写入/覆盖文件
	`patch`	精准查找替换（比 sed 可靠）
	`search_files`	搜索文件内容或文件名（ripgrep）
终端	`terminal`	执行 Shell 命令（前后台）
	`process`	管理后台进程
	`execute_code`	Python 沙箱执行
浏览器	`browser_navigate`	打开网页
	`browser_click`	点击元素
	`browser_type`	输入文本
	`browser_snapshot`	获取页面文本快照
	`browser_vision`	截图分析
网络	`web_search`	网络搜索
网络	`web_extract`	提取网页内容
会话	`memory`	持久记忆 CRUD
	`session_search`	搜索历史会话
	`todo`	任务列表管理
协作	`delegate_task`	派生子 Agent
协作	`cronjob`	定时任务管理

3 Toolsets —— 按需组合

不用的工具不要启用——减少 System Prompt 长度，让 LLM 更聚焦

Hermes 把工具按功能分成 Toolsets（工具组）。你可以按需启用/禁用：

# 交互式管理
hermes tools

# 命令行
hermes tools list
hermes tools enable browser
hermes tools disable image_gen

Toolset	包含的能力
`terminal`	Shell 命令、进程管理
`file`	文件读写搜索
`browser`	浏览器自动化
`web`	网络搜索、内容提取
`vision`	图片分析
`memory`	持久记忆
`delegation`	子 Agent 委托
`cronjob`	定时任务
`feishu_doc`	飞书文档
`feishu_drive`	飞书云盘

⚠ 改动后需要 /reset：Toolsets 在会话启动时加载，修改后需要新会话生效。这是为了保护 Prompt Caching。

4 自定义工具开发

3 个文件，10 分钟搞定一个自己的工具

步骤 1：创建 tools/your_tool.py

import json, os

from tools.registry import registry

def check_requirements() -> bool:

    return bool(os.getenv("YOUR_API_KEY"))

def your_tool(param: str) -> str:

    return json.dumps({"success": True, "data": param})

# 注册到系统

registry.register(

    name="your_tool",

    toolset="custom",

    schema={"name": "your_tool", "description": "...", "parameters": {}},

    handler=lambda args, **kw: your_tool(args.get("param")),

    check_fn=check_requirements,

    requires_env=["YOUR_API_KEY"],
)

步骤 2：加到 toolsets.py 的 _HERMES_CORE_TOOLS 列表。

步骤 3：/reset 新会话即可使用。

💡 工具自动发现：tools/*.py 中任何含 registry.register() 的文件都会被自动导入——不需要手动维护导入列表。

5 安全机制

🛡 命令审批

approvals.mode: manual（默认）——危险命令（rm -rf / git reset --hard）弹确认。smart 用 LLM 判断风险。off 跳过。

🔒 Secret 脱敏

工具输出中的 API Key / Token 自动替换为 [REDACTED]。默认开启，可在 config 关闭。

🔐 .env 隔离

密钥不放 config.yaml，单独存 .env。.env 不入 git。

6 常见疑问

Q: 工具太多会不会让 LLM 混乱？

会。所以用 Toolsets 按需启用。只给当前任务需要的工具，LLM 决策更精准。

Q: 自定义工具能调外部 API 吗？

可以。在 handler 函数里做 HTTP 请求即可。记得用 check_fn 检查 API Key 是否存在。

Q: 怎么确认工具加载成功了？

hermes tools list 看状态。或者在新会话中直接让 Agent 用这个工具，看是否出现在 tool call 中。

← 模块 3：系统提示词与人格模块 5：技能系统 (Skills) →