Hermes 不仅仅是一个 CLI 工具。你可以直接导入 AIAgent，在自己的 Python 脚本、Web 应用或自动化流水线中以编程方式使用它。本指南将向你展示如何操作。 直接从仓库安装 Hermes： 或者使用 uv： 你也可以将其固定在 requirements.txt 中：
作为 Python 库使用
> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16
作为 Python 库使用 Hermes
Hermes 不仅仅是一个 CLI 工具。你可以直接导入 AIAgent，在自己的 Python 脚本、Web 应用或自动化流水线中以编程方式使用它。本指南将向你展示如何操作。
安装
直接从仓库安装 Hermes：
pip install git+https://github.com/NousResearch/hermes-agent.git
或者使用 uv：
uv pip install git+https://github.com/NousResearch/hermes-agent.git
你也可以将其固定在 requirements.txt 中：
hermes-agent @ git+https://github.com/NousResearch/hermes-agent.git
tip
将 Hermes 作为库使用时，需要与 CLI 相同的环境变量。至少需要设置 OPENROUTER_API_KEY（如果使用直连提供商，则设置 OPENAI_API_KEY / ANTHROPIC_API_KEY）。
基本使用方法
使用 Hermes 最简单的方式是 chat() 方法——传入一条消息，返回一个字符串：
from run_agent import AIAgent
agent = AIAgent(
model="anthropic/claude-sonnet-4",
quiet_mode=True,
)
response = agent.chat("What is the capital of France?")
print(response)
chat() 在内部处理完整的对话循环——工具调用、重试等所有环节——并仅返回最终的文本响应。
warning
在自己的代码中嵌入 Hermes 时，务必设置 quiet_mode=True。否则，agent 会打印 CLI 旋转指示器、进度条等终端输出，会干扰你的应用输出。
完整对话控制
如需更精细地控制对话，可直接使用 run_conversation()。它会返回一个包含完整响应、消息历史和元数据的字典：
agent = AIAgent(
model="anthropic/claude-sonnet-4",
quiet_mode=True,
)
result = agent.run_conversation(
user_message="Search for recent Python 3.13 features",
task_id="my-task-1",
)
print(result["final_response"])
print(f"Messages exchanged: {len(result['messages'])}")
返回的字典包含：
final_response— agent 的最终文本回复messages— 完整的消息历史（系统消息、用户消息、助手消息、工具调用）task_id— 用于 VM 隔离的任务标识符
你也可以传入自定义系统消息，覆盖该次调用的临时系统提示：
result = agent.run_conversation(
user_message="Explain quicksort",
system_message="You are a computer science tutor. Use simple analogies.",
)
配置工具
使用 enabled_toolsets 或 disabled_toolsets 控制 agent 可以访问哪些工具集：
# Only enable web tools (browsing, search)
agent = AIAgent(
model="anthropic/claude-sonnet-4",
enabled_toolsets=["web"],
quiet_mode=True,
)
# Enable everything except terminal access
agent = AIAgent(
model="anthropic/claude-sonnet-4",
disabled_toolsets=["terminal"],
quiet_mode=True,
)
tip
当你需要一个最小化、受限的 agent 时，使用 enabled_toolsets（例如，研究机器人仅启用网络搜索）。当你需要大部分功能但要限制特定能力时，使用 disabled_toolsets（例如，共享环境中禁止终端访问）。
多轮对话
通过传回消息历史来维持多轮对话状态：
agent = AIAgent(
model="anthropic/claude-sonnet-4",
quiet_mode=True,
)
# First turn
result1 = agent.run_conversation("My name is Alice")
history = result1["messages"]
# Second turn — agent remembers the context
result2 = agent.run_conversation(
"What's my name?",
conversation_history=history,
)
print(result2["final_response"]) # "Your name is Alice."
conversation_history 参数接受前一次结果的 messages 列表。agent 会在内部复制该列表，因此你的原始列表不会被修改。
保存对话轨迹
启用轨迹保存功能，以 ShareGPT 格式捕获对话——适用于生成训练数据或调试：
agent = AIAgent(
model="anthropic/claude-sonnet-4",
save_trajectories=True,
quiet_mode=True,
)
agent.chat("Write a Python function to sort a list")
# Saves to trajectory_samples.jsonl in ShareGPT format
每次对话会作为一条 JSONL 行追加，便于从自动化运行中收集数据集。
自定义系统提示
使用 ephemeral_system_prompt 设置自定义系统提示来引导 agent 的行为，但该提示不会被保存到轨迹文件中（保持训练数据的干净）：
agent = AIAgent(
model="anthropic/claude-sonnet-4",
ephemeral_system_prompt="You are a SQL expert. Only answer database questions.",
quiet_mode=True,
)
response = agent.chat("How do I write a JOIN query?")
print(response)
这非常适合构建专业化 agent——代码审查者、文档编写者、SQL 助手——全部使用相同的底层工具。
批量处理
为了并行运行大量提示，Hermes 包含 batch_runner.py。它管理并发的 AIAgent 实例并提供适当的资源隔离：
python batch_runner.py --input prompts.jsonl --output results.jsonl
每个提示都有自己的 task_id 和隔离环境。如果你需要自定义批处理逻辑，可以直接使用 AIAgent 来构建：
import concurrent.futures
from run_agent import AIAgent
prompts = [
"Explain recursion",
"What is a hash table?",
"How does garbage collection work?",
]
def process_prompt(prompt):
# Create a fresh agent per task for thread safety
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))
for prompt, result in zip(prompts, results):
print(f"Q: {prompt}\nA: {result}\n")
warning
始终为每个线程或任务创建新的 AIAgent 实例。agent 维护着内部状态（对话历史、工具会话、迭代计数器），这些状态在线程间共享是不安全的。
集成示例
FastAPI 端点
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}
Discord 机器人
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")
CI/CD 流水线步骤
#!/usr/bin/env python3
"""CI step: auto-review a PR diff."""
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"Review this PR diff for bugs, security issues, and style problems:\n\n{diff}"
)
print(review)
关键构造参数
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
model | str | "anthropic/claude-opus-4.6" | OpenRouter 格式的模型名称 |
quiet_mode | bool | False | 抑制 CLI 输出 |
enabled_toolsets | List[str] | None | 白名单指定工具集 |
disabled_toolsets | List[str] | None | 黑名单指定工具集 |
save_trajectories | bool | False | 将对话保存为 JSONL |
ephemeral_system_prompt | str | None | 自定义系统提示（不保存到轨迹） |
max_iterations | int | 90 | 每次对话最大工具调用迭代次数 |
skip_context_files | bool | False | 跳过加载 AGENTS.md 文件 |
skip_memory | bool | False | 禁用持久化内存读写 |
api_key | str | None | API 密钥（回退到环境变量） |
base_url | str | None | 自定义 API 端点 URL |
platform | str | None | 平台提示（"discord"、"telegram" 等） |
❗ 重要提示
tip
- 如果你不想将工作目录中的
AGENTS.md文件加载到系统提示中，请设置skip_context_files=True。 - 设置
skip_memory=True可防止 agent 读写持久化内存——推荐用于无状态 API 端点。 platform参数（如"discord"、"telegram"）会注入特定平台的格式提示，使 agent 调整输出风格。
warning
- 线程安全：每个线程或任务创建一个
AIAgent。切勿在并发调用间共享实例。 - 资源清理：对话结束时，agent 会自动清理资源（终端会话、浏览器实例）。如果你在长期运行的进程中使用，请确保每次对话正常完成。
- 迭代限制：默认的
max_iterations=90相当宽松。对于简单的问答场景，可以考虑降低该值（如max_iterations=10），以防止工具调用循环失控并控制成本。