Hermes Agent 实战指南⑤：工具集成与外部调用，让AI真正能干活

---

5.1 为什么工具集成是Agent的"手脚"

前四篇我们完成了Hermes Agent的安装配置、多Agent协作、记忆系统搭建。但还有一个关键问题：

Agent再聪明，如果不能调用外部工具，也只是"纸上谈兵"。

真正的生产力AI必须能够：

• 调用API获取实时数据
• 执行本地脚本
• 读写数据库
• 操作文件系统

Hermes Agent的工具系统，就是给AI装上"手脚"，让它从"会说话"变成"能干活"。

---

5.2 工具系统的核心架构

Hermes Agent的工具系统基于"工具描述-参数验证-执行反馈"三步闭环：

工具的定义方式

每个工具是一个Python函数，通过装饰器声明其能力：

from hermes import tool

@tool(
    name="get_weather",
    description="获取指定城市的实时天气信息",
    parameters={
        "city": {
            "type": "string",
            "description": "城市名称，如'北京'、'上海'",
            "required": True
        },
        "unit": {
            "type": "string",
            "description": "温度单位，'celsius'或'fahrenheit'",
            "required": False,
            "default": "celsius"
        }
    }
)
def get_weather(city: str, unit: str = "celsius") -> dict:
    """
    调用天气API获取实时天气数据
    """
    import requests
    
    response = requests.get(
        f"https://api.weather.com/v1/current?city={city}&unit={unit}"
    )
    
    if response.status_code == 200:
        data = response.json()
        return {
            "city": city,
            "temperature": data["temp"],
            "condition": data["condition"],
            "humidity": data["humidity"]
        }
    else:
        return {"error": f"获取天气失败: {response.text}"}

---

5.3 内置工具与自定义工具

5.3.1 内置工具

Hermes Agent预置了常用工具：

工具名称	功能	典型场景
web_search	网页搜索	查找信息、新闻
read_file	读取文件	查看文档内容
write_file	写入文件	保存生成内容
execute_code	执行代码	数据分析、计算
send_email	发送邮件	通知、提醒

使用内置工具：

# .hermes/config.yaml
tools:
  builtin:
    - web_search
    - read_file
    - write_file
    - execute_code

5.3.2 自定义工具

创建自定义工具的完整流程：

步骤1：创建工具文件

# .hermes/tools/my_tools.py

from hermes import tool
import requests
import json

@tool(
    name="send_wechat_message",
    description="通过企业微信机器人发送消息通知",
    parameters={
        "webhook_url": {
            "type": "string",
            "description": "企业微信机器人的Webhook地址",
            "required": True
        },
        "message": {
            "type": "string",
            "description": "要发送的消息内容",
            "required": True
        }
    }
)
def send_wechat_message(webhook_url: str, message: str) -> dict:
    """发送企业微信消息"""
    payload = {
        "msgtype": "text",
        "text": {"content": message}
    }
    
    response = requests.post(
        webhook_url,
        data=json.dumps(payload),
        headers={"Content-Type": "application/json"}
    )
    
    return {
        "success": response.status_code == 200,
        "response": response.text
    }

步骤2：注册工具

# .hermes/config.yaml
tools:
  custom:
    - path: ./.hermes/tools/my_tools.py
      enabled: true

步骤3：验证工具可用

# 查看已注册工具
hermes tools list

# 测试工具
hermes tools test --name send_wechat_message 
  --params '{"webhook_url": "https://...", "message": "测试消息"}'

---

5.4 工具调用的高级配置

5.4.1 权限控制

限制工具的执行范围，保护敏感操作：

# .hermes/config.yaml
tools:
  permissions:
    # 只允许访问特定目录
    read_file:
      allowed_paths:
        - ./workspace/
        - ./documents/
    
    # 禁止执行危险命令
    execute_code:
      blocked_commands:
        - "rm -rf"
        - "sudo"
        - "chmod"
    
    # 敏感工具需要人工确认
    send_email:
      require_confirmation: true

5.4.2 超时与重试

# .hermes/config.yaml
tools:
  execution:
    default_timeout: 30  # 默认超时30秒
    
    retry:
      enabled: true
      max_attempts: 3
      backoff: exponential  # 指数退避

5.4.3 结果缓存

对于耗时且结果稳定的工具调用，启用缓存：

# .hermes/config.yaml
tools:
  cache:
    enabled: true
    ttl: 3600  # 缓存有效期1小时
    cache_for:
      - web_search
      - query_database

---

5.5 实战案例：构建公众号发布助手

下面通过一个完整案例，展示如何用Hermes Agent构建公众号发布助手。

需求

1. 从本地Markdown文件读取文章
2. 调用Pexels API获取配图
3. 发布到WordPress站点
4. 发送企业微信通知

使用Agent发布文章

---

5.6 常见问题

Q：工具执行失败会怎样？

Agent会收到错误信息，可以尝试重试或换用其他方案。你可以配置重试策略和备用工具。

Q：如何保护敏感信息（如API密钥）？

使用环境变量存储密钥，不要硬编码在工具文件中：

import os

API_KEY = os.getenv("MY_API_KEY")  # 从环境变量读取

Q：如何调试工具？

使用内置的测试命令：

# 测试单个工具
hermes tools test --name my_tool --params '{"param1": "value1"}'

# 查看工具执行日志
hermes logs --tool my_tool

---

5.7 本讲小结

核心概念	说明
工具定义	通过装饰器声明工具名称、描述、参数
工具注册	在配置文件中启用自定义工具
权限控制	限制工具访问范围，保护敏感操作
超时重试	处理网络不稳定等异常情况
结果缓存	提升响应速度，减少重复调用

核心价值：工具集成让Hermes Agent从"能对话"升级为"能执行"，真正成为生产力助手。

---

5.8 下一讲预告

第6篇将深入讲解 Hermes Agent的部署与监控：如何将Agent部署到服务器、实现7x24运行、监控运行状态、处理异常告警。

---