Hermes 提供三種協定用於從外部程式驅動代理程式 — IDE 外掛、自訂 UI、CI 管線、嵌入式子代理程式。選擇符合你的傳輸層和消費者的協定。
| 協定 | 傳輸層 | 最適用於 | 定義位置 |
|---|---|---|---|
| ACP | JSON-RPC over stdio | 已支援 Agent Client Protocol 的 IDE 客戶端（VS Code、Zed、JetBrains） | acp_adapter/ |
| TUI 閘道器 | JSON-RPC over stdio（或 WebSocket） | 想要精細控制 session、斜線命令、核准和串流事件的自訂主機 | tui_gateway/server.py |
| API 伺服器 | HTTP + Server-Sent Events | OpenAI 相容的前端（Open WebUI、LobeChat、LibreChat…）和語言無關的 web 客戶端 | gateway/platforms/api_server.py |
三者驅動相同的 AIAgent 核心。它們只在線格式和暴露的功能集上有差異。
ACP（Agent Client Protocol）
hermes acp 啟動一個 stdio JSON-RPC 伺服器，實作 ACP 協定。在生產環境中被 VS Code（Zed Industries 的 ACP 擴充套件）、Zed 和任何帶有 ACP 外掛的 JetBrains IDE 使用。
暴露的功能：session 建立、提示詞提交、串流代理程式訊息區塊、工具呼叫事件、權限請求、session 分支、取消和認證。工具輸出會渲染為 IDE 能理解的 ACP Diff/ToolCall 內容區塊。
完整生命週期、事件橋接器和核准流程：ACP Internals。
hermes acp # 在 stdio 上提供 ACP 服務
hermes acp --bootstrap # 列印適用於支援 ACP 的 IDE 的安裝片段
TUI 閘道器 JSON-RPC
tui_gateway/server.py 是 Ink TUI（hermes --tui）和嵌入式儀表板 PTY 橋接器使用的協定。任何外部主機都可以透過 stdio（或透過 tui_gateway/ws.py 的 WebSocket）說相同的協定。
方法目錄（精選）
prompt.submit prompt.background session.steer
session.create session.list session.active_list
session.activate session.close session.interrupt
session.history session.compress session.branch
session.title session.usage session.status
clarify.respond sudo.respond secret.respond
approval.respond config.set / config.get commands.catalog
command.resolve command.dispatch cli.exec
reload.mcp reload.env process.stop
delegation.status subagent.interrupt spawn_tree.save / list / load
terminal.resize clipboard.paste image.attach
session.active_list、session.activate 和 session.close 是 TUI session 切換器使用的進程內即時 session 控制。使用 session.list / /resume 進行已儲存對話記錄的發現；只對目前在 TUI 閘道器進程中開啟的 session 使用即時 session 方法。
串流回傳的事件
message.delta、message.complete、tool.start、tool.progress、tool.complete、approval.request、clarify.request、sudo.request、secret.request、gateway.ready，以及 session 生命週期和錯誤事件。
Pi 風格的 RPC 對應
Pi-mono RPC 規範（issue #360）中的每個命令都有一個 TUI 閘道器對應項：
| Pi 命令 | Hermes 對應 |
|---|---|
prompt | prompt.submit（或 ACP session/prompt） |
steer | session.steer |
follow_up | 在當前回合後排隊的 prompt.submit |
abort | session.interrupt |
set_model | 用於 /model <provider:model> 的 command.dispatch（中間 session，持久） |
compact | session.compress |
get_state | session.status |
get_messages | session.history |
switch_session | session.resume |
fork | session.branch |
ui_request / ui_response | clarify.respond / sudo.respond / secret.respond / approval.respond |
OpenAI 相容的 API 伺服器
gateway/platforms/api_server.py 透過 HTTP 暴露 hermes，供任何已支援 OpenAI 格式的客戶端使用。適用於需要 web 前端、curl 驅動的 CI 運行器或非 Python 消費者時。
端點：
POST /v1/chat/completions OpenAI Chat Completions（透過 SSE 串流）
POST /v1/responses OpenAI Responses API（有狀態）
POST /v1/runs 啟動運行，回傳 run_id（202）
GET /v1/runs/{id} 運行狀態
GET /v1/runs/{id}/events 生命週期事件的 SSE 串流
POST /v1/runs/{id}/approval 解決待處理的核准
POST /v1/runs/{id}/stop 中斷運行
GET /v1/capabilities 機器可讀的功能標誌
GET /v1/models 列出 hermes-agent
GET /health, /health/detailed
設定、標頭（X-Hermes-Session-Id、X-Hermes-Session-Key）和前端連線：API Server。
我應該使用哪個？
- 你在寫 IDE 外掛且 IDE 已支援 ACP → ACP。IDE 端零協定工作。
- 你在寫自訂桌面 / web / TUI 主機且想要所有 Hermes 功能（斜線命令、核准、澄清、多代理、session 分支）→ TUI 閘道器 JSON-RPC。
- 你想要任何 OpenAI 相容的前端、語言無關的 HTTP 客戶端或 curl 驅動的自動化 → API 伺服器。
- 你想要 Python 進程內嵌入而不需要子程序 → 直接匯入
run_agent.AIAgent。請見 Agent Loop。
模型熱切換
中間 session 模型切換在每個介面上都能運作 — 底層是 /model 斜線命令。
- CLI / TUI：
/model claude-sonnet-4或/model openrouter:anthropic/claude-sonnet-4.6 - TUI 閘道器 RPC：
command.dispatch搭配{"command": "/model claude-sonnet-4"} - ACP： IDE 將斜線命令作為提示詞發送；代理程式進行分派
- API 伺服器： 在請求體中包含
model欄位或設定X-Hermes-Model
Provider 感知的解析（相同的模型名稱在你使用的任何 provider 上選擇正確的格式）是內建的。請見 hermes_cli/model_switch.py。
關於 --mode rpc 的說明
Hermes 沒有 --mode rpc 旗標。上述三種協定已經涵蓋了使用場景 — ACP 用於 IDE 協定客戶端，TUI 閘道器用於 stdio JSON-RPC 主機，API 伺服器用於 HTTP。如果你發現它們都無法填補的真實缺口，請提出一個包含你正在建構的具體消費者的 issue。