ACP Protocol

源码版本v2026.7.20

Responsibility

ACP (Agent Client Protocol) is a standard protocol for editors/IDEs to talk to an agent. acp_adapter/ exposes Hermes as an ACP server so that ACP-capable clients (Zed, VS Code extensions, etc.) can directly drive Hermes: manage sessions, read/write resources (files/images), approve edits, trace provenance, and isolate tools by permission. This lets Hermes extend beyond messaging platforms and embed into development workflows.

Key Files

• server.py header:1-92 — "ACP agent server — exposes Hermes Agent via the Agent Client Protocol"
• resource handling:96-150 — _MAX_ACP_RESOURCE_BYTES, _resource_display_name, _is_text_resource / _is_image_resource
• resource text/image conversion:201-296 — _format_resource_text / _resource_link_to_parts / _image_data_url (resource → OpenAI content parts)
• SessionState / SessionManager:159-175 — ACP session state and management
• cwd translation:29-62 — _translate_acp_cwd / _normalize_cwd_for_compare (align editor working directory)
• toolsets expansion:129-159 — _expand_acp_enabled_toolsets
• class EditProposal:26-51 — edit proposal (write file / patch)
• build_edit_proposal:178-220 — builds a proposal from a tool call (write_file / patch_replace / patch_v4a)
• approval requester:51-69 — set_edit_approval_requester / token mechanism
• permissions.py — tool permission isolation
• provenance:22-111 — build_session_provenance / session_provenance_meta (operation-origin traceability)
• auth.py / entry.py / events.py
• __main__.py — ACP server startup entry (5 lines)
• acp_registry/agent.json — agent metadata manifest (for client discovery)
• acp_registry/icon.svg — icon

Data Flow

1. An ACP client (editor) discovers and launches the Hermes ACP server via acp_registry/agent.json (acp_adapter/__main__.py).
2. The client opens a session → SessionManager:175 creates a SessionState, aligns cwd (acp_adapter/session.py:29), and expands toolsets (acp_adapter/session.py:129).
3. The client sends a message/resource → resource conversion:201 turns the ACP resource (file/image, subject to the acp_adapter/server.py:96 size limit) into OpenAI content parts, fed to run_conversation:588.
4. When the agent wants to modify a file, the tool call becomes an EditProposal via build_edit_proposal:178, popped to the user for confirmation via the approval requester (acp_adapter/edit_approval.py:51).
5. Tool execution is gated by acp_adapter/permissions.py permissions; each operation records provenance via acp_adapter/provenance.py:22.
6. Streaming output and events (acp_adapter/events.py) are returned to the client.

Summary

ACP lets Hermes embed into editor workflows: session management, resource read/write, edit approval, permission isolation, provenance tracing. The core is server.py (protocol adaptation) + session.py (sessions) + edit_approval.py (human-approved edits). It complements the gateway layer — the gateway connects to messaging platforms, ACP connects to IDEs.