官方文档提供对于python库来集成的说明可以很方便的集成hermes agent来实现对应逻辑。

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",
    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 存储在 agent 实例上用于 VM 隔离,不会在返回字典中回显。)

你也可以传入自定义系统消息,覆盖该次调用的临时系统 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 可访问的工具集: 

提示  当你需要一个功能最小化、受限的 agent 时(例如,仅用于研究机器人的 Web 搜索),使用 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 记住了上下文
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 的形式追加写入,便于从自动化运行中收集数据集。


自定义系统 Prompt

使用 ephemeral_system_prompt 设置自定义系统 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 助手——全部使用相同的底层工具。


批量处理

如需并行运行大量 prompt,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):
    # 每个任务创建一个新的 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 自定义系统 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),以防止工具调用循环失控并控制成本。

总结一下:可以通过引入源码的方式,将agent集成到业务逻辑中去

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

result1 = agent.run_conversation("My name is Alice")

由于hermes版本更新很快,AIAgent的函数说明按照最新源码重新学习下,参数很多,源码如下:

AIAgent初始化

def init_agent(
    agent,
    base_url: str = None,
    api_key: str = None,
    provider: str = None,
    api_mode: str = None,
    acp_command: str = None,
    acp_args: list[str] | None = None,
    command: str = None,
    args: list[str] | None = None,
    model: str = "",
    max_iterations: int = 90,  # Default tool-calling iterations (shared with subagents)
    tool_delay: float = 1.0,
    enabled_toolsets: List[str] = None,
    disabled_toolsets: List[str] = None,
    save_trajectories: bool = False,
    verbose_logging: bool = False,
    quiet_mode: bool = False,
    ephemeral_system_prompt: str = None,
    log_prefix_chars: int = 100,
    log_prefix: str = "",
    providers_allowed: List[str] = None,
    providers_ignored: List[str] = None,
    providers_order: List[str] = None,
    provider_sort: str = None,
    provider_require_parameters: bool = False,
    provider_data_collection: str = None,
    openrouter_min_coding_score: Optional[float] = None,
    session_id: str = None,
    tool_progress_callback: callable = None,
    tool_start_callback: callable = None,
    tool_complete_callback: callable = None,
    thinking_callback: callable = None,
    reasoning_callback: callable = None,
    clarify_callback: callable = None,
    step_callback: callable = None,
    stream_delta_callback: callable = None,
    interim_assistant_callback: callable = None,
    tool_gen_callback: callable = None,
    status_callback: callable = None,
    notice_callback: callable = None,
    notice_clear_callback: callable = None,
    max_tokens: int = None,
    reasoning_config: Dict[str, Any] = None,
    service_tier: str = None,
    request_overrides: Dict[str, Any] = None,
    prefill_messages: List[Dict[str, Any]] = None,
    platform: str = None,
    user_id: str = None,
    user_id_alt: str = None,
    user_name: str = None,
    chat_id: str = None,
    chat_name: str = None,
    chat_type: str = None,
    thread_id: str = None,
    gateway_session_key: str = None,
    skip_context_files: bool = False,
    load_soul_identity: bool = False,
    skip_memory: bool = False,
    session_db=None,
    parent_session_id: str = None,
    iteration_budget: "IterationBudget" = None,
    fallback_model: Dict[str, Any] = None,
    credential_pool=None,
    checkpoints_enabled: bool = False,
    checkpoint_max_snapshots: int = 20,
    checkpoint_max_total_size_mb: int = 500,
    checkpoint_max_file_size_mb: int = 10,
    pass_session_id: bool = False,
):
    """
    Initialize the AI Agent.

    Args:
        base_url (str): Base URL for the model API (optional)
        api_key (str): API key for authentication (optional, uses env var if not provided)
        provider (str): Provider identifier (optional; used for telemetry/routing hints)
        api_mode (str): API mode override: "chat_completions" or "codex_responses"
        model (str): Model name to use (default: "anthropic/claude-opus-4.6")
        max_iterations (int): Maximum number of tool calling iterations (default: 90)
        tool_delay (float): Delay between tool calls in seconds (default: 1.0)
        enabled_toolsets (List[str]): Only enable tools from these toolsets (optional)
        disabled_toolsets (List[str]): Disable tools from these toolsets (optional)
        save_trajectories (bool): Whether to save conversation trajectories to JSONL files (default: False)
        verbose_logging (bool): Enable verbose logging for debugging (default: False)
        quiet_mode (bool): Suppress progress output for clean CLI experience (default: False)
        ephemeral_system_prompt (str): System prompt used during agent execution but NOT saved to trajectories (optional)
        log_prefix_chars (int): Number of characters to show in log previews for tool calls/responses (default: 100)
        log_prefix (str): Prefix to add to all log messages for identification in parallel processing (default: "")
        providers_allowed (List[str]): OpenRouter providers to allow (optional)
        providers_ignored (List[str]): OpenRouter providers to ignore (optional)
        providers_order (List[str]): OpenRouter providers to try in order (optional)
        provider_sort (str): Sort providers by price/throughput/latency (optional)
        openrouter_min_coding_score (float): Coding-score floor (0.0-1.0) for the
            openrouter/pareto-code router. Only applied when model == "openrouter/pareto-code".
            None or empty = let OpenRouter pick the strongest available coder.
        session_id (str): Pre-generated session ID for logging (optional, auto-generated if not provided)
        tool_progress_callback (callable): Callback function(tool_name, args_preview) for progress notifications
        clarify_callback (callable): Callback function(question, choices) -> str for interactive user questions.
            Provided by the platform layer (CLI or gateway). If None, the clarify tool returns an error.
        max_tokens (int): Maximum tokens for model responses (optional, uses model default if not set)
        reasoning_config (Dict): OpenRouter reasoning configuration override (e.g. {"effort": "none"} to disable thinking).
            If None, defaults to {"enabled": True, "effort": "medium"} for OpenRouter. Set to disable/customize reasoning.
        prefill_messages (List[Dict]): Messages to prepend to conversation history as prefilled context.
            Useful for injecting a few-shot example or priming the model's response style.
            Example: [{"role": "user", "content": "Hi!"}, {"role": "assistant", "content": "Hello!"}]
            NOTE: Anthropic Sonnet 4.6+ and Opus 4.6+ reject a conversation that ends on an
            assistant-role message (400 error).  For those models use structured outputs or
            output_config.format instead of a trailing-assistant prefill.
        platform (str): The interface platform the user is on (e.g. "cli", "telegram", "discord", "whatsapp").
            Used to inject platform-specific formatting hints into the system prompt.
        skip_context_files (bool): If True, skip auto-injection of SOUL.md, AGENTS.md, and .cursorrules
            into the system prompt. Use this for batch processing and data generation to avoid
            polluting trajectories with user-specific persona or project instructions.
        load_soul_identity (bool): If True, still use ~/.hermes/SOUL.md as the primary
            identity even when skip_context_files=True. Project context files from the cwd
            remain skipped.
    """

以下是 init_agent 函数的入参分析,按功能分组,每个参数的具体作用基于代码中的文档字符串和常见实践解释:


一、API 连接与认证

参数 作用
base_url 模型 API 的基础 URL,用于连接非默认或自定义的 API 端点。可选。
api_key API 认证密钥。若不提供,通常从环境变量获取。可选。
provider 提供商标识符(如 "openrouter", "anthropic"),用于遥测或路由提示。可选。
api_mode API 模式覆盖:可选 "chat_completions"(标准对话)或 "codex_responses"(代码型响应)。
acp_command / acp_args (推测)与 ACP(Agent Communication Protocol)相关的外部命令及参数,用于启动子进程代理。
command / args 直接指定本地命令及其参数,用于运行外部工具或自定义代理。
model 模型名称,例如 "anthropic/claude-opus-4.6"。默认值为空字符串(可能由内部选择)。
max_tokens 模型响应的最大 token 数。若不指定,使用模型默认值。
service_tier 服务层级(如标准版、专业版),用于控制响应质量或速率限制。可选。
request_overrides 请求级别的覆盖设置,字典形式,可修改每次 API 调用的参数。

二、行为控制

参数 作用
max_iterations 最大工具调用迭代次数(默认 90)。也用于子代理(subagents)。
tool_delay 连续工具调用之间的延迟时间(秒,默认 1.0),避免过快请求。
enabled_toolsets 仅启用指定的工具集列表(如 ["filesystem", "web"]),其他工具集被禁用。
disabled_toolsets 禁用指定的工具集列表。若同时设置,enabled 优先级更高。
save_trajectories 是否将对话轨迹保存为 JSONL 文件(默认 False),用于事后分析或调试。
verbose_logging 是否启用详细日志(默认 False),用于深度调试。
quiet_mode 是否抑制进度输出(默认 False),适合需要干净 CLI 输出的场景。
ephemeral_system_prompt 临时系统提示,仅在本次代理执行期间生效,不会保存到轨迹文件中。
log_prefix_chars 在工具调用/响应的日志预览中显示的字符数(默认 100)。
log_prefix 添加到所有日志消息的前缀,用于并行处理中区分不同代理实例。
skip_context_files 若为 True,跳过自动注入 SOUL.mdAGENTS.md.cursorrules 等上下文文件到系统提示,适合批处理/数据生成场景。
load_soul_identity 若为 True,即使 skip_context_files=True,仍加载 ~/.hermes/SOUL.md 作为主要身份标识,但跳过项目级上下文文件。
skip_memory 若为 True,跳过记忆加载(如长期记忆模块),使代理为无状态模式。
iteration_budget 迭代预算对象(IterationBudget),用于更精细地控制迭代次数或成本限制。
checkpoints_enabled 是否启用检查点(快照)功能,允许从中间状态恢复(默认 False)。
checkpoint_max_snapshots 最多保留的快照数量(默认 20)。
checkpoint_max_total_size_mb 检查点总大小上限 MB(默认 500)。
checkpoint_max_file_size_mb 单个检查点文件大小上限 MB(默认 10)。
pass_session_id 是否将 session_id 传递给子代理或下游调用(默认 False)。

三、OpenRouter 专用参数(模型路由与筛选)

参数 作用
providers_allowed 允许的 OpenRouter 提供商列表(如 ["openai", "anthropic"])。
providers_ignored 忽略的 OpenRouter 提供商列表。
providers_order 指定 OpenRouter 提供商的尝试顺序(优先使用列表靠前的)。
provider_sort 按价格、吞吐量或延迟排序提供商(如 "price""latency")。
provider_require_parameters 是否要求提供商必须有完整参数配置才能使用(默认 False)。
provider_data_collection 控制数据收集策略(例如是否允许模型训练使用数据),具体值待查。
openrouter_min_coding_score 当使用 openrouter/pareto-code 模型时,设置最低编程能力分数(0.0-1.0),低于此分数的提供商被排除。
reasoning_config OpenRouter 推理配置覆盖,例如 {"effort": "none"} 禁用思考过程。若为 None,默认启用中等努力推理。
fallback_model 当主模型失败时使用的备选模型配置(字典形式,如 {"model": "...", "provider": "..."})。

四、回调函数(事件钩子)

参数 作用
tool_progress_callback 工具调用进度通知,签名 callback(tool_name, args_preview)
tool_start_callback 工具开始执行时的回调。
tool_complete_callback 工具执行完成时的回调。
thinking_callback 模型“思考”过程(如链式推理)的回调。
reasoning_callback 模型推理步骤的回调(与 thinking 可能重叠)。
clarify_callback 当代理需要向用户提问澄清时调用,接收 (question, choices) 并返回用户答案。若无此回调,clarify 工具会报错。
step_callback 每个执行步骤完成后的回调(如一轮用户输入+工具调用)。
stream_delta_callback 流式响应中每个数据块(delta)的回调。
interim_assistant_callback 中间助手消息的回调(例如在工具调用前生成的文本)。
tool_gen_callback 工具生成(如动态定义工具)时的回调。
status_callback 状态更新回调(如“正在思考”、“正在调用工具”)。
notice_callback 发送通知消息的回调(如警告、非错误提示)。
notice_clear_callback 清除之前通知的回调。

五、元数据与会话标识

参数 作用
session_id 预生成的会话 ID,用于日志和轨迹跟踪。若不提供,自动生成。
parent_session_id 父会话 ID,用于关联子代理或嵌套对话。
platform 用户所在的平台(如 "cli""telegram""discord"),用于注入平台特定的格式化提示。
user_id 用户唯一标识符(如数据库 ID)。
user_id_alt 备用用户标识符(如匿名 ID)。
user_name 用户显示名称。
chat_id 聊天会话的唯一 ID(适用于群聊场景)。
chat_name 聊天名称。
chat_type 聊天类型(如 "private""group""channel")。
thread_id 线程 ID(用于区分同一聊天中的不同话题分支)。
gateway_session_key 网关会话密钥(可能用于认证或路由)。
session_db 会话数据库连接对象(用于持久化会话状态)。
credential_pool 凭证池对象(管理多个 API 密钥或用户凭证)。

六、其他

参数 作用
prefill_messages 预填充到对话历史的消息列表(如 [{"role": "user", "content": "Hi!"}])。注意:某些模型(如 Anthropic Sonnet 4.6+)若最后一条消息是 assistant,会报 400 错误,此时应使用结构输出代替。
agent 第一个参数,通常是一个代理实例或配置对象。文档未详细说明,推测为待初始化的 Agent 对象。

发起对话

def run_conversation(
    agent,
    user_message: str,
    system_message: str = None,
    conversation_history: List[Dict[str, Any]] = None,
    task_id: str = None,
    stream_callback: Optional[callable] = None,
    persist_user_message: Optional[str] = None,
) -> Dict[str, Any]:
    """
    Run a complete conversation with tool calling until completion.

    Args:
        user_message (str): The user's message/question
        system_message (str): Custom system message (optional, overrides ephemeral_system_prompt if provided)
        conversation_history (List[Dict]): Previous conversation messages (optional)
        task_id (str): Unique identifier for this task to isolate VMs between concurrent tasks (optional, auto-generated if not provided)
        stream_callback: Optional callback invoked with each text delta during streaming.
            Used by the TTS pipeline to start audio generation before the full response.
            When None (default), API calls use the standard non-streaming path.
        persist_user_message: Optional clean user message to store in
            transcripts/history when user_message contains API-only
            synthetic prefixes.
                or queuing follow-up prefetch work.

    Returns:
        Dict: Complete conversation result with final response and message history
    """

参数详解

参数 类型 作用
agent (通常为已初始化的 Agent 实例) 必填。代表已经通过 init_agent 或其他方式创建好的 AI 代理对象。该对象内部包含了模型配置、工具集、回调函数、会话状态等。run_conversation 会在这个 agent 实例上执行对话逻辑。
user_message str 必填。用户发送的消息或问题。这是对话的输入起点。
system_message str 可选。自定义系统消息。如果提供,它会覆盖 agent 创建时设置的 ephemeral_system_prompt 或默认系统提示。用于临时调整代理的角色、行为规则或上下文。
conversation_history List[Dict[str, Any]] 可选。之前的对话消息历史。格式通常为 OpenAI 风格的消息列表,每个元素包含 role(如 "user""assistant""tool")和 content 等字段。传入历史可以让代理“记住”之前的交互,实现多轮对话。如果不提供,则视为全新对话。
task_id str 可选。任务的唯一标识符。主要用于隔离不同任务之间的资源(如虚拟机 VM 环境),避免并发任务互相干扰。例如,当多个会话同时运行时,每个任务有自己的临时文件空间或沙箱。如果不提供,通常会自动生成一个 UUID。
stream_callback Optional[callable] 可选。流式回调函数,在模型逐词生成文本块(delta)时被调用。典型用途是与 TTS(文本转语音)管道集成,在完整响应尚未生成完毕时就开始合成语音,从而降低延迟。当 stream_callback 为 None(默认)时,API 调用走标准的非流式路径,一次性返回完整响应。
persist_user_message Optional[str] 可选。用于存储到对话记录/历史中的“干净”用户消息。当 user_message 参数中包含了仅用于 API 调用的合成前缀(例如某些代理会在用户消息前添加 "<user_said>" 等标记)时,可以使用 persist_user_message 提供一个更友好、无标记的版本存入日志或数据库。这避免了记录中被污染的内容。

返回值

  • Dict[str, Any]:包含完整对话结果,通常含有最终响应文本、完整的消息历史、工具调用记录等。具体结构取决于实现,但常见字段包括:

    • "response": 最终助手的回复文本。

    • "messages": 更新后的完整对话历史列表。

    • "usage": token 使用统计(可选)。

    • "iterations": 实际迭代次数(可选)。

更多推荐