将 Hermes 作为 Python 库使用

Hermes 不仅仅是一个 CLI 工具。你可以直接导入 AIAgent，在自己的 Python 脚本、Web 应用或自动化流水线中以编程方式使用它。本指南将介绍具体方法。

安装

直接从仓库安装 Hermes：

或使用 uv：

也可以在 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() 方法——传入一条消息，返回一个字符串：

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

警告

将 Hermes 嵌入自己的代码时，务必设置 quiet_mode=True。否则，agent 会打印 CLI 的加载动画、进度指示器及其他终端输出，从而干扰你的应用输出。

完整对话控制

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

返回的字典包含：

final_response — agent 的最终文本回复

messages — 完整的消息历史（系统消息、用户消息、助手消息、工具调用）

（传入的 task_id 存储在 agent 实例上用于 VM 隔离，不会在返回字典中回显。）

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

配置工具集

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

提示

当你需要一个功能最小化、受限的 agent 时（例如，仅用于研究机器人的 Web 搜索），使用 enabled_toolsets。当你需要大部分功能但需限制特定能力时（例如，在共享环境中禁用终端访问），使用 disabled_toolsets。

多轮对话

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

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

保存轨迹数据

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

每次对话以单行 JSONL 的形式追加写入，便于从自动化运行中收集数据集。

自定义系统 Prompt

使用 ephemeral_system_prompt 设置自定义系统 prompt，用于引导 agent 的行为，但不会保存到轨迹文件中（保持训练数据的整洁）：

这非常适合构建专用 agent——代码审查员、文档撰写员、SQL 助手——全部使用相同的底层工具。

批量处理

如需并行运行大量 prompt，Hermes 提供了 batch_runner.py，它可管理并发的 AIAgent 实例并进行适当的资源隔离：

每个 prompt 都有自己的 task_id 和隔离环境。如果需要自定义批处理逻辑，可以直接使用 AIAgent 构建：

警告

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

集成示例

FastAPI 端点

Discord 机器人

CI/CD 流水线步骤

关键构造函数参数

参数	类型	默认值	描述
`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`	自定义系统 prompt（不保存到轨迹文件）
`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"` 等）

重要说明

提示

如果不希望将工作目录中的 AGENTS.md 文件加载到系统 prompt 中，请设置 skip_context_files=True。

设置 skip_memory=True 可阻止 agent 读写持久化内存——推荐用于无状态 API 端点。

platform 参数（如 "discord"、"telegram"）会注入平台特定的格式化提示，使 agent 适配其输出风格。

警告

线程安全：每个线程或任务创建一个 AIAgent 实例。切勿在并发调用中共享同一实例。

资源清理：agent 在对话结束时会自动清理资源（终端会话、浏览器实例）。若在长期运行的进程中使用，请确保每次对话正常结束。

迭代限制：默认的 max_iterations=90 较为宽松。对于简单的问答场景，建议适当降低该值（如 max_iterations=10），以防止工具调用循环失控并控制成本。

"将 Hermes 作为 Python 库使用"

将 Hermes 作为 Python 库使用#

安装#

基本用法#

完整对话控制#

配置工具集#

多轮对话#

保存轨迹数据#

自定义系统 Prompt#

批量处理#

集成示例#

FastAPI 端点#

Discord 机器人#

CI/CD 流水线步骤#

关键构造函数参数#

重要说明#

将 Hermes 作为 Python 库使用

安装

基本用法

完整对话控制

配置工具集

多轮对话

保存轨迹数据

自定义系统 Prompt

批量处理

集成示例

FastAPI 端点

Discord 机器人

CI/CD 流水线步骤

关键构造函数参数

重要说明