mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-18 04:41:56 +00:00
afb97dbc53
Document the three protocols already available for driving hermes-agent from external programs — ACP, the TUI gateway JSON-RPC, and the OpenAI-compatible API server — with a 'which one should I use' guide and a Pi-style RPC command mapping table. Sidebar entry under Developer Guide -> Architecture.
126 lines
6.2 KiB
Markdown
126 lines
6.2 KiB
Markdown
---
|
|
sidebar_position: 8
|
|
title: "Programmatic Integration"
|
|
description: "Three protocols for driving hermes-agent from external programs: ACP, the TUI gateway JSON-RPC, and the OpenAI-compatible HTTP API"
|
|
---
|
|
|
|
# Programmatic Integration
|
|
|
|
Hermes ships three protocols for driving the agent from external programs — IDE plugins, custom UIs, CI pipelines, embedded sub-agents. Pick the one that matches your transport and consumer.
|
|
|
|
| Protocol | Transport | Best for | Defined by |
|
|
|----------|-----------|----------|------------|
|
|
| **ACP** | JSON-RPC over stdio | IDE clients (VS Code, Zed, JetBrains) that already speak the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) | `acp_adapter/` |
|
|
| **TUI gateway** | JSON-RPC over stdio (or WebSocket) | Custom hosts that want fine-grained control of sessions, slash commands, approvals, and streaming events | `tui_gateway/server.py` |
|
|
| **API server** | HTTP + Server-Sent Events | OpenAI-compatible frontends (Open WebUI, LobeChat, LibreChat…) and language-agnostic web clients | `gateway/platforms/api_server.py` |
|
|
|
|
All three drive the same `AIAgent` core. They differ only in wire format and which set of features they expose.
|
|
|
|
---
|
|
|
|
## ACP (Agent Client Protocol)
|
|
|
|
`hermes acp` starts a stdio JSON-RPC server speaking ACP. Used in production by VS Code (Zed Industries' ACP extension), Zed, and any JetBrains IDE with an ACP plugin.
|
|
|
|
Capabilities exposed: session creation, prompt submission, streaming agent message chunks, tool-call events, permission requests, session fork, cancel, and authentication. Tool output is rendered into ACP `Diff`/`ToolCall` content blocks the IDE understands.
|
|
|
|
Full lifecycle, event bridge, and approval flow: [ACP Internals](./acp-internals).
|
|
|
|
```bash
|
|
hermes acp # serve ACP on stdio
|
|
hermes acp --bootstrap # print install snippet for an ACP-capable IDE
|
|
```
|
|
|
|
---
|
|
|
|
## TUI Gateway JSON-RPC
|
|
|
|
`tui_gateway/server.py` is the protocol the Ink TUI (`hermes --tui`) and the embedded dashboard PTY bridge talk to. Any external host can speak the same protocol over stdio (or WebSocket via `tui_gateway/ws.py`).
|
|
|
|
### Method catalog (selected)
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
### Events streamed back
|
|
|
|
`message.delta`, `message.complete`, `tool.start`, `tool.progress`, `tool.complete`, `approval.request`, `clarify.request`, `sudo.request`, `secret.request`, `gateway.ready`, plus session lifecycle and error events.
|
|
|
|
### Pi-style RPC mapping
|
|
|
|
Every command in the Pi-mono RPC spec ([issue #360](https://github.com/NousResearch/hermes-agent/issues/360)) has a TUI-gateway equivalent:
|
|
|
|
| Pi command | Hermes equivalent |
|
|
|------------|-------------------|
|
|
| `prompt` | `prompt.submit` (or ACP `session/prompt`) |
|
|
| `steer` | `session.steer` |
|
|
| `follow_up` | `prompt.submit` queued after current turn |
|
|
| `abort` | `session.interrupt` |
|
|
| `set_model` | `command.dispatch` for `/model <provider:model>` (mid-session, persistent) |
|
|
| `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-Compatible API Server
|
|
|
|
`gateway/platforms/api_server.py` exposes hermes over HTTP for any client that already speaks the OpenAI format. Useful when you want a web frontend, a curl-driven CI runner, or a non-Python consumer.
|
|
|
|
Endpoints:
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
Setup, headers (`X-Hermes-Session-Id`, `X-Hermes-Session-Key`), and frontend wiring: [API Server](../user-guide/features/api-server).
|
|
|
|
---
|
|
|
|
## Which one should I use?
|
|
|
|
- **You're writing an IDE plugin and the IDE already speaks ACP** → ACP. Zero protocol work on the IDE side.
|
|
- **You're writing a custom desktop / web / TUI host and want every Hermes feature** (slash commands, approvals, clarify, multi-agent, session branching) → TUI gateway JSON-RPC.
|
|
- **You want any OpenAI-compatible frontend, a language-agnostic HTTP client, or curl-driven automation** → API server.
|
|
- **You want a Python in-process embed without a subprocess** → import `run_agent.AIAgent` directly. See [Agent Loop](./agent-loop).
|
|
|
|
---
|
|
|
|
## Model hot-swapping
|
|
|
|
Mid-session model switching works on every surface — it's the `/model` slash command under the hood.
|
|
|
|
- **CLI / TUI:** `/model claude-sonnet-4` or `/model openrouter:anthropic/claude-sonnet-4.6`
|
|
- **TUI gateway RPC:** `command.dispatch` with `{"command": "/model claude-sonnet-4"}`
|
|
- **ACP:** the IDE sends the slash command as a prompt; the agent dispatches it
|
|
- **API server:** include a `model` field in the request body or set `X-Hermes-Model`
|
|
|
|
Provider-aware resolution (the same model name picks the right format for whatever provider you're on) is built in. See `hermes_cli/model_switch.py`.
|
|
|
|
---
|
|
|
|
## A note on `--mode rpc`
|
|
|
|
Hermes does not have a `--mode rpc` flag. The three protocols above already cover the use cases — ACP for IDE-protocol clients, the TUI gateway for stdio JSON-RPC hosts, and the API server for HTTP. If you find a real gap that none of them fill, open an issue with the concrete consumer you're building.
|