在实际 AI 应用开发中我们常常面临一个困境云端大模型 API 虽然强大但存在成本、延迟、数据隐私和网络依赖等问题。而完全本地部署的模型在复杂任务规划和工具调用能力上又往往有所欠缺。Hermes Agent 的出现为这个困境提供了一个优雅的折中方案。它本质上是一个智能体框架能够将本地运行的轻量级模型如通过 Ollama 部署的模型与强大的云端模型如 Claude、GPT协同工作并赋予其使用本地工具Skill、管理记忆和进行多轮复杂对话的能力。这使得开发者可以在保护隐私和控制成本的前提下构建出能力接近顶级云端模型的智能应用。本文面向希望深入理解并实践 AI 智能体的开发者。我们将从零开始完成 Hermes Agent 的本地部署深入剖析其会话与记忆的工作原理并手把手教你创建自定义 Skill 来扩展其能力。最终你将获得一个完全在本地运行、可对话、有记忆、能调用工具的智能体系统。1. 理解 Hermes Agent 的核心架构与工作流在动手部署之前必须先理解 Hermes Agent 是如何工作的。这能帮助你在后续配置、调试和扩展时清楚地知道每一步操作影响的是哪个环节。1.1 核心组件模型、技能与记忆Hermes Agent 的架构围绕三个核心概念构建模型Model、技能Skill和记忆Memory。模型Model这是智能体的“大脑”。Hermes Agent 支持混合模型策略。你可以配置一个主模型Primary Model通常是一个强大的云端模型如 Claude 3.5 Sonnet用于复杂的推理和规划。同时配置一个或多个本地模型Local Model例如通过 Ollama 运行的 Llama 3.2、Qwen 2.5 等用于处理对延迟敏感或需要隐私保护的简单任务。Agent 会根据任务复杂度自动路由请求。技能Skill这是智能体的“手和脚”。一个 Skill 就是一个可执行的功能单元例如“查询天气”、“发送邮件”、“执行系统命令”、“搜索文件”。Hermes Agent 自带一些基础 Skill更重要的是它允许你通过编写 Python 函数来轻松创建自定义 Skill从而将任何本地能力如调用内部 API、操作数据库暴露给 Agent。记忆Memory这是智能体的“经验簿”。它使 Agent 能够跨对话轮次记住上下文。记忆不是简单的聊天历史堆叠而是结构化的存储可能包括会话记忆Conversation Memory当前对话的短期上下文。长期记忆Long-term Memory通过向量数据库存储的关键信息片段可供未来检索。技能记忆Skill Memory记录 Skill 的执行历史和结果。1.2 会话工作原理从用户输入到智能响应一次完整的 Hermes Agent 交互其内部工作流可以简化为以下步骤接收输入用户通过 Web UI、API 或命令行提出问题例如“帮我总结一下/home/user/reports目录下所有.txt文件的内容”。上下文组装Agent 从记忆系统中检索与当前问题相关的历史对话和知识片段将用户问题、相关记忆和系统指令拼接成完整的提示词Prompt。规划与路由模型通常是主模型分析提示词判断是否需要调用 Skill、调用哪个 Skill、以及如何组合多个 Skill 来解决问题。例如它可能规划出先调用list_filesSkill 获取文件列表再循环调用read_fileSkill 读取每个文件。技能执行Agent 根据模型的规划按顺序调用相应的Skill。Skill 在本地环境中执行并返回结果如文件列表、文件内容。结果整合与响应生成Agent 将 Skill 执行的结果反馈给模型。模型基于这些结果和原始问题生成最终的自然语言回答例如“已为您总结共有3个文件主要内容是...”。记忆更新此次交互的关键信息如用户意图、使用的技能、产生的结果被结构化后存入记忆系统供未来使用。这个“感知-规划-行动-学习”的循环是 Hermes Agent 实现复杂任务自动化的基础。2. 本地部署 Hermes Agent环境准备与安装我们将在一个干净的 Python 虚拟环境中部署 Hermes Agent。这里以 Linux/macOS 系统为例Windows 用户建议使用 WSL2 以获得最佳体验。2.1 前置条件检查确保你的系统满足以下要求Python 3.10这是 Hermes Agent 的强制要求。pipPython 包管理工具。虚拟环境工具venv或conda。Ollama可选但推荐用于在本地运行轻量级大模型。如果你计划使用本地模型需要先安装并拉取模型。至少 8GB 可用内存运行模型和向量数据库需要一定内存。2.2 创建虚拟环境与安装使用虚拟环境可以避免包依赖冲突。# 1. 创建项目目录并进入 mkdir hermes-agent-project cd hermes-agent-project # 2. 创建 Python 虚拟环境 python3 -m venv venv # 3. 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows (CMD) # venv\Scripts\activate.bat # Windows (PowerShell) # venv\Scripts\Activate.ps1 # 4. 升级 pip pip install --upgrade pip # 5. 安装 Hermes Agent # 使用 pip 从 PyPI 安装核心包 pip install hermes-agent安装完成后可以通过以下命令验证是否安装成功hermes --version # 或 python -m hermes_agent --help2.3 初始化配置与启动Hermes Agent 需要一个配置文件来定义模型、技能和记忆等设置。首次启动时它会引导你进行初始化。# 1. 初始化配置会生成配置文件 .hermes/config.yaml hermes init # 2. 启动 Hermes Agent 服务 hermes start执行hermes init时会进入一个交互式配置向导。你需要做出以下关键选择主模型提供商选择anthropic(Claude),openai(GPT),groq等。你需要提供对应的 API 密钥。本地模型选择是否启用 Ollama。如果启用需要指定本地运行的模型名称如llama3.2:latest。向量数据库用于记忆选择chroma(默认轻量级) 或qdrant。Chroma 适合本地开发。技能目录指定存放自定义 Skill 的 Python 文件路径。一个简化版的config.yaml核心部分可能如下所示# .hermes/config.yaml model: primary: provider: anthropic model: claude-3-5-sonnet-20241022 api_key: ${ANTHROPIC_API_KEY} # 建议使用环境变量 local: enabled: true provider: ollama model: llama3.2:latest base_url: http://localhost:11434 skills: # 内置技能 - hermes_agent.skills.builtin.filesystem.FileSystemSkill - hermes_agent.skills.builtin.web_search.WebSearchSkill # 自定义技能路径 custom_paths: - ./my_skills memory: type: chroma persist_directory: ./chroma_db server: host: 0.0.0.0 port: 8000启动后默认的 Web UI 可以通过http://localhost:8000访问。同时一个后台服务进程会开始运行。3. 深入技能系统创建与使用自定义 Skill自定义 Skill 是 Hermes Agent 真正强大的地方它允许你将任何本地能力或业务逻辑封装成 Agent 可以调用的工具。3.1 Skill 的基本结构一个 Skill 本质上是一个继承了BaseSkill类的 Python 类并使用装饰器声明其元数据。核心组成部分包括class_description: 技能的整体描述。skill装饰器注册函数为一个可调用的技能。parameter装饰器定义函数参数的名称、类型、描述和是否必需。3.2 实战创建一个“文件内容搜索” Skill假设我们想让 Agent 能够搜索指定目录下所有文件中包含特定关键词的行。创建技能目录和文件 在项目根目录下创建my_skills/目录并在其中创建file_search_skill.py。mkdir -p my_skills touch my_skills/file_search_skill.py编写 Skill 代码 编辑my_skills/file_search_skill.py写入以下内容# my_skills/file_search_skill.py import os from typing import List, Optional from hermes_agent.skills import BaseSkill, skill, parameter class FileSearchSkill(BaseSkill): 一个用于在指定目录的文件中搜索特定文本内容的技能。 支持按文件扩展名过滤。 class_description 在文件系统中搜索包含特定文本的文件和行。 skill( namesearch_files_for_text, description递归搜索目录查找包含给定文本字符串的文件并返回匹配的行及其位置。 ) parameter(namedirectory_path, typestr, description要开始搜索的根目录路径, requiredTrue) parameter(namesearch_text, typestr, description要搜索的文本内容, requiredTrue) parameter(namefile_extension, typestr, description可选的文件扩展名过滤器例如 .txt, .py, requiredFalse) def search_files( self, directory_path: str, search_text: str, file_extension: Optional[str] None ) - List[dict]: 执行文件搜索。 返回一个字典列表每个字典包含文件路径、行号和匹配的行内容。 results [] # 安全检查确保目录存在 if not os.path.isdir(directory_path): return [{error: f目录不存在: {directory_path}}] for root, dirs, files in os.walk(directory_path): for file in files: # 应用扩展名过滤 if file_extension and not file.endswith(file_extension): continue file_path os.path.join(root, file) try: with open(file_path, r, encodingutf-8, errorsignore) as f: for line_num, line in enumerate(f, start1): if search_text in line: results.append({ file_path: file_path, line_number: line_num, matched_line: line.strip() }) except (IOError, PermissionError) as e: # 记录错误但继续搜索其他文件 results.append({ file_path: file_path, error: f无法读取文件: {str(e)} }) return results更新配置 确保你的config.yaml中skills.custom_paths包含了./my_skills初始化时如果已设置则无需修改。重新加载技能 技能是动态加载的。修改技能文件或添加新技能后需要让 Agent 重新加载。方法一重启 Hermes Agent 服务 (hermes stop然后hermes start)。方法二通过 API 调用重新加载端点如果暴露了的话。3.3 在对话中使用自定义 Skill启动 Hermes Agent 并打开 Web UI 或使用其 API。现在你可以尝试向 Agent 发出如下指令“请在我的~/projects目录下搜索所有.py文件中包含def get_user这个字符串的地方并告诉我结果。”Agent 的内部工作流将会理解你的意图是“搜索文件”。规划调用search_files_for_text这个技能。提取参数directory_path“~/projects”,search_text“def get_user”,file_extension“.py”。在本地执行你的 Python 函数。将函数返回的列表结果整合成一段清晰的文字回复给你。4. 揭秘记忆系统从会话上下文到长期记忆记忆是智能体体现“智能”和连续性的关键。很多人部署后发现 Agent“没有记忆”通常是因为对记忆系统的工作原理理解不透彻或配置不当。4.1 记忆的层次与存储Hermes Agent 的记忆通常分为两层记忆类型存储介质容量用途生命周期会话记忆内存 / 临时存储有限受上下文窗口限制维持当前对话的连贯性理解指代如“它”、“上面提到的”。随会话结束而消失。长期记忆向量数据库如Chroma理论上无限存储跨会话的重要事实、用户偏好、任务结果等供未来检索。持久化存储除非手动删除。当你使用claude-mem这类强调记忆的模型时它指的是模型自身在单次上下文窗口内处理长文本和维持连贯性的能力与框架的长期记忆系统是互补关系。4.2 配置与验证记忆功能确保你的config.yaml中memory部分已正确配置并且向量数据库服务如 Chroma已随 Agent 启动。常见问题claude-mem安装后无记忆记录这个问题可能由以下几个原因导致记忆未持久化检查config.yaml中memory.persist_directory是否设置。如果没有设置或路径不可写记忆可能只存在于内存重启后丢失。检索策略问题Agent 不是每次都会从长期记忆中检索信息。它只在模型认为需要历史上下文时才会触发检索。你可以尝试问一些明显需要历史信息的问题如“我们昨天讨论的那个项目计划是什么”。向量化模型不匹配长期记忆需要将文本转换为向量Embedding。确保你配置的 Embedding 模型通常是默认的可用且适合你的语言。会话记忆与长期记忆混淆模型自身的上下文记忆会话记忆是即时的不会存入向量库。只有被框架明确标记为“需要存储”的信息才会进入长期记忆。验证记忆是否工作 你可以通过查询向量数据库来直接验证。如果使用 Chroma可以编写一个小脚本# check_memory.py import chromadb from chromadb.config import Settings # 连接到 Hermes Agent 使用的 Chroma 持久化目录 client chromadb.PersistentClient(path./chroma_db, settingsSettings(anonymized_telemetryFalse)) # 列出所有集合每个集合可能对应一种记忆类型 collections client.list_collections() print(已有的记忆集合:, [c.name for c in collections]) # 假设主要集合名为 hermes_memory if collections: collection client.get_collection(namecollections[0].name) # 获取前几条记录 results collection.peek() print(f集合 {collection.name} 中的记录数: {collection.count()}) if results[documents]: print(示例记忆内容:, results[documents][:2])4.3 最佳实践设计有效的记忆交互为了让记忆系统更有效你可以在自定义 Skill 或系统指令中设计记忆的读写主动存储在 Skill 执行后将重要的结果摘要主动存储到长期记忆。结构化存储存储时添加清晰的元数据如type: “project_plan”,date: “2024-01-15”便于后续检索。优化检索提示在系统指令中鼓励模型在适当时机询问用户是否需要记住某些信息或主动检索相关记忆。5. 高级配置与生产环境考量将 Hermes Agent 用于更严肃的场景时需要考虑以下方面。5.1 模型路由与降级策略在config.yaml中你可以精细控制模型的使用策略。model: primary: provider: anthropic model: claude-3-5-sonnet-20241022 api_key: ${ANTHROPIC_API_KEY} # 设置温度、最大token等参数 parameters: temperature: 0.7 max_tokens: 4096 local: enabled: true provider: ollama model: llama3.2:latest base_url: http://localhost:11434 # 路由规则定义哪些请求走本地模型 routing: # 如果任务描述中包含这些关键词优先使用本地模型 use_local_for_keywords: [简单, 总结, 翻译, 格式化] # 如果主模型不可用如API超限、网络错误自动降级到本地模型 fallback_to_local_on_primary_failure: true5.2 技能的安全性与权限控制自定义 Skill 拥有执行本地代码的能力因此安全至关重要。输入验证在所有自定义 Skill 中严格验证输入参数。例如对于文件路径检查是否在允许的目录范围内防止路径遍历攻击。沙箱环境高级考虑在 Docker 容器或受限的子进程中运行不可信的 Skill。技能白名单在生产环境中不要动态加载任意路径的技能。应通过配置明确指定允许加载的技能列表。权限分离运行 Hermes Agent 的进程应使用具有最小必要权限的系统用户而不是 root。5.3 日志、监控与持久化日志配置Hermes Agent 通常使用 Python 的logging模块。你可以通过配置logging.yaml或环境变量来调整日志级别和输出格式将日志导入到 ELK 或 Loki 等系统。对话历史持久化除了向量记忆你可能还需要完整存储原始的对话历史用于审计或再训练。这可以通过订阅 Agent 的事件总线或编写一个存储 Skill 来实现。健康检查为 Hermes Agent 的 HTTP 服务设置健康检查端点如果提供或自行实现一个检查模型和技能是否可用的监控脚本。5.4 常见故障排查清单下表列出了部署和使用 Hermes Agent 时可能遇到的典型问题及解决思路问题现象可能原因检查步骤解决方案Agent 服务启动失败1. 端口被占用2. 配置文件语法错误3. 关键依赖缺失1.netstat -tulnp | grep :80002.hermes validate-config3. 查看启动日志hermes start --log-level DEBUG1. 更改config.yaml中的port2. 修正 YAML 语法3. 重新安装依赖pip install -r requirements.txt无法调用云端模型 (如 Claude)1. API Key 未设置或错误2. 网络问题3. 额度用尽或模型不可用1. 检查config.yaml或环境变量echo $ANTHROPIC_API_KEY2.curl -v https://api.anthropic.com3. 查看提供商控制台1. 设置正确的 API Key2. 配置网络代理如需3. 检查账单或切换模型本地模型 (Ollama) 无响应1. Ollama 服务未运行2. 模型未拉取3. 配置中的base_url错误1.systemctl status ollama或ollama serve2.ollama list3. 检查config.yaml中的base_url1. 启动 Ollama 服务2.ollama pull llama3.2:latest3. 修正为http://localhost:11434自定义 Skill 未加载1. 技能路径未配置2. Python 语法错误3. 类未继承BaseSkill1. 检查config.yaml的skills.custom_paths2.python -m py_compile my_skills/*.py3. 查看 Agent 启动日志1. 添加正确路径2. 修正代码错误3. 确保正确导入和继承Agent 回答“我不知道如何做X”1. 缺乏对应 Skill2. 模型未正确规划使用现有 Skill3. Skill 描述不够清晰1. 检查已加载技能列表2. 查看模型收到的完整提示词调试模式3. 审查 Skill 的description和parameter描述1. 创建所需 Skill2. 优化系统指令明确技能能力3. 用更清晰的语言重写 Skill 描述记忆功能似乎无效1. 向量数据库未持久化2. 检索相关性阈值过高3. 信息未被标记为需要存储1. 检查chroma_db目录是否存在和写入2. 检查记忆检索的相似度分数配置3. 查看记忆写入的日志1. 确认persist_directory配置2. 调整检索阈值如果配置支持3. 在 Skill 或交互中显式触发记忆存储通过遵循本教程你不仅能在本地成功部署和运行 Hermes Agent更能深入理解其内部机制从而能够定制技能、管理记忆并构建出真正贴合你个人或业务需求的智能体。下一步你可以探索将其与内部系统如 CRM、知识库集成或者研究多智能体协作的配置让多个拥有不同技能的 Agent 共同解决复杂问题。