跳到主要内容

将 Hermes 作为 Python 库使用

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
提示

作为库使用 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("法国的首都是什么？")
print(response)

chat() 内部处理完整的对话循环 — 工具调用、重试、一切 — 只返回最终的文本响应。

注意

在自己的代码中嵌入 Hermes 时，务必设置 quiet_mode=True。否则 Agent 会打印 CLI 旋转器、进度指示器和其他终端输出，干扰你的应用输出。

完整对话控制​

要更精细地控制对话，直接使用 run_conversation()。它返回包含完整响应、消息历史和元数据的字典：

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)

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 — Agent 的最终文本回复
  • messages — 完整的消息历史（系统、用户、助手、工具调用）
  • task_id — 用于 VM 隔离的任务标识符

你也可以传入自定义系统消息，覆盖该次调用的临时系统提示：

result = agent.run_conversation(
    user_message="解释快速排序",
    system_message="你是一位计算机科学导师。使用简单的类比。",
)

配置工具​

使用 enabled_toolsets 或 disabled_toolsets 控制 Agent 可访问的工具集：

# 仅启用 Web 工具（浏览、搜索）
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# 启用除终端访问外的所有功能
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)
提示

当你需要一个最小化、锁定的 Agent 时使用 enabled_toolsets（如只允许 Web 搜索的研究 Bot）。当你需要大部分功能但要限制特定功能时使用 disabled_toolsets（如在共享环境中禁止终端访问）。

多轮对话​

通过传回消息历史来维护跨多轮的对话状态：

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)

# 第一轮
result1 = agent.run_conversation("我的名字是小明")
history = result1["messages"]

# 第二轮 — Agent 记住上下文
result2 = agent.run_conversation(
    "我叫什么名字？",
    conversation_history=history,
)
print(result2["final_response"])  # "你的名字是小明。"

conversation_history 参数接受上次结果的 messages 列表。Agent 内部会复制它，原始列表不会被修改。

保存轨迹​

启用轨迹保存，以 ShareGPT 格式捕获对话 — 用于生成训练数据或调试：

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    save_trajectories=True,
    quiet_mode=True,
)

agent.chat("写一个 Python 函数来排序列表")
# 保存到 trajectory_samples.jsonl，ShareGPT 格式

每次对话作为一行 JSONL 追加，方便从自动化运行中收集数据集。

自定义系统提示​

使用 ephemeral_system_prompt 设置自定义系统提示来引导 Agent 行为，但不会保存到轨迹文件（保持训练数据干净）：

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

response = agent.chat("如何写 JOIN 查询？")
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 = [
    "解释递归",
    "哈希表是什么？",
    "垃圾回收如何工作？",
]

def process_prompt(prompt):
    # 每个任务创建新 Agent 以确保线程安全
    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"问: {prompt}\n答: {result}\n")
注意

始终为每个线程或任务创建新的 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 Bot​

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 步骤：自动审查 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"审查这个 PR diff 中的 bug、安全问题和风格问题:\n\n{diff}"
)
print(review)

关键构造参数​

参数类型默认值说明
modelstr"anthropic/claude-opus-4.6"OpenRouter 格式的模型名称
quiet_modeboolFalse抑制 CLI 输出
enabled_toolsetsList[str]None白名单特定工具集
disabled_toolsetsList[str]None黑名单特定工具集
save_trajectoriesboolFalse保存对话到 JSONL
ephemeral_system_promptstrNone自定义系统提示（不保存到轨迹）
max_iterationsint90每次对话最大工具调用迭代次数
skip_context_filesboolFalse跳过加载 AGENTS.md 文件
skip_memoryboolFalse禁用持久记忆读写
api_keystrNoneAPI 密钥（回退到环境变量）
base_urlstrNone自定义 API 端点 URL
platformstrNone平台提示（"discord"、"telegram" 等）

重要说明​

提示
  • 如果不想将工作目录中的 AGENTS.md 文件加载到系统提示中，设置 skip_context_files=True。
  • 设置 skip_memory=True 可阻止 Agent 读写持久记忆 — 推荐用于无状态 API 端点。
  • platform 参数（如 "discord"、"telegram"）注入平台特定的格式提示，让 Agent 自适应输出风格。
注意
  • 线程安全：每个线程或任务创建一个 AIAgent。永远不要在并发调用间共享实例。
  • 资源清理：对话结束时 Agent 自动清理资源（终端会话、浏览器实例）。如果在长期运行的进程中使用，确保每次对话正常完成。
  • 迭代限制：默认 max_iterations=90 比较宽松。对于简单的问答场景，考虑降低（如 max_iterations=10）以防止工具调用循环失控和控制成本。

📝 本文由 AI 翻译，如有疑问请参考英文原版