AIAgent 才是 Hermes Agent 的“总调度器”：run_agent.py 在系统里到底负责什么？

一、先给结论AIAgent 不是“大模型”而是“任务总控台”很多人第一次看 Hermes Agent容易把核心误解成“调用某个大模型的代码”。但从官方文档和源码结构看真正的核心不是模型本身而是 run_agent.py 里的 AIAgent。它像一个任务总控台先把用户问题、项目上下文、长期记忆、技能、工具说明组织成模型能理解的输入再选择合适的 Provider/API Mode 调用模型如果模型要求调用工具就调度工具执行如果上下文太长就压缩如果主模型失败就切换备用模型如果任务跑太久就用预算机制刹车。二、普通调用大模型 VS AIAgent 调度 Agent有什么本质区别普通大模型调用通常是“给模型一段文本等模型返回一段文本”。AIAgent 要处理的是“让模型在真实环境里完成任务”它需要读文件、查网页、调用终端、管理会话、记住历史、处理异常、在不同平台展示进度。对比项普通 Chat / LLM APIHermes AIAgent输入用户消息用户消息 系统 Prompt Memory Skills Context Files Tool Schemas输出文本回复文本回复或多轮工具调用后的最终结果执行能力模型只能生成内容AIAgent 调度文件、终端、浏览器、MCP 等工具状态管理通常由外部系统维护AIAgent 维护 OpenAI-style conversation history 和 session容错能力调用失败就报错支持 retry、fallback provider、credential refresh 等成本控制通常靠外部限制IterationBudget、上下文压缩、辅助任务 fallback三、两个入口chat() 是简洁版run_conversation() 是完整版AIAgent 对外有两个主要入口。chat() 更像“省心模式”传入一个问题拿回最终文本run_conversation() 更像“工程模式”它返回包含最终回答、完整消息历史、元数据和使用统计的结构化结果。官方文档也说明chat() 本质上是 run_conversation() 的薄封装只是把 final_response 抽出来返回。这意味着如果你只是把 Hermes 当命令行助手用 chat() 就够如果你要把 Hermes 嵌到 Web 系统、自动化平台、任务平台、企业内部工具中就应该重点看 run_conversation()。四、初始化阶段AIAgent 先把运行时“装备”装好看 run_agent.py 的构造函数会发现 AIAgent 初始化参数非常多。GitHub 的项目说明里也提到真实的 AIAgent.__init__ 大约有 60 个参数覆盖凭证、路由、回调、session context、预算、credential pool 等。这些参数不是“堆功能”而是在描述一个 Agent 运行时需要的所有资源。可以把初始化理解成“任务开始前的装备检查”模型用哪个、工具开哪些、当前平台是谁、会话 ID 是什么、最大循环次数是多少、有没有进度回调、是否跳过记忆和上下文文件。五、run_conversation() 主循环一次任务真正怎么跑起来官方文档把每一轮 Turn Lifecycle 拆成清晰步骤生成 task_id、追加用户消息、构建或复用系统 Prompt、检查是否需要预检压缩、按 API mode 构造消息、注入预算/上下文压力提示、应用缓存标记、发起可中断模型调用、解析模型响应。如果返回 tool_calls就执行工具并把结果追加回历史然后回到构造 API 消息继续循环如果返回文本就持久化 session、刷新 memory 并返回。这套流程说明了一个关键事实Agent 不是“一次模型调用”而是“模型思考 → 工具执行 → 结果回填 → 模型再思考”的循环。AIAgent 就是这个循环的控制器。六、Prompt 组装AIAgent 不是自己写 Prompt而是调度 Prompt BuilderAIAgent 并不是把用户输入原封不动丢给模型。它会通过 prompt_builder.py 组装有效系统提示词把 Memory、Skills、Context Files、Personality、工具 schema 等内容组织起来。官方关键源码文件说明中也把 agent/prompt_builder.py 定义为“从 memory、skills、context files、personality 组装系统提示词”的模块。通俗理解Prompt Builder 负责“把菜配齐”AIAgent 负责“决定什么时候上菜、上给哪个模型、用哪种接口格式”。七、Provider 与 API Mode同一套 Agent要能切换不同模型接口Hermes 不是只绑定一个模型。官方文档说明它支持 chat_completions、codex_responses、anthropic_messages 三种 API 执行模式并按显式 api_mode、provider 检测、base_url 推断、默认 chat_completions 的顺序解析。GitHub README 也强调 Hermes 可以使用 Nous Portal、OpenRouter、OpenAI、Anthropic 或自定义端点并可通过 hermes model 切换模型。这就是 AIAgent 的另一个价值业务层不必关心每个模型厂商的消息格式细节AIAgent 把内部消息统一成 OpenAI-style再按目标 Provider 转换。八、可中断模型调用长任务 Agent 必须允许用户打断官方文档提到API 请求会被包装在 _interruptible_api_call() 里实际 HTTP 调用运行在后台线程主线程监听响应完成、interrupt event 或 timeout。如果用户发送新消息、执行 /stop 或系统信号打断API 线程结果会被丢弃不会把半截回复写进历史。这对真实产品很重要。用户可能在 Agent 跑任务时发现方向错了需要立刻改口如果系统不能打断就会浪费 token、时间和工具调用成本。九、工具执行模型负责“提议”AIAgent 负责“审批与落地”当模型返回 tool_calls 时AIAgent 会解析工具调用单个工具直接执行多个工具可通过 ThreadPoolExecutor 并发执行交互式工具会强制顺序执行结果会按原始 tool_call 顺序重新插回历史。这意味着模型并不是直接操作终端或文件系统它只是提出“我要调用哪个工具、参数是什么”真正的执行由 AIAgent 和工具注册表完成。工具执行链路通常包括从 tools/registry.py 查找 handler、触发 pre_tool_call hook、检查危险命令、等待用户审批、执行 handler、触发 post_tool_call hook、把工具结果追加为 roletool 消息。十、Agent-Level Tools有些工具必须由 AIAgent 自己拦截官方文档特别指出有些工具会被 run_agent.py 在进入普通 handle_function_call() 之前拦截例如 todo、memory、session_search、delegate_task。原因是这些工具会修改 Agent 自身状态todo 读写任务状态memory 写长期记忆session_search 查会话库delegate_task 启动子 Agent。这类设计很关键普通工具更多是“对外部世界做动作”Agent-Level Tools 则是“改变 Agent 自身的运行状态”。所以它们不能完全当作普通外部函数处理。十一、消息历史守门人为什么要维护统一 Message FormatAIAgent 内部统一使用 OpenAI 兼容消息格式system、user、assistant、tool。官方文档还强调消息角色必须严格交替system 后是 User → Assistant → User → Assistant工具调用时是 Assistant(with tool_calls) → Tool → Tool → Assistant不能连续两个 assistant也不能连续两个 user只有 tool 可以连续出现。这个“守门”动作看起来不起眼但非常重要。很多模型供应商会拒绝格式错乱的历史消息工具调用如果不成对回填下一轮模型就可能看不懂自己刚刚做了什么。十二、预算、压缩、FallbackAIAgent 的三套刹车系统能连续行动的 Agent 必须有“刹车”。官方文档说明AIAgent 通过 IterationBudget 跟踪循环次数默认 90 次子 Agent 有独立预算受 delegation.max_iterations 控制预算到 100% 时停止并返回已完成工作的总结。上下文方面AIAgent 在 API 调用前发现会话超过模型上下文 50% 时会触发预检压缩Gateway 层在 85% 时也会更激进地自动压缩。压缩前会先 flush memory然后摘要中间消息、保留最近 N 条消息、保证 tool call/result 成对不被拆开。模型失败方面遇到 429、5xx、401/403 等情况时AIAgent 会检查 fallback_providers按顺序尝试备用 provider/model辅助任务如 vision、compression、web extraction 也可以有独立 fallback 链。十三、Callback Surface为什么同一个 AIAgent 能接 CLI、Gateway、ACPAIAgent 支持多种平台回调例如 tool_progress_callback、thinking_callback、reasoning_callback、clarify_callback、step_callback、stream_delta_callback、tool_gen_callback、status_callback。官方文档说明这些回调用于 CLI、Gateway 和 ACP 集成中的实时进度展示。这也是 Hermes 和普通命令行脚本的区别它不是把结果憋到最后一次性吐出来而是让不同平台能看到“正在思考、正在调用工具、需要澄清、已完成一步、正在流式输出”等状态。十四、持久化与记忆刷新一次任务结束不代表信息丢失官方 Agent Loop 文档说明在每轮结束后消息会保存到 SQLite session store由 hermes_state.py 管理Memory 变更会刷新到 MEMORY.md / USER.md用户之后可以通过 /resume 或 hermes chat --resume 恢复会话。[1] GitHub README 也强调 Hermes 会搜索过去对话、构建跨会话用户模型并通过内置学习闭环创建和改进 skills。所以 AIAgent 不只是把这次请求跑完还要把“这次执行过什么、用户偏好是什么、哪些信息值得长期保存”沉淀下来为下一次任务提供上下文。十五、源码协作关系run_agent.py 很大但不是孤岛官方文档在关键源码文件列表中明确写到run_agent.py 是完整 agent loopagent/prompt_builder.py 负责系统 Prompt 组装agent/context_compressor.py 负责默认有损摘要算法agent/prompt_caching.py 负责 Anthropic prompt cachingagent/auxiliary_client.py 负责视觉、摘要等辅助 LLM 任务model_tools.py 负责工具 schema 收集和 handle_function_call() 调度。因此看源码时不建议从 run_agent.py 第 1 行硬啃到最后。更好的方式是围绕一次任务执行链路顺藤摸瓜去看它调用的模块。十六、推荐源码阅读路线别硬啃按职责切片先看 AIAgent.__init__知道它运行时需要哪些配置、凭证、工具、回调、会话和预算。再看 chat()理解简单入口为什么只是 run_conversation() 的封装。重点看 run_conversation()把官方 9 步 Turn Lifecycle 和源码结构对上。看 Provider/API Mode 解析理解为什么同一个 Agent 能接不同模型。看工具调用处理理解 registry、审批、并发、结果回填。看压缩、Fallback 和预算理解长期任务为什么不容易失控。最后看持久化理解 session、memory、resume 如何让任务跨平台延续。十七、用一句话总结 AIAgentAIAgent 是 Hermes Agent 的“运行时大脑外壳”模型负责生成判断和行动意图AIAgent 负责把意图变成可控、可追踪、可恢复、可压缩、可切换模型、可跨平台延续的真实执行过程。如果你要学习 Hermes Agent 架构run_agent.py 不只是一个文件而是一条主线。沿着它你会看到 Agent 工程最核心的几个问题上下文怎么拼、模型怎么选、工具怎么调、危险动作怎么审批、失败怎么降级、长任务怎么压缩、历史怎么保存、经验怎么沉淀。