Hermes Agents Integration

Hermes Agents Integration connects the Conduit mobile client to self-hosted Hermes servers. This system enables the execution of autonomous agents that run tools, manage long-term memory, and follow schedules. Conduit provides a native interface to watch tool execution live and approve sensitive actions before the agent proceeds.

Sources: README.md:27-33, README.md:88-91

Connectivity and Setup

You connect to a Hermes server by providing a server URL and an API key. Conduit supports multiple named Hermes connections (e.g., "Home" or "Research"), which you can manage via the Accounts page or sidebar.

Connection Parameters

Sources: README.md:188-193, assets/release_notes/en.json:115-119

Setup Workflow

The following diagram illustrates the initial connection process for Hermes Agents.

The application validates the connection and Desktop Gateway sign-in during the setup process.
Sources: README.md:188-194, assets/release_notes/en.json:107-108

Core Components and Features

Desktop Gateway and Bot Mode

Hermes utilizes a Desktop Gateway to facilitate "Bot Mode." In this mode, consecutive replies from the agent share a single header in the UI. Users can select specific bots from the sidebar to initiate sessions.

Sources: assets/release_notes/en.json:8-10, assets/release_notes/en.json:120-123

Tool Execution and Approvals

Conduit renders streamed tool calls as distinct UI blocks. If an agent attempts a sensitive step, the system pauses for user approval. Approvals remain associated with the specific execution run to ensure accuracy in long conversations.

Sources: assets/release_notes/en.json:34-37, assets/release_notes/en.json:107-108

Session Management

• Persistence: Reopening a running Desktop session maintains the active state, including UI spinners for active tasks.
• Recovery: The system recovers finished runs and loads long sessions even if a reconnection attempt initially fails.
• Context Support: Hermes accepts PDF attachments and provides skill autocompletion during prompt entry.

Sources: assets/release_notes/en.json:25-27, assets/release_notes/en.json:36-37, assets/release_notes/en.json:62-64

Data Flow and Architecture

The integration relies on WebSockets for real-time updates and tool execution tracking.

Technical Implementation Details

The system uses standard web protocols and shared data structures to manage agent states.

Message Structure

Messages from Hermes include metadata for statusHistory and code_executions. These fields track internal actions like knowledge searches or Python code interpreter runs.

{
  "statusHistory": [
    {
      "action": "knowledge_search",
      "query": "matplotlib sine wave",
      "done": true
    }
  ],
  "code_executions": [
    {
      "id": "ce-4a5b6c7d",
      "name": "Code Interpreter",
      "code": "import numpy as np...",
      "language": "python",
      "result": { "output": "saved\n" }
    }
  ]
}

Sources: packages/conduit_core/test/fixtures/chat_blobs/06_code_executions.json:44-70, packages/conduit_core/test/fixtures/chat_blobs/05_web_search_status_sources.json:44-50

Dependencies

The integration utilizes several Dart packages for networking and data handling:

• socket_io_client: Manages WebSocket connections to the Hermes server.
• flutter_secure_storage: Stores API keys and credentials in platform-secure storage (Keychain/Keystore).
• conduit_markdown: Processes agent output into renderable blocks.

Sources: pubspec.yaml:70-71, pubspec.yaml:49, pubspec.yaml:23

Summary

Hermes Agents Integration provides a secure, interactive mobile interface for self-hosted autonomous agents. By combining native tool rendering, mandatory user approvals for sensitive steps, and persistent session management via a Desktop Gateway, Conduit enables users to manage complex AI workflows directly from mobile devices.