python library — The Hermes Bible

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.6",
    quiet_mode=True,
)
response = agent.chat("What is the capital of France?")
print(response)

chat() 在內部處理完整的對話迴圈——工具呼叫、重試、所有內容——並僅回傳最終的文字回應。

警告

將 Hermes 嵌入你自己的程式碼時，始終設定 quiet_mode=True。沒有它，代理會印出 CLI 旋轉器、進度指示器和其他終端輸出，這會混淆你的應用程式輸出。

完整對話控制

要對對話有更多控制，直接使用 run_conversation()。它回傳一個包含完整回應、訊息歷史和中繼資料的字典：

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    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 — 代理的最終文字回覆
messages — 完整的訊息歷史（系統、使用者、助手、工具呼叫）

（你傳入的 task_id 會儲存在代理實例上用於 VM 隔離，但不會在回傳字典中回顯。）

你也可以傳入一個自訂系統訊息來覆蓋該呼叫的短暫系統提示：

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

設定工具

使用 enabled_toolsets 或 disabled_toolsets 控制代理可以存取哪些工具集：

# 僅啟用網路工具（瀏覽、搜尋）
agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# 啟用除終端存取外的所有功能
agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)

提示

當你想要一個最小化、鎖定的代理時，使用 enabled_toolsets（例如研究機器人僅使用網路搜尋）。當你想要大多數功能但需要限制特定功能時，使用 disabled_toolsets（例如在共享環境中禁用終端存取）。

多輪對話

透過傳回訊息歷史來維護跨多輪的對話狀態：

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

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

# 第二輪 — 代理記得上下文
result2 = agent.run_conversation(
    "What's my name?",
    conversation_history=history,
)
print(result2["final_response"])  # "Your name is Alice."

conversation_history 參數接受先前結果的 messages 列表。代理會在內部複製它，因此你的原始列表永遠不會被修改。

儲存軌跡

啟用軌跡儲存以 ShareGPT 格式捕獲對話——用於產生訓練資料或除錯：

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    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 = 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)

這非常適合建構專門的代理——程式碼審查員、文件撰寫者、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 = 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 實例。代理維護的內部狀態（對話歷史、工具會話、迭代計數器）在並行呼叫之間共享是非執行緒安全的。

整合範例

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`	`""`	OpenRouter 格式的模型（預設為空；運行時從你的 hermes 設定解析）
`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。

設定 skip_memory=True 以防止代理讀取或寫入持久化記憶體——推薦用於無狀態 API 端點。

platform 參數（例如 "discord"、"telegram"）會注入平台特定的格式提示，使代理調整其輸出風格。

警告

執行緒安全：為每個執行緒或任務建立一個 AIAgent。永遠不要在並行呼叫之間共享一個實例。

資源清理：代理在對話結束時會自動清理資源（終端會話、瀏覽器實例）。如果你在長生命週期的進程中運行，請確保每個對話正常完成。

迭代限制：預設的 max_iterations=90 是寬鬆的。對於簡單的問答使用場景，考慮降低它（例如 max_iterations=10）以防止失控的工具呼叫迴圈並控制成本。

安裝