Protocolo ACP

源码版本v2026.7.20

Responsabilidad

ACP (Agent Client Protocol) es el protocolo estándar de comunicación entre un editor/IDE y un agent. acp_adapter/ expone a Hermes como server ACP, de modo que los clientes compatibles (Zed, extensiones de VS Code, etc.) puedan conducir Hermes directamente: gestionar sesiones, leer/escribir recursos (ficheros/imágenes), aprobar ediciones, trazar provenance y aislar herramientas por permisos. Así Hermes no vive solo en plataformas de mensajes, también se incrusta en flujos de desarrollo.

Archivos clave

• cabecera server.py:1-92 — "ACP agent server — exposes Hermes Agent via the Agent Client Protocol"
• tratamiento de recursos:96-150 — _MAX_ACP_RESOURCE_BYTES, _resource_display_name, _is_text_resource / _is_image_resource
• conversión de recursos texto/imagen:201-296 — _format_resource_text / _resource_link_to_parts / _image_data_url (recurso → partes de contenido OpenAI)
• SessionState / SessionManager:159-175 — estado y gestor de sesiones ACP
• traducción de cwd:29-62 — _translate_acp_cwd / _normalize_cwd_for_compare (alineación del directorio de trabajo del editor)
• expansión de toolsets:129-159 — _expand_acp_enabled_toolsets
• class EditProposal:26-51 — propuesta de edición (write_file / patch)
• build_edit_proposal:178-220 — construye la propuesta desde la llamada a herramienta (write_file / patch_replace / patch_v4a)
• requester de aprobación:51-69 — set_edit_approval_requester / mecanismo de token
• permissions.py — aislamiento de permisos de herramientas
• provenance:22-111 — build_session_provenance / session_provenance_meta (trazabilidad del origen de operaciones)
• auth.py / entry.py / events.py
• __main__.py — entrada del server ACP (5 líneas)
• acp_registry/agent.json — manifiesto de metadatos del agent (para descubrimiento por los clientes)
• acp_registry/icon.svg — icono

Flujo de datos

1. El cliente ACP (editor) descubre y arranca el server ACP de Hermes a partir de acp_registry/agent.json (acp_adapter/__main__.py).
2. El cliente inicia una sesión → SessionManager:175 crea un SessionState, alinea cwd (acp_adapter/session.py:29) y expande toolsets (acp_adapter/session.py:129).
3. El cliente envía mensajes/recursos → la conversión de recursos:201 traduce el recurso ACP (fichero/imagen, sujeto al límite de tamaño de acp_adapter/server.py:96) a partes de contenido OpenAI y las entrega a run_conversation:588.
4. Cuando el agent quiere modificar ficheros, la llamada a herramienta pasa por build_edit_proposal:178 y se convierte en un EditProposal, que el requester de aprobación (acp_adapter/edit_approval.py:51) eleva al usuario para confirmar.
5. La ejecución de herramientas está sujeta a los permisos de acp_adapter/permissions.py; cada operación anota provenance vía acp_adapter/provenance.py:22.
6. La salida en streaming y los eventos (acp_adapter/events.py) se devuelven al cliente.

Resumen

ACP incrusta a Hermes en el flujo de trabajo del editor: gestión de sesiones, lectura/escritura de recursos, aprobación de ediciones, aislamiento de permisos y trazabilidad de origen. El núcleo es server.py (adaptación de protocolo) + session.py (sesión) + edit_approval.py (ediciones con revisión humana). Complementa a la capa de gateway: el gateway conecta plataformas de mensajes; ACP conecta IDEs.