Hermes Agent

flowchart TD
  subgraph CoreEngine["Core Engine"]
    AGENT["agent/\nOrchestration + Memory + Skills"]
    TOOLS["tools/\n40+ Tool Implementations"]
    CLI["hermes_cli/\nTUI + Config + Profiles"]
  end

  subgraph Communication["Communication"]
    GATEWAY["gateway/\n18+ Platform Adapters"]
    ACP["acp_adapter/\nAgent Communication Protocol"]
  end

  subgraph Intelligence["Intelligence"]
    PLUGINS["plugins/\n8 Memory Backends"]
    ENVS["environments/\nRL Training + Benchmarks"]
  end

  subgraph Automation["Automation"]
    CRON["cron/\nScheduled Tasks"]
  end

  CLI -->|"user input to prompt builder"| AGENT
  AGENT -->|"dispatches via registry"| TOOLS
  AGENT -->|"persists context"| PLUGINS
  GATEWAY -->|"routes messages to sessions"| AGENT
  ACP -->|"inter-agent protocol"| AGENT
  CRON -->|"triggers scheduled runs"| AGENT
  CRON -->|"delivers results"| GATEWAY
  ENVS -->|"evaluation harness"| AGENT
  TOOLS -->|"environment execution"| ENVS
  GATEWAY -->|"exposes endpoints"| ACP

sequenceDiagram
    participant User as User
    participant CLI as hermes_cli
    participant PB as PromptBuilder
    participant LLM as LLM Provider
    participant TR as ToolRegistry
    participant Tool as Tool
    participant Display as Display

    User->>CLI: input message
    Note over User,CLI: CLI captures input and manages session state
    CLI->>PB: build prompt with context + memory
    Note over CLI,PB: Context window management ensures token budget
    PB->>LLM: send prompt to selected model
    Note over PB,LLM: Provider abstraction routes to any of 100+ backends
    LLM->>TR: tool call request
    Note over LLM,TR: Registry resolves tool by name, validates args
    TR->>Tool: execute tool
    Note over TR,Tool: Subprocess isolation protects agent from tool crashes
    Tool-->>TR: tool result
    TR-->>LLM: inject result into context
    Note over TR,LLM: Multi-turn loop continues until LLM produces final answer
    LLM-->>CLI: final response
    CLI-->>Display: stream to TUI
    Note over CLI,Display: Skin engine formats output per user preferences

sequenceDiagram
    participant Platform as Platform (Telegram/Discord/...)
    participant Adapter as Platform Adapter
    participant Session as SessionStore
    participant Agent as Agent Loop
    participant Stream as StreamConsumer
    participant Delivery as Delivery Router

    Platform->>Adapter: incoming message
    Note over Platform,Adapter: Adapter normalizes platform-specific format
    Adapter->>Session: resolve or create session
    Note over Adapter,Session: Session tracks conversation history per user per platform
    Session->>Agent: dispatch to agent loop
    Note over Session,Agent: Subprocess boundary - gateway and agent are isolated
    Agent->>Agent: reason + tool calls
    Agent-->>Stream: streaming tokens
    Note over Agent,Stream: Backpressure prevents overwhelming slow platforms
    Stream-->>Delivery: formatted chunks
    Delivery-->>Platform: deliver response
    Note over Delivery,Platform: Delivery router handles platform rate limits and retries

sequenceDiagram
    participant AgentLoop as Agent Loop
    participant Registry as ToolRegistry
    participant ToolDef as Tool Definition
    participant Backend as Execution Backend

    AgentLoop->>Registry: lookup tool by name
    Note over AgentLoop,Registry: Registry was populated at import time via decorators
    Registry->>ToolDef: resolve definition + schema
    Note over Registry,ToolDef: Schema validation catches bad args before execution
    ToolDef->>Backend: execute in selected environment
    Note over ToolDef,Backend: Backend chosen by config: local, Docker, SSH, Modal, etc.
    Backend-->>ToolDef: raw result
    ToolDef-->>Registry: formatted result
    Registry-->>AgentLoop: inject into context window
    Note over Registry,AgentLoop: Agent decides: call another tool or produce final answer