Hermes Agent Python 库：把 AI 打工仔塞进你的代码里

—— 告别 CLI 命令行，用 import 召唤神龙

前言：Hermes 不只是个命令行工具

你有没有这种经历：在终端里一行行敲命令，等 AI 回你，等得花都谢了？Hermes Agent 以前就是个 CLI 工具，你得在命令行里跟它对话，就像跟个傲娇的客服吵架一样。但今天不一样了 —— Hermes 摇身一变，成了一个可以 import 到 Python 项目里的库。

没错，你没听错。你不需要再对着黑漆漆的终端大喊大叫了，直接 `from run_agent import AIAgent`，一行代码召唤一个全副武装的 AI 打工人，塞进你的脚本、Web 应用、自动化流水线，随你使唤。

💡 核心理念：Hermes = 一个可以编程调用的 AI Agent，自带工具调用、多轮对话、批量处理等全套技能。

第一章：装就完事了，比点外卖还简单

安装 Hermes 库的方式多种多样，总有一款适合你。

1.1 pip 装包：传统艺能

最朴素的方式，用 pip 直接从 GitHub 仓库拉取：

pip install git+https://github.com/NousResearch/hermes-agent.git

1.2 uv 装包：速度起飞

如果你追求极致速度，uv 是你的菜，比 pip 快得不止一个量级：

uv pip install git+https://github.com/NousResearch/hermes-agent.git

1.3 requirements.txt：持久化方案

想把 Hermes 写进项目依赖里？直接在 requirements.txt 里加上：

hermes-agent @ git+https://github.com/NousResearch/hermes-agent.git

💡 环境变量不能省！至少要设置 OPENROUTER_API_KEY（或者 OPENAI_API_KEY / ANTHROPIC_API_KEY）。不设置？那 AI 就是断了网的赛博盲人，啥也干不了。

第二章：三行代码，召唤 AI 打工人

最简用法，只有三行：

from run_agent import AIAgent          agent = AIAgent(model="anthropic/claude-sonnet-4", quiet_mode=True)          response = agent.chat("巴黎首都是啥？")          print(response)

就这么简单。`chat()` 方法内部帮你搞定了一切：工具调用、重试、多轮对话，最后就返回一个纯文本答案。你只管提问，AI 只管干活。

2.1 关键参数：quiet_mode=True

💡 一定要设置 quiet_mode=True！不然 AI 会像话痨一样，在终端里打印各种进度条、旋转动画，把你程序输出的日志淹得底裤都不剩。在代码里用？安静点好。

第三章：full control —— 当你对 AI 不放心时

如果你不满足于简单问答，想要掌控全局，那就用 `run_conversation()`。这玩意儿返回一个字典，里面有你想要的一切：最终回复、完整对话历史、元数据。

result = agent.run_conversation(          user_message="搜一下 Python 3.13 有啥新特性",          task_id="my-task-1",          )          print(result["final_response"])          print(f"来回对话了 {len(result['messages'])} 轮")

返回的字典里：`final_response` 是 AI 的最终回答，`messages` 是完整的对话历史（系统提示、用户消息、AI 回复、工具调用……全在里面）。

3.1 自定义系统提示：给 AI 贴标签

你可以传入 `system_message` 覆盖默认的系统提示：

result = agent.run_conversation(          user_message="给我讲讲快排",          system_message="你是个计算机科学的老师，用最简单的类比来解释。",          )

💡 这相当于给 AI 贴了个临时标签：今天你是老师，明天你是代码审查员，后天你是 SQL 专家。同一个 Hermes，换脑即换人。

第四章：工具箱 —— 要还是不要，你说了算

Hermes 内置了各种 toolsets（工具集）：浏览器、终端、搜索、文件操作……但你不需要全部。可以按需开启或关闭。

4.1 只开网页工具：搜搜搜

agent = AIAgent(          model="anthropic/claude-sonnet-4",          enabled_toolsets=["web"],# 只开网页工具          quiet_mode=True,          )

4.2 关闭终端：安全模式

agent = AIAgent(          model="anthropic/claude-sonnet-4",          disabled_toolsets=["terminal"],# 关终端，开放所有          quiet_mode=True,          )

💡 场景建议：`enabled_toolsets` 适合最小权限（比如只让 AI 搜索），`disabled_toolsets` 适合大部分开放但需要限制个别危险操作的场景。

第五章：多轮对话 —— AI 的短期记忆

Hermes 默认没有跨调用的记忆。每次 `chat()` 都是新的开始。但如果你想让 AI 记住上下文，可以手动传递对话历史：

# 第一回合          result1 = agent.run_conversation("我叫小明")          history = result1["messages"]          # 第二回合 —— AI 还记得          result2 = agent.run_conversation(          "你记得我叫啥不？",          conversation_history=history,          )          print(result2["final_response"])# "你叫小明啊！"

`conversation_history` 接收上一次返回的 messages 列表。Hermes 会内部复制一份，不会污染你原来的列表。

第六章：保存轨迹 —— 收集 AI 的数据

开启 `save_trajectories=True`，Hermes 会把每次对话以 ShareGPT 格式保存到 `trajectory_samples.jsonl` 文件中。适合用来：

- 收集训练数据

- 调试 AI 的行为

- 分析 AI 的思考过程

💡 每条对话占一行 JSONL，批量处理的时候特别好使。

第七章：定制人格 —— 给 AI 穿衣服

用 `ephemeral_system_prompt` 给 AI 设定专属人设，而且这个提示不会保存到轨迹文件里，保证训练数据干干净净：

agent = AIAgent(          model="anthropic/claude-sonnet-4",          ephemeral_system_prompt="你是个 SQL 专家，只回答数据库相关问题。",          quiet_mode=True,          )

💡 这招特别适合打造专用 Agent：代码审查员、文档撰写机器人、SQL 助手……同一个底层工具，换上不同的系统提示，就是不同的专家。

第八章：批量处理 —— 一人干活，不如一群 AI

想同时跑一堆提示词？Hermes 自带 `batch_runner.py`：

python batch_runner.py --input prompts.jsonl --output results.jsonl

每个提示词有自己的 task_id 和隔离环境。如果想自己写批量逻辑：

import concurrent.futures          from run_agent import AIAgent          prompts = [          "解释一下递归",          "哈希表是啥？",          "垃圾回收怎么工作的？",          ]          def process_prompt(prompt):          agent = AIAgent(          model="anthropic/claude-sonnet-4",          quiet_mode=True,          skip_memory=True,          )          return agent.chat(prompt)          with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:          results = list(executor.map(process_prompt, prompts))

💡 重要：每个线程必须创建新的 AIAgent 实例！Agent 内部有对话历史、工具会话、迭代计数器等状态，不是线程安全的，不能共享。

第九章：实战 —— 把 Hermes 塞进你的项目

9.1 FastAPI 接口

写个 Web API，前端发来消息，Hermes 秒回：

from fastapi import FastAPI          from pydantic import BaseModel          from run_agent import AIAgent          app = FastAPI()          class ChatRequest(BaseModel):          message: str          model: str = "anthropic/claude-sonnet-4"          @app.post("/chat")          async def chat(request: ChatRequest):          agent = AIAgent(          model=request.model,          quiet_mode=True,          skip_context_files=True,          skip_memory=True,          )          response = agent.chat(request.message)          return {"response": response}

9.2 Discord Bot

在 Discord 里 @AI 求助？安排：

import discord          from run_agent import AIAgent          client = discord.Client(intents=discord.Intents.default())          @client.event          async def on_message(message):          if message.author == client.user:          return          if message.content.startswith("!hermes "):          query = message.content[8:]          agent = AIAgent(          model="anthropic/claude-sonnet-4",          quiet_mode=True,          skip_context_files=True,          skip_memory=True,          platform="discord",          )          response = agent.chat(query)          await message.channel.send(response[:2000])          client.run("YOUR_DISCORD_TOKEN")

9.3 CI/CD 流水线：自动 Code Review

PR 合并前让 AI 帮你审代码，解放双手：

#!/usr/bin/env python3          import subprocess          from run_agent import AIAgent          diff = subprocess.check_output(          ["git", "diff", "main...HEAD"]          ).decode()          agent = AIAgent(          model="anthropic/claude-sonnet-4",          quiet_mode=True,          skip_context_files=True,          skip_memory=True,          disabled_toolsets=["terminal", "browser"],          )          review = agent.chat(          f"审查这段 PR diff 的 bug、安全漏洞和代码风格问题：\n\n{diff}"          )          print(review)

第十章：参数速查表 —— 不查文档也能用

以下是 AIAgent 构造函数里的关键参数和注意事项：

skip_context_files=True —— 不想让 AGENTS.md 文件自动加载到系统提示里？开它。

skip_memory=True —— 不让 AI 读写持久化记忆。API 接口场景必备，保证每次调用都是无状态的。

platform 参数 —— 比如传 `"discord"` 或 `"telegram"`，AI 会自动调整输出风格，适配平台格式。

max_iterations —— 默认 90 次迭代。如果只做简单问答，建议降到 10 以内，防止 AI 陷入工具调用死循环烧钱。

💡 线程安全铁律：一个线程一个 Agent 实例，千万别共享。资源清理：对话结束后会自动清理终端会话和浏览器实例，但长进程里要确保正常结束。

总结：从 CLI 到 Library，Hermes 的进化之路

Hermes Agent 从一个命令行工具进化为一个可编程的 Python 库，意味着你可以把 AI Agent 的能力直接嵌入到任何 Python 项目中。不管你是写 Web API、Discord Bot、CI 流水线，还是批量处理脚本，Hermes 都能胜任。

核心就三点：

1. 安装简单，三行代码启动

2. 控制灵活，工具按需开关

3. 集成方便，塞进任何项目都能跑

🚀👋

现在，去 import 你的第一个 AI 打工人吧。