将 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（如果你走直连 provider，也可以是 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() 会在内部处理完整对话循环，包括工具调用、重试等全部流程，并只返回最终文本回复。

注意

当你把 Hermes 嵌入自己的代码时，请务必设置 quiet_mode=True。否则 agent 会输出 CLI 的 spinner、进度提示等终端内容，污染你的应用输出。

完整控制对话

如果你想更细致地控制对话过程，可以直接使用 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 -> 完整消息历史（system、user、assistant、tool calls）
task_id -> 用于 VM 隔离的任务标识

你也可以为某次调用传入自定义系统消息，用它覆盖这次调用的临时 system prompt：

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,
)

提示

如果你想要一个最小权限、强约束的 agent（例如只允许做网页搜索的研究机器人），优先使用 enabled_toolsets。如果你想保留大部分能力，但屏蔽某几个高风险工具（例如共享环境中禁用 terminal），则使用 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

每条 prompt 都会拿到自己的 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")

注意

每个线程或任务都必须创建全新的 AIAgent 实例。agent 内部维护了会话历史、工具会话、迭代计数等状态，这些都不是线程安全的，不能共享。

集成示例

FastAPI Endpoint

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 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)

重要构造参数

Parameter	Type	Default	Description
`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 key（若未传则回退到环境变量）
`base_url`	`str`	`None`	自定义 API endpoint
`platform`	`str`	`None`	平台提示（如 `"discord"`、`"telegram"`）

重要说明

提示

如果你不希望工作目录下的 AGENTS.md 被加载进系统提示，请设置 skip_context_files=True
如果你希望 agent 完全无状态，不读也不写持久记忆（例如 API endpoint），请设置 skip_memory=True
platform 参数（如 "discord"、"telegram"）会注入平台相关的格式提示，让 agent 自动调整输出风格

注意

线程安全：每个线程或任务都创建独立的 AIAgent，绝不要在并发调用间共享同一个实例
资源清理：当一次对话正常结束时，agent 会自动清理终端会话、浏览器实例等资源。如果你把它运行在长生命周期进程中，请确保每次对话都能正常完成
迭代上限：默认的 max_iterations=90 已经很宽松。对于简单问答场景，可以考虑调低（例如 max_iterations=10），以避免工具调用失控并更好控制成本

安装​

基础用法​

完整控制对话​

配置工具​

多轮对话​

保存轨迹​

自定义系统提示​

批处理​

集成示例​

FastAPI Endpoint​

Discord Bot​

CI/CD 流水线步骤​

重要构造参数​

重要说明​

安装