Skip to main content

Programmatic Integration

Thoth ships two protocols for driving the agent from external programs — IDE plugins, CI pipelines, embedded sub-agents. Pick the one that matches your transport and consumer.

ProtocolTransportBest forDefined by
ACPJSON-RPC over stdioIDE clients (VS Code, Zed, JetBrains) that already speak the Agent Client Protocolacp_adapter/
API serverHTTP + Server-Sent EventsOpenAI-compatible frontends (Open WebUI, LobeChat, LibreChat…) and language-agnostic web clientsgateway/platforms/api_server.py

Both drive the same AIAgent core. They differ only in wire format and which set of features they expose.

ACP (Agent Client Protocol)​

thoth 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.

thoth acp                  # serve ACP on stdio
thoth acp --bootstrap      # print install snippet for an ACP-capable IDE

OpenAI-Compatible API Server​

gateway/platforms/api_server.py exposes thoth 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 thoth-agent
GET  /health, /health/detailed

Setup, headers (X-Thoth-Session-Id, X-Thoth-Session-Key), and frontend wiring: 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 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.

Model hot-swapping​

Mid-session model switching works on every surface — it's the /model slash command under the hood.

  • CLI: /model claude-sonnet-4 or /model openrouter:anthropic/claude-sonnet-4.6
  • 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-Thoth-Model

Provider-aware resolution (the same model name picks the right format for whatever provider you're on) is built in. See thoth_cli/model_switch.py.

A note on --mode rpc​

Thoth does not have a --mode rpc flag. The two protocols above already cover the use cases — ACP for IDE-protocol clients and the API server for HTTP. If you find a real gap that neither fills, open an issue with the concrete consumer you're building.