使用 Hermes 作为 Python 库

Hermes 不只是一个命令行工具。你也可以直接导入 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。

---

基础用法

最简单的调用方式是使用 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。否则它会输出 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 —— 代理的最终文本回复
• messages —— 完整的消息历史（系统、用户、助手、工具调用）
• task_id —— 用于虚拟机隔离的任务标识符

你也可以传入自定义系统消息，为这一轮调用临时覆盖系统提示：

result = agent.run_conversation(
    user_message="Explain quicksort",
    system_message="You are a computer science tutor. Use simple analogies.",
)

---

配置工具

你可以通过 enabled_toolsets 或 disabled_toolsets 控制代理可访问的工具集：

# 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

如果你想创建一个最小且受控的代理，例如只允许联网搜索的研究助手，优先使用 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 列表。代理会内部复制该列表，因此你的原始列表不会被修改。

---

保存对话轨迹

开启轨迹保存后，Hermes 会以 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 = 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)

这很适合构建用途明确的专用代理，例如代码审查助手、文档写作助手或 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 实例。该代理维护内部状态（对话历史、工具会话、迭代计数器），这些状态不支持跨并发调用共享。

---

集成示例

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

• 如果你不希望从当前工作目录加载上下文文件进入系统提示，请设置 skip_context_files=True。
• 设置 skip_memory=True 可以阻止代理读写持久记忆，比较适合无状态 API 接口或一次性任务。
• platform 参数（如 "discord"、"telegram"）会注入平台相关的格式提示，让代理更贴近对应平台的输出风格。

warning

• 线程安全性：每个线程或任务都应创建独立的 AIAgent 实例，不要在并发调用之间共享同一个实例。
• 资源清理：对话结束后，代理会自动回收终端会话、浏览器实例等资源。若你在长生命周期进程中使用 Hermes，请确保每次调用都能正常收尾。
• 迭代限制：默认的 max_iterations=90 偏宽松。对于简单问答，建议适当调低，例如设为 10，这样更容易控制成本，也能降低工具调用陷入循环的风险。