將 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

提示

在作為庫使用時，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("What is the capital of France?")
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="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 —— 完整的消息歷史（系統、用戶、助手、工具調用）
• 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 控制 Agent 可訪問的工具集：

# 僅啟用網頁tools（瀏覽、搜索）
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。當你希望擁有大部分功能但需要限制特定工具（例如，在共享環境中禁用終端訪問）時，請使用 disabled_toolsets。

---

多輪對話

通過將消息歷史傳回，可在多輪對話中保持對話狀態：

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

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

# 第二回合 — agent 記得 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")
# 以 ShareGPT 格式保存到 trajectory_samples.jsonl

每次對話都會作為單行 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

每個提示都會獲得獨立的 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):
    # 每個任務創建一個新的 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 端點

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" 等）

---

重要說明

提示

• 如果不希望將工作目錄中的 AGENTS.md 文件加載到系統提示中，請設置 skip_context_files=True。
• 若要阻止 Agent 讀取或寫入持久記憶，請設置 skip_memory=True —— 建議用於無狀態 API 端點。
• platform 參數（例如 "discord"、"telegram"）會注入平臺特定的格式化提示，使 Agent 能夠調整其輸出風格。

注意

• 線程安全性：每個線程或任務應創建一個 AIAgent 實例。切勿在併發調用之間共享實例。
• 資源清理：當對話結束時，Agent 會自動清理資源（終端會話、瀏覽器實例）。如果在長期運行的進程中運行，請確保每次對話都能正常完成。
• 迭代次數限制：默認的 max_iterations=90 已經相當寬鬆。對於簡單的問答用例，建議降低該值（例如設置為 max_iterations=10），以防止工具調用循環失控並控制成本。