ACP-Protokoll

源码版本v2026.7.20

Verantwortung

ACP (Agent Client Protocol) ist das Standardprotokoll, über das Editor/IDE mit dem Agenten kommunizieren. acp_adapter/ stellt Hermes als ACP-Server bereit, sodass ACP-fähige Clients (Zed, VS-Code-Erweiterungen u. a.) Hermes direkt antreiben können: Sitzungen verwalten, Ressourcen (Dateien/Bilder) lesen/schreiben, Edits genehmigen, Provenance nachverfolgen, Werkzeuge nach Berechtigungen isolieren. Damit ist Hermes nicht nur Nachrichtenplattform, sondern auch in Entwickler-Workflows eingebettet.

Schlüsseldateien

• server.py Kopf:1-92 — "ACP agent server — exposes Hermes Agent via the Agent Client Protocol"
• Ressourcen-Handling:96-150 — _MAX_ACP_RESOURCE_BYTES, _resource_display_name, _is_text_resource / _is_image_resource
• Ressourcen-Text/Bild-Konvertierung:201-296 — _format_resource_text / _resource_link_to_parts / _image_data_url (Ressource → OpenAI-Content-Parts)
• SessionState / SessionManager:159-175 — ACP-Sitzungszustand und -Verwaltung
• cwd-Übersetzung:29-62 — _translate_acp_cwd / _normalize_cwd_for_compare (Arbeitsverzeichnis des Editors ausrichten)
• Toolsets-Expansion:129-159 — _expand_acp_enabled_toolsets
• class EditProposal:26-51 — Edit-Vorschlag (Datei schreiben / Patch)
• build_edit_proposal:178-220 — baut aus einem Werkzeugaufruf einen Vorschlag (write_file / patch_replace / patch_v4a)
• Approval-Requester:51-69 — set_edit_approval_requester / Token-Mechanismus
• permissions.py — Werkzeug-Berechtigungsisolation
• provenance:22-111 — build_session_provenance / session_provenance_meta (Aktionen-Provenance)
• auth.py / entry.py / events.py
• __main__.py — ACP-Server-Starteinstieg (5 Zeilen)
• acp_registry/agent.json — Agent-Metadaten-Manifest (für Client-Discovery)
• acp_registry/icon.svg — Icon

Datenfluss

1. Ein ACP-Client (Editor) entdeckt via acp_registry/agent.json und startet den Hermes-ACP-Server (acp_adapter/__main__.py).
2. Der Client öffnet eine Sitzung → SessionManager:175 erzeugt eine SessionState, richtet cwd aus (acp_adapter/session.py:29) und klappt die Toolsets auf (acp_adapter/session.py:129).
3. Der Client sendet Nachrichten/Ressourcen → Ressourcen-Konvertierung:201 wandelt die ACP-Ressource (Datei/Bild, beschränkt durch acp_adapter/server.py:96) in OpenAI-Content-Parts und füttert run_conversation:588.
4. Will der Agent eine Datei ändern, wird aus dem Werkzeugaufruf über build_edit_proposal:178 ein EditProposal, das über den Approval-Requester (acp_adapter/edit_approval.py:51) dem Nutzer zur Bestätigung vorgelegt wird.
5. Die Werkzeugausführung wird durch acp_adapter/permissions.py berechtigt; jede Aktion wird über acp_adapter/provenance.py:22 als Provenance festgehalten.
6. Streaming-Output und Events (acp_adapter/events.py) werden an den Client zurückgesendet.

Zusammenfassung

ACP bettet Hermes in Editor-Workflows ein: Sitzungsverwaltung, Ressourcen-Lesen/Schreiben, Edit-Genehmigung, Berechtigungs-Isolation, Provenance. Der Kern ist server.py (Protokoll-Adapter) + session.py (Sitzung) + edit_approval.py (menschliche Edit-Prüfung). Komplementär zum Gateway – das Gateway bindet Nachrichtenplattformen an, ACP bindet die IDE an.