How Hermes Turns ACP into a First‑Class Agent Protocol

Hermes extends its "terminal‑first" AI Agent with an acp_adapter that implements the Agent Communication Protocol (ACP), allowing IDEs such as VS Code, Zed, and JetBrains to communicate through a single, standardized interface.

1. Why a Standard Protocol Is Needed

AI coding assistants each ship their own private IDE plugins, binding developers to specific ecosystems and forcing Agent developers to write multiple adapters. This mirrors the pre‑LSP era where each editor required its own language server.

ACP, proposed by IBM Research, aims to solve the "client × Agent" N² integration problem just as LSP solved the "editor × language" issue.

2. What ACP Is

ACP is an open protocol that uses JSON‑RPC over stdio or sockets, but unlike LSP it maintains stateful sessions. Core operations include session/new, session/prompt, session/update, session/load, session/resume, and session/fork. Sessions have unique IDs, history, and can be paused, resumed, or branched.

3. Why Hermes Implements ACP

Avoid reinventing the wheel : Hermes already provides multi‑step reasoning, tool calls, and memory management; ACP supplies the missing standardized external interface.

One implementation, many IDEs : A single ACP server works across Zed, VS Code, and JetBrains plugins.

Protocol‑native capabilities : streaming responses, edit approvals, session replay, model switching, and task‑panel synchronization are all built into ACP.

4. acp_adapter Architecture

The acp_adapter/ directory contains:

acp_adapter/
├── entry.py      # CLI entry point: hermes acp
├── server.py     # Core ACP Agent implementation
├── session.py    # Session manager
├── events.py     # Bridge AIAgent callbacks to ACP notifications
├── tools.py      # Build ACP data structures for tool calls
├── auth.py       # Detect and broadcast authentication methods
├── permissions.py# Bridge dangerous commands to approval flow
├── edit_approval.py # File‑edit approval handling
└── provenance.py # Session lineage tracking

Communication follows the LSP‑style stdio JSON‑RPC pattern: the IDE launches hermes acp as a subprocess, sending requests via stdin and receiving only ACP frames on stdout, while logs go to stderr.

5. Session Management

Sessions are stored both in memory and in a SQLite database, enabling persistent history across IDE restarts. The SessionState dataclass holds the session ID, agent instance, working directory, model, history, and concurrency primitives.

@dataclass
class SessionState:
    session_id: str
    agent: Any
    cwd: str
    model: str
    history: List[Dict]
    cancel_event: Any
    is_running: bool
    queued_prompts: List[str]
    runtime_lock: Lock

When a client requests session/load, the server streams the prior conversation back via session/update before sending the RPC response, ensuring the IDE receives a complete transcript.

6. Event Bridging

Because the AIAgent runs synchronously in a thread pool while ACP operates asynchronously on an asyncio loop, events.py uses run_coroutine_threadsafe to forward updates safely:

def _send_update(conn, session_id, loop, update):
    future = safe_schedule_threadsafe(
        conn.session_update(session_id, update),
        loop,
    )
    future.result(timeout=5)

Three core event types are translated:

Tool call start → ToolCallStart notification.

Tool call completion → ToolCallProgress with formatted result.

Streaming text output → incremental session/update messages.

7. Tool Kind Mapping

Hermes maps its internal tool names to ACP’s standardized ToolKind values, allowing IDEs to render appropriate icons:

TOOL_KIND_MAP = {
    "read_file": "read",
    "write_file": "edit",
    "patch": "edit",
    "terminal": "execute",
    "web_search": "fetch",
    "todo": "other",
    ...
}

8. Edit Approval Workflow

When the Agent proposes a file edit, edit_approval.py builds an ACP ToolCallUpdate containing a diff and sends it to the IDE. The user must click "Allow" before the edit is applied. Three approval modes are supported: ask (default, prompt each edit), workspace_session (auto‑approve within the workspace), and session (auto‑approve for the whole session).

9. Design Takeaways

Standard protocol eliminates duplicated IDE integration work.

ACP’s native features—session history, streaming, edit approval, and tool‑type semantics—are leveraged instead of hacking private data into a custom API.

Full transparency of the Agent’s reasoning, tool usage, and file changes is exposed to the user.

Human‑in‑the‑loop safeguards prevent unchecked file modifications.

Future posts will discuss Hermes’s prefix‑cache philosophy for improving KV‑cache hit rates and reducing API latency.