程序化集成
Hermes 提供了三种协议，用于从外部程序驱动代理——IDE 插件、自定义 UI、CI 流水线、嵌入式子代理。请根据您的传输方式和使用场景选择最合适的协议。
| 协议 | 传输方式 | 适用场景 | 定义方 |
|---|---|---|---|
| ACP | 通过标准输入输出（stdio）的 JSON-RPC | 已支持 Agent Client Protocol 的 IDE 客户端（如 VS Code、Zed、JetBrains 系列） | acp_adapter/ |
| TUI 网关 | 通过标准输入输出（stdio）或 WebSocket 的 JSON-RPC | 希望对会话、斜杠命令、审批流程、流式事件拥有精细控制的自定义宿主 | tui_gateway/server.py |
| API 服务器 | HTTP + 服务器发送事件（Server-Sent Events） | 兼容 OpenAI 的前端（如 Open WebUI、LobeChat、LibreChat 等）以及语言无关的 Web 客户端 | gateway/platforms/api_server.py |
这三种协议均驱动相同的 AIAgent 核心。它们之间的区别仅在于数据传输格式，以及所暴露的功能集合。
ACP（代理客户端协议）
hermes acp 启动一个基于 stdio 的 JSON-RPC 服务，遵循 ACP 协议。该协议已被生产环境中的 VS Code（Zed Industries 的 ACP 扩展）、Zed，以及任何安装了 ACP 插件的 JetBrains IDE 使用。
支持功能：会话创建、提示提交、代理消息分块流式传输、工具调用事件、权限请求、会话分叉、取消操作及认证。工具输出会被渲染为 IDE 可理解的 ACP Diff/ToolCall 内容块。
完整生命周期、事件桥接与审批流程：ACP 内部机制。
hermes acp # serve ACP on stdio
hermes acp --bootstrap # print install snippet for an ACP-capable 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.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
回传的事件流
message.delta、message.complete、tool.start、tool.progress、tool.complete、approval.request、clarify.request、sudo.request、secret.request、gateway.ready，以及会话生命周期和错误事件。
Pi 风格的 RPC 映射
Pi-mono RPC 规范中每个命令（问题 #360）都有对应的 TUI 网关等价实现：
| Pi 命令 | Hermes 对应项 |
|---|---|
prompt | prompt.submit（或 ACP 中的 session/prompt） |
steer | session.steer |
follow_up | prompt.submit（在当前回合后排队） |
abort | session.interrupt |
set_model | command.dispatch（用于 /model <provider:model>，会话内持久化） |
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 (streaming via SSE)
POST /v1/responses OpenAI Responses API (stateful)
POST /v1/runs Start a run, returns run_id (202)
GET /v1/runs/{id} Run status
GET /v1/runs/{id}/events SSE stream of lifecycle events
POST /v1/runs/{id}/approval Resolve a pending approval
POST /v1/runs/{id}/stop Interrupt the run
GET /v1/capabilities Machine-readable feature flags
GET /v1/models Lists hermes-agent
GET /health, /health/detailed
设置说明、请求头（X-Hermes-Session-Id、X-Hermes-Session-Key），以及前端集成方式：API 服务器。
应该如何选择？
- 您正在编写一个 IDE 插件，且目标 IDE 已支持 ACP → 选择 ACP。无需在 IDE 侧进行额外协议开发。
- 您正在构建自定义桌面/网页/TUI 宿主，并希望使用 Hermes 的全部功能（斜杠命令、审批、澄清、多代理、会话分支）→ 选择 TUI 网关 JSON-RPC。
- 您希望接入任意兼容 OpenAI 的前端、实现语言无关的 HTTP 客户端，或通过 curl 实现自动化 → 选择 API 服务器。
- 您希望在 Python 进程内直接嵌入而无需子进程 → 直接导入
run_agent.AIAgent。详见 代理循环。
模型热切换
会话中动态切换模型在所有接口上均支持——其底层正是 /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
提供者感知的模型解析（同一模型名称会自动适配当前所用提供商的格式）已内置。详情参见 hermes_cli/model_switch.py。
关于 --mode rpc 的说明
Hermes 并未提供 --mode rpc 标志位。上述三种协议已覆盖所有典型使用场景：ACP 用于 IDE 协议客户端，TUI 网关用于 stdio JSON-RPC 宿主，API 服务器用于 HTTP 通信。若您发现某个真实需求无法被其中任一协议满足，请提交 issue 并附上您正在构建的具体消费端实例。