ByteNoteByteNote
字

字节笔记本

2026年5月16日

Hermes Agent Python Library：将 AI Agent 集成到你的 Python 应用

#AI 前沿
API中转
¥120

Hermes Agent 不仅仅是一个 CLI 工具，你还可以将 AIAgent 直接导入到自己的 Python 脚本、Web 应用或自动化流水线中使用。本文将介绍如何安装、配置以及在实际场景中集成 Hermes Agent。

安装

直接从仓库安装 Hermes：

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

或使用 uv：

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

你也可以在 requirements.txt 中固定版本：

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

CLI 所需的环境变量在库模式下同样需要设置。至少要配置 OPENROUTER_API_KEY（如果使用直连提供商，则需要 OPENAI_API_KEY 或 ANTHROPIC_API_KEY）。

基本用法

最简单的方式是使用 chat() 方法 —— 传入消息，返回字符串：

python
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 旋转指示器、进度条等终端内容，干扰应用程序的正常输出。

完整会话控制

如果需要对对话进行更精细的控制，可以直接使用 run_conversation()。它返回一个字典，包含完整的响应、消息历史和元数据：

python
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 会存储在 Agent 实例上用于 VM 隔离，但不会在返回字典中原样返回。）

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

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

配置工具集

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

python
# 仅启用 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 时（例如仅使用 web 搜索的研究机器人），使用 enabled_toolsets。当你需要大部分能力但需要限制特定功能时（例如共享环境中禁止终端访问），使用 disabled_toolsets。

多轮对话

通过传入消息历史，可以在多轮对话间保持会话状态：

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

# 第一轮
result1 = agent.run_conversation("My name is Alice")
history = result1["messages"]

# 第二轮 — Agent 记住了上下文
result2 = agent.run_conversation(
    "What's my name?",
    conversation_history=history,
)
print(result2["final_response"])  # "Your name is Alice."

conversation_history 参数接受上一次结果中的 messages 列表。Agent 会在内部复制该列表，因此原始列表不会被修改。

保存对话轨迹

启用轨迹保存功能可以捕获 ShareGPT 格式的对话 —— 这对于生成训练数据或调试非常有用：

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

agent.chat("Write a Python function to sort a list")
# 保存到 trajectory_samples.jsonl，格式为 ShareGPT

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

自定义系统提示

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

python
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 实例并确保资源隔离：

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

每个提示都会获得独立的 task_id 和隔离的环境。如果需要自定义批处理逻辑，可以直接使用 AIAgent：

python
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):
    # 为每个任务创建新的 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"Q: {prompt}\nA: {result}\n")

务必为每个线程或任务创建新的 AIAgent 实例。Agent 维护着内部状态（对话历史、工具会话、迭代计数器），这些状态在并发间共享是不安全的。

集成示例

FastAPI 端点

python
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 机器人

python
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 流水线步骤

python
#!/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)

构造函数关键参数

参数类型默认值说明
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 前沿
上一篇

Hermes Agent Skills 系统：扩展 Agent 能力的技能框架

下一篇

Hermes Agent Python Library：将 AI Agent 集成到你的 Python 应用

分享: