Programmatic Integration
Programmatic Integration
Start with meaning, then move to detail.
This lesson explains Programmatic Integration as part of Hermes internals and extension points. You will learn what it does, when it matters, and the smallest safe test that proves it works.
If you are new, do not memorize names. Focus on three questions: what problem does this solve, what access does it need, and how can you verify the result?
For practice, inspect the first example, identify its effects, run it on test data, and compare the result with the source claim.
For advanced readers, inspect ACP (Agent Client Protocol), TUI Gateway JSON-RPC, Method catalog (selected), then verify failure modes and version compatibility.
Know Python, Git, and basic project structure before changing code.
A clear outcome before you read.
- Understand Programmatic Integration without assumed prior knowledge.
- Separate the source description from what still needs testing in your environment.
- Read the first command and identify its inputs and outputs before copying it.
Short definitions before the details.
- ACP
- A protocol used to connect agent sessions and events to compatible clients and editors.
- Provider
- The service that runs or provides access and authentication to a model.
- Gateway
- The process that connects Hermes to channels such as Telegram or Discord and routes messages.
Three protocols for driving hermes-agent from external programs: ACP, the TUI gateway JSON-RPC, and the OpenAI-compatible HTTP API
What does the source say, and in what order?
- 01ACP (Agent Client Protocol)
Start here to understand the core idea or structure.
- 02TUI Gateway JSON-RPC
Read this after the foundation, then connect it to the previous step.
- 03Method catalog (selected)
Read this after the foundation, then connect it to the previous step.
- 04Rewinding history on prompt.submit
Read this after the foundation, then connect it to the previous step.
- 05Events streamed back
Read this after the foundation, then connect it to the previous step.
- 06Pi-style RPC mapping
Read this after the foundation, then connect it to the previous step.
- 07OpenAI-Compatible API Server
Read this after the foundation, then connect it to the previous step.
- 08Model catalog surfaces
Read this after the foundation, then connect it to the previous step.
- 09Which one should I use?
Read this after the foundation, then connect it to the previous step.
- 10Model hot-swapping
Finish here to verify the result and special cases.
Copy only after you understand the effect.
hermes acp # serve ACP on stdio
hermes acp --check # verify ACP dependencies and adapter imports
hermes acp --setup # interactive provider/model setup for ACP terminal authprompt.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 subagentPOST /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 /api/model/options Provider-aware picker iRead the first command and identify its inputs and outputs before copying it.
Match every command to your installed Hermes version, review the files and accounts it can reach, and use non-sensitive data for the first test. If this explanation differs from the source, the official source wins.