{
  "id": "page:docs-hermes-research-raw-programmatic-integration",
  "_kind": "Page",
  "_file": "wiki/docs/hermes-research/raw/programmatic-integration.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/hermes-research/raw/programmatic-integration.md",
    "sourceKind": "repo-docs",
    "title": "Programmatic Integration",
    "displayName": "Programmatic Integration",
    "slug": "docs/hermes-research/raw/programmatic-integration",
    "articlePath": "wiki/docs/hermes-research/raw/programmatic-integration.md",
    "article": "\n# Programmatic Integration\n\n> Source: https://hermes-agent.nousresearch.com/docs/developer-guide/programmatic-integration\n\nHermes offers three protocols for external program control:\n\n## Protocol Comparison\n\n| Protocol | Transport | Use Case | Location |\n|----------|-----------|----------|----------|\n| ACP | JSON-RPC over stdio | IDE clients (VS Code, Zed, JetBrains) | `acp_adapter/` |\n| TUI Gateway | JSON-RPC over stdio/WebSocket | Custom hosts needing fine-grained control | `tui_gateway/server.py` |\n| API Server | HTTP + Server-Sent Events | OpenAI-compatible frontends | `gateway/platforms/api_server.py` |\n\nAll three drive the same `AIAgent` core with different wire formats.\n\n## ACP (Agent Client Protocol)\n\nLaunch with: `hermes acp`\n\n\"Session creation, prompt submission, streaming agent message chunks, tool-call events, permission requests, session fork, cancel, and authentication\" are exposed capabilities.\n\nBootstrap for IDEs: `hermes acp --bootstrap`\n\n## TUI Gateway JSON-RPC\n\nControls sessions and features via methods like:\n- `session.create`, `session.list`, `session.activate`, `session.close`\n- `prompt.submit`, `prompt.background`\n- `session.steer`, `session.history`, `session.compress`, `session.branch`\n- `command.dispatch`, `approval.respond`, `clarify.respond`\n\n**Events returned:** `message.delta`, `message.complete`, `tool.start`, `tool.progress`, `tool.complete`, plus approval and clarify requests.\n\n## OpenAI-Compatible API Server\n\nHTTP endpoints:\n- `POST /v1/chat/completions` (with SSE streaming)\n- `POST /v1/responses` (stateful)\n- `POST /v1/runs` (start run, returns ID)\n- `GET /v1/runs/{id}` (status)\n- `GET /v1/runs/{id}/events` (SSE lifecycle stream)\n- `POST /v1/runs/{id}/approval` (resolve approvals)\n\n## Model Hot-Swapping\n\nMid-session model switching via `/model` slash command:\n- CLI/TUI: `/model claude-sonnet-4`\n- TUI gateway: `command.dispatch` RPC method\n- API server: `model` field in request body\n\n## Selection Guide\n\n- **IDE plugins with ACP support** -> Use ACP\n- **Custom hosts requiring all features** -> TUI gateway JSON-RPC\n- **OpenAI-compatible frontends or HTTP clients** -> API server\n- **Python in-process without subprocess** -> Import `AIAgent` directly\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-hermes-research",
      "to": "page:docs-hermes-research-raw-programmatic-integration",
      "kind": "contains_page"
    }
  ]
}