Hermes Agent 源碼拆解：一個循環不到 10 行代碼的 Agent 框架，憑什麼自進化？
整理版優先睇
Hermes Agent 靠三層 Prompt 分層設計同簡潔循環實現自進化，值得Agent開發者深入學習
呢篇文章係術哥（一名專注AI編程、智能體、Agent Skills等技術實踐者同開源佈道者）對Hermes Agent源碼嘅深度拆解。佢想幫讀者搞清楚呢個自進化AI Agent框架嘅核心設計，而唔係俾一堆數字嚇親。文章從源碼出發，拆解咗三層Prompt架構、思考-行動循環、工具系統等核心機制，仲一步一步教你點正確配置同運行。
整體嚟講，Hermes Agent嘅設計清晰，分層哲學做得好——系統Prompt分stable/context/volatile三層，提升緩存命中率；核心循環保持簡潔（唔夠10行），能力靠外圍系統組合擴展。呢種工程取捨令到框架既靈活又高效。不過佢嘅門檻都唔低：要求模型至少64K上下文、構造函數有成60個參數、40+工具要按場景裁剪，初次接觸要花時間理解。
文章基於v0.14.0源碼同官方Quickstart分析，未經生產環境全場景驗證，建議讀者自行測試。Hermes Agent適合需要生產部署Agent嘅團隊、想深入理解Agent架構嘅開發者，同埋需要多平台消息網關嘅場景；唔適合輕度用戶或者Agent新手。
- 結論：Hermes Agent 內置學習閉環，從任務經驗提煉可複用 skill，核心係三層 Prompt 分離同思考-行動循環。
- 方法：系統 Prompt 分 stable/context/volatile 三層，穩定部分緩存重用，減少 token 消耗；循環簡潔，能力靠工具系統組合。
- 差異：與其他框架每輪重建 system prompt 唔同，Hermes 分層設計提升緩存命中率；循環邏輯清晰，唔超過10行主代碼。
- 啟發：分層設計值得借鑑，特別係多輪對話系統嘅緩存優化；工具自動發現同按場景裁剪可顯著提升效率。
- 可行動點：用 hermes setup 快速入門；確認模型支援64K上下文；按場景啟用工具集（如只開 web 同 terminal）；生產環境用 Docker 後端確保一致性。
核心機制：三層 Prompt 與思考-行動循環
Hermes Agent 嘅核心唔係某個花哨功能，而係佢嘅分層設計哲學。系統提示詞喺 agent/system_prompt.py 中組裝，分為三層：stable（穩定層）、context（上下文層）、volatile（易變層）。呢個設計嘅核心考量係緩存命中率——系統提示詞喺每個會話中只構建一次並緩存，後續輪次複用，對 LLM 提供商嘅 prefix cache 好友好。
三層 Prompt 架構：stable/context/volatile
緩存命中率提升，減少重複 token 計費
Agent Loop 喺 agent/conversation_loop.py 中實現，核心循環唔夠10行代碼。佢嘅邏輯好清晰：發送消息，檢查有冇工具調用，有就執行並繼續循環，冇就返回最終響應。複雜嘅能力來自主外圍嘅工具系統、提示詞組裝同記憶管理，而唔係循環本身嘅複雜度。
核心循環唔夠10行，能力靠組合擴展
工具自動發現機制：每個 tools/*.py 導入時自動註冊
- 1 max_iterations 默認90，控制工具調用迭代次數上限
- 2 iteration_budget 提供更細粒度嘅預算控制
- 3 _budget_grace_call 允許預算耗盡後額外執行一次，避免任務中途截斷
源碼級快速上手
Hermes Agent 提供三種安裝路徑，適用場景唔同：一鍵安裝、pip 安裝、貢獻者路徑。一鍵安裝器會自動處理 uv、Python 3.11、Node.js、ripgrep、ffmpeg 等依賴，對新手最友好。
一鍵安裝：curl -fsSL ... | bash
- 一鍵安裝：快速體驗，適用於 Linux/macOS/WSL2/Termux
- pip 安裝：已有 Python 環境就用呢個
- 貢獻者路徑：git clone + ./setup-hermes.sh，適合想改源碼嘅人
AIAgent 類喺 run_agent.py 中，構造函數接收約60個參數。日常使用只需要關注兩個接口：agent.chat() 同 agent.run_conversation()。
# 簡單接口：返回最終響應字符串
response = agent.chat("幫我分析呢段代碼嘅性能問題")
# 完整接口：返回 final_response + messages
result = agent.run_conversation(
user_message="分析代碼",
system_message="你係一個代碼審查專家",
conversation_history=[],
task_id="review-001"
)CLI 核心命令：hermes setup 然後 hermes (--tui)
CLI 提供互動式對話同 TUI 界面，hermes setup 係最直接嘅入門方式。如果已經知道用邊個提供商，直接 hermes model 選模型更快。
環境與配置避坑指南
Hermes Agent 嘅配置跟分離原則：密鑰同令牌放 ~/.hermes/.env，非機密設置放 ~/.hermes/config.yaml。呢個分離令 .env 可以 set 嚴格權限（chmod 600），config.yaml 可以加入版本控制共享俾團隊。
密鑰放 .env，非機密放 config.yaml
新手成日遇到64K上下文嘅硬性門檻。Hermes Agent 要求模型至少64,000 tokens，低過呢個值嘅模型喺啟動時會被直接拒絕。如果係本地模型，需要手動設置上下文長度，例如 llama.cpp 用 --ctx-size 65536。
環境變量方面，.env.example 列出咗20+個 LLM 提供商嘅密鑰配置。常用嘅包括 OPENROUTER_API_KEY、GOOGLE_API_KEY、DEEPSEEK_API_KEY，仲有工具密鑰例如 EXA_API_KEY、FIRECRAWL_API_KEY。
先跑 hermes doctor 診斷問題
- 1 空回覆或亂碼：提供商認證或模型選擇錯誤，重跑 hermes model
- 2 自定義端點返回垃圾數據：base URL 錯誤或唔係 OpenAI 兼容，先喺獨立客戶端驗證
- 3 網關啓動但收唔到消息：Bot token 或白名單唔完整，重跑 hermes gateway setup
進階最佳實踐
Prompt 緩存優化可以進一步做：stable 層盡量保持不變，context 層按項目切換，volatile 層交俾框架管理。咁樣可以最大化緩存命中率，減少 token 消耗。
enabled_toolsets 同 disabled_toolsets 精細控制
供應鏈安全方面，Hermes Agent 喺2026年5月經歷咗一次蠕蟲事件，之後所有核心依賴使用精確版本鎖定（==X.Y.Z），mistralai PyPI 包已被隔離移除。呢個做法犧牲咗靈活性但換來安全。
依賴精確版本鎖定，避免供應鏈風險
7種終端後端覆蓋本地開發到雲端部署場景。生產環境推薦 Docker 後端（TERMINAL_ENV=docker），確保團隊行為一致。
- local：本地開發調試，默認選項，零配置
- docker：隔離環境運行，適合 CI/CD 同團隊標準化
- ssh：遠程服務器執行，適合需要特定硬件嘅場景
- modal / daytona / vercel_sandbox：雲端按需執行，按用量計費
- singularity：HPC 環境專用，學術同科研場景
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 119 篇，Hermes Agent 最佳實戰「2026」系列第 2 篇
大家好，歡迎來到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一個專注喺 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫嘅技術實踐者同開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
圖 1：Hermes Agent 核心架構與關鍵數據概覽
Hermes Agent v0.14.0 嘅定位好明確：一個自進化 AI Agent 框架。佢唔係簡單嘅 API 封裝，而係內置咗學習閉環 - 能夠從任務經驗入面提煉出可複用嘅 skill，並喺後續使用中自我修正。
睇咗一圈官方文檔同源碼，發現幾個數字幾搶眼：30+ LLM 提供商、40+ 內置工具、7 種終端後端。但係初次接觸嘅人好容易俾呢啲數字淹沒，連跑個 Quickstart 都可能卡住。
呢篇文章從源碼出發，將 Hermes Agent 嘅核心架構拆清楚，再一步步說明點樣正確配置同運行。
說明：本文內容係基於 Hermes Agent 源碼（NousResearch/hermes-agent）v0.14.0 同官方 Quickstart 文檔分析整理而成，源碼分析係基於筆者本地倉庫版本，尚未喺生產環境完成全場景驗證。文中嘅配置模板同參數建議只係參考，實際效果請以你嘅業務數據同環境測試結果為準。如果有實際使用經驗，歡迎喺評論區分享交流。
1. 核心機制：三層 Prompt 與思考-行動循環
圖 2：System Prompt 三層架構 — stable/context/volatile 分層設計
Hermes Agent 嘅核心唔係某個花巧嘅功能，而係佢嘅分層設計哲學。理解咗呢套設計，後面嘅配置同調試就唔會亂。
System Prompt 三層架構
系統提示詞喺 agent/system_prompt.py 中組裝，分為三層：
stable（穩定層）：Agent 身份（由 SOUL.md 或默認身份定義）、工具使用指導、技能提示、環境提示、平台提示。呢啲內容喺 Agent 生命週期內基本唔變。 context（上下文層）： AGENTS.md、.cursorrules等上下文文件 + 調用方傳入嘅system_message。呢一層隨項目或者場景切換而變化。volatile（易變層）：記憶快照、用戶畫像、外部記憶提供者塊、時間戳/會話/模型/提供商信息。每一輪對話都可能唔同。
呢個設計嘅核心考量係緩存命中率。系統提示詞喺每個會話入面只構建一次並緩存，後續輪次複用 - 對上游 LLM 提供商嘅 prefix cache 友好，可以明顯減少重複 token 嘅計費。
對於做過多輪對話系統嘅開發者嚟講，呢個設計應該唔陌生。好多 Agent 框架每輪都重建完整 system prompt，搞到緩存全部失效。Hermes 將唔變嘅部分（stable）同成日變嘅部分（volatile）分開，呢個係一個值得借鏡嘅工程決策。
Agent Loop：思考-行動循環
圖 3：Agent Loop 思考-行動循環流程
對話循環嘅核心喺 agent/conversation_loop.py（大約 3900 行）。精簡咗之後嘅邏輯如下：
while (api_call_count < self.max_iterations
and self.iteration_budget.remaining > 0) \
or self._budget_grace_call:
if self._interrupt_requested:
break
response = client.chat.completions.create(
model=model,
messages=messages,
tools=tool_schemas
)
if response.tool_calls:
for tool_call in response.tool_calls:
result = handle_function_call(
tool_call.name,
tool_call.args,
task_id
)
messages.append(tool_result_message(result))
api_call_count += 1
else:
return response.content
循環邏輯好清楚：發送消息，檢查有冇工具調用，有就執行並繼續循環，冇就返回最終響應。
有意思嘅係，呢個號稱自帶學習閉環嘅 Agent 框架，核心循環唔夠 10 行代碼。複雜嘅能力嚟自外圍嘅工具系統、提示詞組裝同記憶管理，而唔係循環本身嘅複雜度。呢個係一種刻意嘅設計選擇 - 循環保持簡潔，能力透過組合擴展。
幾個關鍵參數值得留意：
max_iterations默認 90，控制工具調用嘅迭代次數上限iteration_budget提供更細粒嘅預算控制_budget_grace_call允許預算用曬之後額外執行一次，避免任務中途截斷工具調用使用線程池並行執行，上限 8 個 worker
工具自動發現機制
工具系統採用註冊模式。每個 tools/*.py 文件喺導入時會調用 registry.register() 自動註冊，唔需要手動維護工具列表。
model_tools.py 中的 discover_builtin_tools() 觸發發現過程，toolsets.py 定義了 _HERMES_CORE_TOOLS 列表，即所有平台共享嘅基礎工具集，大約 40+ 個工具。工具一定要歸屬於某個 toolset 先至可以被 Agent 使用 - 呢套設計令到工具嘅開關變得好靈活。
核心工具集包括：web（搜索同內容提取）、terminal（命令執行）、file（文件操作）、browser（瀏覽器自動化，13 個工具）、code_execution（Python 腳本執行）、delegation（子代理委派）、skills（技能管理）、memory（持久化記憶）、todo（任務規劃）。
2. 源碼級快速上手
安裝方式對比
Hermes Agent 提供三種安裝路徑，適用場景唔同：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash | ||
pip install hermes-agent && hermes postinstall | ||
git clone./setup-hermes.sh |
一鍵安裝器會自動處理 uv、Python 3.11、Node.js、ripgrep、ffmpeg 等依賴。如果揀貢獻者路徑，源碼目錄結構如下：
hermes-agent/
├── run_agent.py # AIAgent 核心類（~4100 行）
├── model_tools.py # 工具編排層
├── toolsets.py # 工具集定義
├── cli.py # 交互式 CLI（~11k 行）
├── agent/ # Agent 內部模塊
│ ├── system_prompt.py # 系統提示詞組裝
│ ├── conversation_loop.py # 對話循環
│ └── prompt_builder.py # 提示詞構建器
├── tools/ # 工具實現（自動發現）
├── gateway/ # 消息網關
└── plugins/ # 插件系統
AIAgent 核心接口
AIAgent 類在 run_agent.py 中，構造函數接收大約 60 個參數。日常使用只需要留意兩個接口：
# 簡單接口：返回最終響應字符串
response = agent.chat("幫我分析這段代碼的性能問題")
# 完整接口：返回 final_response + messages
result = agent.run_conversation(
user_message="分析代碼",
system_message="你是一個代碼審查專家",
conversation_history=[],
task_id="review-001"
)
構造函數入面幾個關鍵參數：
AIAgent(
base_url=None, # LLM 端點
api_key=None, # API 密鑰
provider=None, # 提供商標識
model="", # 模型名稱
max_iterations=90, # 工具調用迭代上限
enabled_toolsets=None, # 啓用的工具集
disabled_toolsets=None # 禁用的工具集
)
不過大多數情況下唔需要直接構造 AIAgent，CLI 同網關會自動處理初始化。
CLI 核心命令
hermes # 交互式 CLI 對話
hermes --tui # 現代 TUI 界面（推薦）
hermes setup # 一站式配置嚮導
hermes model # 選擇 LLM 提供商和模型
hermes tools # 配置啓用的工具
hermes config set # 設置單個配置項
hermes gateway # 啓動消息網關
hermes doctor # 診斷問題
hermes --continue # 恢復上次會話
按照官方 Quickstart 嘅推薦路徑，hermes setup 然後運行真實聊天驗證響應，係最直接嘅入門方式。如果已經知道要用邊個提供商，直接 hermes model 揀模型更快。
官方文檔仲提供咗一個快速路徑表，按目標揀入口：
hermes setup | ||
hermes model | ||
hermes gateway setup | ||
hermes model |
3. 環境與配置避坑指南
圖 4：配置分離原則 — .env 安全區域 vs config.yaml 共享區域
Hermes Agent 嘅配置遵循分離原則：密鑰同令牌放 ~/.hermes/.env，非機密設定放 ~/.hermes/config.yaml。呢個分離唔係隨便做㗎 - .env 文件可以設定嚴格權限（chmod 600），而 config.yaml 可以加入版本控制分享俾團隊。
三個配置加載器服務於唔同運行場景：
load_cli_config() | cli.py | |
load_config() | hermes_cli/config.py | |
gateway/run.py |
64K 上下文：容易踩嘅硬性門檻
呢個係新手成日遇到嘅問題。Hermes Agent 要求模型至少 64,000 tokens 嘅上下文窗口，低過呢個值嘅模型喺啟動時會直接俾人拒絕。
點解唔設低啲？考慮到系統提示詞三層架構 + 工具 schema + 對話歷史嘅 token 消耗，64K 係一個務實嘅選擇。但代價都好明顯 - 一啲輕量模型同細參數模型直接被排除喺外面。
本地模型需要手動設定上下文長度：
# llama.cpp
./main --ctx-size 65536
# Ollama
ollama run model_name -c 65536
環境變量配置
.env.example 列出咗 20+ 個 LLM 提供商嘅密鑰配置。以下係常用嘅幾個：
# LLM 提供商（選一個即可）
OPENROUTER_API_KEY=sk-or-... # OpenRouter，200+ 模型
GOOGLE_API_KEY=AIza... # Google AI Studio
DEEPSEEK_API_KEY=sk-... # DeepSeek
# 工具密鑰（按需配置）
EXA_API_KEY=... # Exa AI 搜索
FIRECRAWL_API_KEY=... # Firecrawl 爬蟲
# 終端配置
TERMINAL_ENV=local # 後端類型
TERMINAL_TIMEOUT=60 # 命令超時（秒）
你喺項目入面用緊邊啲 LLM 提供商？歡迎喺評論區分享下配置心得。
常見故障排查
遇到問題先跑 hermes doctor，佢會喺終端輸出一個診斷報告。官方文檔提供咗一個完整嘅診斷命令鏈：
hermes doctor
→ hermes model
→ hermes setup
→ hermes sessions list
→ hermes --continue
→ hermes gateway status
常見問題對照表：
hermes model | ||
hermes gateway setup | ||
hermes sessions list |
另外留意 Windows 嘅支持狀態。官方文檔明確標註原生 Windows 仍然係 Early Beta，推薦用 WSL2。如果喺 Windows 上遇到莫名其妙嘅問題，轉去 WSL2 係一個排查方向。
4. 進階最佳實踐
圖 5：9 大核心工具集生態與關係
Prompt 緩存優化策略
之前提到系統提示詞嘅三層架構有緩存考量，實際使用中可以再優化：
stable 層盡量保持唔變。 身份、工具指導呢啲內容一旦確定就唔好成日改。每次修改都會令緩存失效，增加 token 消耗。
context 層按項目切換。AGENTS.md 和 .cursorrules 可以放喺項目根目錄，切換項目時自動生效，唔需要手動更新配置。咁樣比起每次都修改 system_message 參數更加優雅。
volatile 層交俾框架管理。 記憶快照、用戶畫像呢啲內容由框架自動更新，唔需要手動幹預。如果發現上下文膨脹得太快，可以檢查 hermes_state.py 入面嘅 SessionDB（基於 SQLite FTS5）係咪正常壓縮歷史會話。
工具集精細控制
工具並行執行嘅上限係 8 個 worker。喺複雜任務入面，如果 Agent 同時觸發大量工具調用，可能出現資源爭用。透過 enabled_toolsets 和 disabled_toolsets 精細控制：
# 只啓用 Web 搜索和終端工具
agent = AIAgent(
enabled_toolsets=["web", "terminal"]
)
# 禁用瀏覽器自動化（減少 token 消耗）
agent = AIAgent(
disabled_toolsets=["browser"]
)
從源碼嚟睇，各工具集之間係獨立嘅，可以自由組合。但係 delegation（子代理委派）同 code_execution（代碼執行）建議搭配使用 - 子代理執行代碼之後，結果可以被主代理直接利用，形成完整嘅執行-反饋鏈路。
停用唔常用嘅工具集仲有一個隱藏好處：減少發送畀 LLM 嘅 tool schema 體積。每個工具嘅 JSON Schema 都會佔用上下文空間，40+ 工具嘅 schema 加埋唔係細數目。按場景裁剪工具集，等於變相增加咗可用上下文。
供應鏈安全考量
Hermes Agent 喺 2026 年 5 月 12 日經歷咗一次供應鏈安全事件（官方叫 Mini Shai-Hulud 蠕蟲事件），之後採取咗嚴格嘅依賴管理策略。
所有核心依賴使用精確版本鎖定（==X.Y.Z），唔接受版本範圍。mistralai PyPI 包已被隔離移除。呢個做法犧牲咗一啲靈活性，但係從安全角度嚟睇係合理嘅。
如果透過貢獻者路徑安裝，建議喺 git clone 後檢查 pyproject.toml 入面嘅依賴版本，確認冇俾人篡改。pyproject.toml 大約 268 行，核心依賴部分可以快速掃描。
多後端部署建議
7 種終端後端覆蓋咗從本地開發到雲端部署嘅場景：
local：本地開發調試，默認選項，零配置 docker：隔離環境運行，適合 CI/CD 同團隊標準化 ssh：遠程服務器執行，適合需要特定硬件嘅場景 modal / daytona / vercel_sandbox：雲端按需執行，按用量計費 singularity：HPC 環境專用，學術同科研場景
生產環境推薦 Docker 後端，透過 TERMINAL_ENV=docker 配置。本地開發用默認嘅 local 就得。如果團隊有幾個人協作嘅需求，Docker 後端配合統一嘅工具集配置，可以確保每個人跑出嚟嘅行為一致。
總結
Hermes Agent 嘅設計有幾個值得留意嘅點。
分層架構做得清楚。 System Prompt 三層分離、配置文件分離、工具集獨立註冊 - 每一層都有明確嘅職責邊界。呢種設計對調試友好，出問題時可以快速定位到具體層。
但門檻唔算低。 64K 上下文嘅硬性要求、60 個構造參數、40+ 工具嘅組合配置 - 初次接觸確實需要花時間理解。hermes setup 嚮導雖然可以簡化初始化流程，但係理解底層原理先至可以喺遇到問題時快速排查。
適合誰：需要喺生產環境部署 Agent 嘅團隊、想要深入理解 Agent 架構嘅開發者、需要多平台消息網關（Telegram/Discord/Slack）嘅場景。
唔適合邊啲人：只想快速調用 LLM API 嘅輕度用戶、對 Agent 概念唔熟嘅入門者。
從源碼分析嚟睇，Hermes Agent 嘅工程完成度相當高。核心循環保持簡潔，能力透過分層組合擴展，呢個係一個成熟嘅工程選擇。如果你正在評估 Agent 框架，值得花時間跑通佢嘅 Quickstart。
你覺得 Hermes Agent 嘅三層 Prompt 設計對其他 Agent 框架有冇參考價值？歡迎喺評論區講下你嘅諗法。
好啦，多謝你睇我嘅文章，如果鍾意可以點讚轉發俾有需要嘅朋友，我哋下一期再見！敬請期待！
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 119 篇，Hermes Agent 最佳實戰「2026」系列第 2 篇
大家好，歡迎來到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一名專注於 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫的技術實踐者與開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
圖 1：Hermes Agent 核心架構與關鍵數據概覽
Hermes Agent v0.14.0 的定位很明確：一個自進化 AI Agent 框架。它不是簡單的 API 封裝，而是內置了學習閉環 - 能從任務經驗中提煉可複用的 skill，並在後續使用中自我修正。
翻了一圈官方文檔和源碼，發現幾個數字挺扎眼的：30+ LLM 提供商、40+ 內置工具、7 種終端後端。但初次接觸的人很容易被這些數字淹沒，跑個 Quickstart 都可能卡住。
這篇文章從源碼出發，把 Hermes Agent 的核心架構拆清楚，再一步步說明怎麼正確配置和運行。
說明：本文內容基於 Hermes Agent 源碼（NousResearch/hermes-agent）v0.14.0 和官方 Quickstart 文檔分析整理而成，源碼分析基於筆者本地倉庫版本，尚未在生產環境中完成全場景驗證。文中的配置模板和參數建議僅供參考，實際效果請以你的業務數據和環境測試結果為準。如果有實際使用經驗，歡迎在評論區分享交流。
1. 核心機制：三層 Prompt 與思考-行動循環
圖 2：System Prompt 三層架構 — stable/context/volatile 分層設計
Hermes Agent 的核心不是某個花哨的功能，而是它的分層設計哲學。理解了這套設計，後面的配置和調試就不會抓瞎。
System Prompt 三層架構
系統提示詞在 agent/system_prompt.py 中組裝，分為三層：
stable（穩定層）：Agent 身份（由 SOUL.md 或默認身份定義）、工具使用指導、技能提示、環境提示、平台提示。這些內容在 Agent 生命週期內基本不變。 context（上下文層）： AGENTS.md、.cursorrules等上下文文件 + 調用方傳入的system_message。這一層隨項目或場景切換而變化。volatile（易變層）：記憶快照、用戶畫像、外部記憶提供者塊、時間戳/會話/模型/提供商信息。每一輪對話都可能不同。
這個設計的核心考量是緩存命中率。系統提示詞在每個會話中只構建一次並緩存，後續輪次複用 - 對上游 LLM 提供商的 prefix cache 友好，能明顯減少重複 token 的計費。
對於做過多輪對話系統的開發者來說，這個設計應該不陌生。很多 Agent 框架每輪都重建完整 system prompt，導致緩存全部失效。Hermes 把不變的部分（stable）和頻繁變化的部分（volatile）分開，這是一個值得借鑑的工程決策。
Agent Loop：思考-行動循環
圖 3：Agent Loop 思考-行動循環流程
對話循環的核心在 agent/conversation_loop.py（約 3900 行）。精簡後的邏輯如下：
while (api_call_count < self.max_iterations
and self.iteration_budget.remaining > 0) \
or self._budget_grace_call:
if self._interrupt_requested:
break
response = client.chat.completions.create(
model=model,
messages=messages,
tools=tool_schemas
)
if response.tool_calls:
for tool_call in response.tool_calls:
result = handle_function_call(
tool_call.name,
tool_call.args,
task_id
)
messages.append(tool_result_message(result))
api_call_count += 1
else:
return response.content
循環邏輯清晰：發送消息，檢查是否有工具調用，有則執行並繼續循環，沒有則返回最終響應。
有意思的是，這個號稱自帶學習閉環的 Agent 框架，核心循環不到 10 行代碼。複雜的能力來自外圍的工具系統、提示詞組裝和記憶管理，而不是循環本身的複雜度。這是一種刻意的設計選擇 - 循環保持簡潔，能力通過組合擴展。
幾個關鍵參數值得關注：
max_iterations默認 90，控制工具調用的迭代次數上限iteration_budget提供更細粒度的預算控制_budget_grace_call允許預算耗盡後額外執行一次，避免任務中途截斷工具調用使用線程池並行執行，上限 8 個 worker
工具自動發現機制
工具系統採用註冊模式。每個 tools/*.py 文件在導入時調用 registry.register() 自動註冊，不需要手動維護工具列表。
model_tools.py 中的 discover_builtin_tools() 觸發發現過程，toolsets.py 定義了 _HERMES_CORE_TOOLS 列表，即所有平台共享的基礎工具集，約 40+ 個工具。工具必須歸屬於某個 toolset 才能被 Agent 使用 - 這套設計讓工具的啓停變得很靈活。
核心工具集包括：web（搜索和內容提取）、terminal（命令執行）、file（文件操作）、browser（瀏覽器自動化，13 個工具）、code_execution（Python 腳本執行）、delegation（子代理委派）、skills（技能管理）、memory（持久化記憶）、todo（任務規劃）。
2. 源碼級快速上手
安裝方式對比
Hermes Agent 提供三種安裝路徑，適用場景不同：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash | ||
pip install hermes-agent && hermes postinstall | ||
git clone./setup-hermes.sh |
一鍵安裝器會自動處理 uv、Python 3.11、Node.js、ripgrep、ffmpeg 等依賴。如果選擇貢獻者路徑，源碼目錄結構如下：
hermes-agent/
├── run_agent.py # AIAgent 核心類（~4100 行）
├── model_tools.py # 工具編排層
├── toolsets.py # 工具集定義
├── cli.py # 交互式 CLI（~11k 行）
├── agent/ # Agent 內部模塊
│ ├── system_prompt.py # 系統提示詞組裝
│ ├── conversation_loop.py # 對話循環
│ └── prompt_builder.py # 提示詞構建器
├── tools/ # 工具實現（自動發現）
├── gateway/ # 消息網關
└── plugins/ # 插件系統
AIAgent 核心接口
AIAgent 類在 run_agent.py 中，構造函數接收約 60 個參數。日常使用只需要關注兩個接口：
# 簡單接口：返回最終響應字符串
response = agent.chat("幫我分析這段代碼的性能問題")
# 完整接口：返回 final_response + messages
result = agent.run_conversation(
user_message="分析代碼",
system_message="你是一個代碼審查專家",
conversation_history=[],
task_id="review-001"
)
構造函數中幾個關鍵參數：
AIAgent(
base_url=None, # LLM 端點
api_key=None, # API 密鑰
provider=None, # 提供商標識
model="", # 模型名稱
max_iterations=90, # 工具調用迭代上限
enabled_toolsets=None, # 啓用的工具集
disabled_toolsets=None # 禁用的工具集
)
不過大多數情況下不需要直接構造 AIAgent，CLI 和網關會自動處理初始化。
CLI 核心命令
hermes # 交互式 CLI 對話
hermes --tui # 現代 TUI 界面（推薦）
hermes setup # 一站式配置嚮導
hermes model # 選擇 LLM 提供商和模型
hermes tools # 配置啓用的工具
hermes config set # 設置單個配置項
hermes gateway # 啓動消息網關
hermes doctor # 診斷問題
hermes --continue # 恢復上次會話
按照官方 Quickstart 的推薦路徑，hermes setup 然後運行真實聊天驗證響應，是最直接的入門方式。如果已經知道要用哪個提供商，直接 hermes model 選模型更快。
官方文檔還提供了一個快速路徑表，按目標選擇入口：
hermes setup | ||
hermes model | ||
hermes gateway setup | ||
hermes model |
3. 環境與配置避坑指南
圖 4：配置分離原則 — .env 安全區域 vs config.yaml 共享區域
Hermes Agent 的配置遵循分離原則：密鑰和令牌放 ~/.hermes/.env，非機密設置放 ~/.hermes/config.yaml。這個分離不是隨便做的 - .env 文件可以設置嚴格權限（chmod 600），而 config.yaml 可以加入版本控制共享給團隊。
三個配置加載器服務於不同運行場景：
load_cli_config() | cli.py | |
load_config() | hermes_cli/config.py | |
gateway/run.py |
64K 上下文：容易踩的硬性門檻
這是新手遇到頻率很高的問題。Hermes Agent 要求模型至少 64,000 tokens 的上下文窗口，低於這個值的模型在啓動時會被直接拒絕。
為什麼不設低一點？考慮到系統提示詞三層架構 + 工具 schema + 對話歷史的 token 消耗，64K 是一個務實的選擇。但代價也很明顯 - 一些輕量模型和小參數模型直接被排除在外。
本地模型需要手動設置上下文長度：
# llama.cpp
./main --ctx-size 65536
# Ollama
ollama run model_name -c 65536
環境變量配置
.env.example 列出了 20+ 個 LLM 提供商的密鑰配置。以下是常用的幾個：
# LLM 提供商（選一個即可）
OPENROUTER_API_KEY=sk-or-... # OpenRouter，200+ 模型
GOOGLE_API_KEY=AIza... # Google AI Studio
DEEPSEEK_API_KEY=sk-... # DeepSeek
# 工具密鑰（按需配置）
EXA_API_KEY=... # Exa AI 搜索
FIRECRAWL_API_KEY=... # Firecrawl 爬蟲
# 終端配置
TERMINAL_ENV=local # 後端類型
TERMINAL_TIMEOUT=60 # 命令超時（秒）
你在項目中用的是哪些 LLM 提供商？歡迎在評論區聊聊配置心得。
常見故障排查
遇到問題先跑 hermes doctor，它會在終端輸出一份診斷報告。官方文檔提供了一個完整的診斷命令鏈：
hermes doctor
→ hermes model
→ hermes setup
→ hermes sessions list
→ hermes --continue
→ hermes gateway status
常見問題對照表：
hermes model | ||
hermes gateway setup | ||
hermes sessions list |
另外注意 Windows 的支持狀態。官方文檔明確標註原生 Windows 仍為 Early Beta，推薦使用 WSL2。如果在 Windows 上遇到莫名其妙的問題，切換到 WSL2 是排查方向。
4. 進階最佳實踐
圖 5：9 大核心工具集生態與關係
Prompt 緩存優化策略
前面提到系統提示詞的三層架構有緩存考量，實際使用中可以進一步優化：
stable 層儘量保持不變。 身份、工具指導這些內容一旦確定就不要頻繁修改。每次修改都會導致緩存失效，增加 token 消耗。
context 層按項目切換。AGENTS.md 和 .cursorrules 可以放在項目根目錄，切換項目時自動生效，不需要手動更新配置。這比每次都修改 system_message 參數要優雅。
volatile 層交給框架管理。 記憶快照、用戶畫像這些內容由框架自動更新，不需要手動干預。如果發現上下文膨脹過快，可以檢查 hermes_state.py 中的 SessionDB（基於 SQLite FTS5）是否正常壓縮歷史會話。
工具集精細控制
工具並行執行的上限是 8 個 worker。在複雜任務中，如果 Agent 同時觸發大量工具調用，可能出現資源爭用。通過 enabled_toolsets 和 disabled_toolsets 精細控制：
# 只啓用 Web 搜索和終端工具
agent = AIAgent(
enabled_toolsets=["web", "terminal"]
)
# 禁用瀏覽器自動化（減少 token 消耗）
agent = AIAgent(
disabled_toolsets=["browser"]
)
從源碼來看，各工具集之間是獨立的，可以自由組合。但 delegation（子代理委派）和 code_execution（代碼執行）建議搭配使用 - 子代理執行代碼後，結果能被主代理直接利用，形成完整的執行-反饋鏈路。
禁用不常用的工具集還有一個隱性好處：減少發送給 LLM 的 tool schema 體積。每個工具的 JSON Schema 都會佔用上下文空間，40+ 工具的 schema 加起來不是小數目。按場景裁剪工具集，等於變相增加了可用上下文。
供應鏈安全考量
Hermes Agent 在 2026 年 5 月 12 日經歷了一次供應鏈安全事件（官方稱為 Mini Shai-Hulud 蠕蟲事件），之後採取了嚴格的依賴管理策略。
所有核心依賴使用精確版本鎖定（==X.Y.Z），不接受版本範圍。mistralai PyPI 包已被隔離移除。這個做法犧牲了一些靈活性，但從安全角度看是合理的。
如果通過貢獻者路徑安裝，建議在 git clone 後檢查 pyproject.toml 中的依賴版本，確認沒有被篡改。pyproject.toml 約 268 行，核心依賴部分可以快速掃描。
多後端部署建議
7 種終端後端覆蓋了從本地開發到雲端部署的場景：
local：本地開發調試，默認選項，零配置 docker：隔離環境運行，適合 CI/CD 和團隊標準化 ssh：遠程服務器執行，適合需要特定硬件的場景 modal / daytona / vercel_sandbox：雲端按需執行，按用量計費 singularity：HPC 環境專用，學術和科研場景
生產環境推薦 Docker 後端，通過 TERMINAL_ENV=docker 配置。本地開發用默認的 local 即可。如果團隊有多人協作的需求，Docker 後端配合統一的工具集配置，能確保每個人跑出來的行為一致。
總結
Hermes Agent 的設計有幾個值得關注的點。
分層架構做得清晰。 System Prompt 三層分離、配置文件分離、工具集獨立註冊 - 每一層都有明確的職責邊界。這種設計對調試友好，出問題時能快速定位到具體層。
但門檻不算低。 64K 上下文的硬性要求、60 個構造參數、40+ 工具的組合配置 - 初次接觸確實需要花時間理解。hermes setup 嚮導雖然能簡化初始化流程，但理解底層原理才能在遇到問題時快速排查。
適合誰：需要在生產環境部署 Agent 的團隊、想要深入理解 Agent 架構的開發者、需要多平台消息網關（Telegram/Discord/Slack）的場景。
不適合誰：只想快速調用 LLM API 的輕度用戶、對 Agent 概念不熟悉的入門者。
從源碼分析來看，Hermes Agent 的工程完成度相當高。核心循環保持簡潔，能力通過分層組合擴展，這是一個成熟的工程選擇。如果你在評估 Agent 框架，值得花時間跑通它的 Quickstart。
你覺得 Hermes Agent 的三層 Prompt 設計對其他 Agent 框架有沒有參考價值？歡迎在評論區聊聊你的看法。
好啦，謝謝你觀看我的文章，如果喜歡可以點贊轉發給需要的朋友，我們下一期再見！敬請期待！