건축

이 페이지는 Hermes Agent 내부의 최상위 맵입니다. 이를 사용하여 코드베이스에 대한 내용을 파악한 다음 구현 세부 사항에 대한 하위 시스템별 문서를 자세히 살펴보세요.

시스템 개요

┌─────────────────────────────────────────────────────────────────────┐
│                        Entry Points                                  │
│                                                                      │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)     │
│  Batch Runner    API Server                  Python Library          │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                          │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │ Prompt       │  │ Provider     │  │ Tool         │               │
│  │ Builder      │  │ Resolution   │  │ Dispatch     │               │
│  │ (prompt_     │  │ (runtime_    │  │ (model_      │               │
│  │  builder.py) │  │  provider.py)│  │  tools.py)   │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                 │                       │
│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
│  │ Compression  │  │ 3 API Modes  │  │ Tool Registry│               │
│  │ & Caching    │  │ chat_compl.  │  │ (registry.py)│               │
│  │              │  │ codex_resp.  │  │ 70+ tools    │               │
│  │              │  │ anthropic    │  │ 28 toolsets  │               │
│  └──────────────┘  └──────────────┘  └──────────────┘               │
└─────────┴─────────────────┴─────────────────┴───────────────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────┐              ┌──────────────────────┐
│ Session Storage   │              │ Tool Backends         │
│ (SQLite + FTS5)   │              │ Terminal (7 backends) │
│ hermes_state.py   │              │ Browser (5 backends)  │
│ gateway/session.py│              │ Web (4 backends)      │
└───────────────────┘              │ MCP (dynamic)         │
                                   │ File, Vision, etc.    │
                                   └──────────────────────┘

디렉토리 구조

hermes-agent/
├── run_agent.py              # AIAgent — core conversation loop (large file)
├── cli.py                    # HermesCLI — interactive terminal UI (large file)
├── model_tools.py            # Tool discovery, schema collection, dispatch
├── toolsets.py               # Tool groupings and platform presets
├── hermes_state.py           # SQLite session/state database with FTS5
├── hermes_constants.py       # HERMES_HOME, profile-aware paths
├── batch_runner.py           # Batch trajectory generation
│
├── agent/                    # Agent internals
│   ├── prompt_builder.py     # System prompt assembly
│   ├── context_engine.py     # ContextEngine ABC (pluggable)
│   ├── context_compressor.py # Default engine — lossy summarization
│   ├── prompt_caching.py     # Anthropic prompt caching
│   ├── auxiliary_client.py   # Auxiliary LLM for side tasks (vision, summarization)
│   ├── model_metadata.py     # Model context lengths, token estimation
│   ├── models_dev.py         # models.dev registry integration
│   ├── anthropic_adapter.py  # Anthropic Messages API format conversion
│   ├── display.py            # KawaiiSpinner, tool preview formatting
│   ├── skill_commands.py     # Skill slash commands
│   ├── memory_manager.py    # Memory manager orchestration
│   ├── memory_provider.py   # Memory provider ABC
│   └── trajectory.py         # Trajectory saving helpers
│
├── hermes_cli/               # CLI subcommands and setup
│   ├── main.py               # Entry point — all `hermes` subcommands (large file)
│   ├── config.py             # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration
│   ├── commands.py           # COMMAND_REGISTRY — central slash command definitions
│   ├── auth.py               # PROVIDER_REGISTRY, credential resolution
│   ├── runtime_provider.py   # Provider → api_mode + credentials
│   ├── models.py             # Model catalog, provider model lists
│   ├── model_switch.py       # /model command logic (CLI + gateway shared)
│   ├── setup.py              # Interactive setup wizard (large file)
│   ├── skin_engine.py        # CLI theming engine
│   ├── skills_config.py      # hermes skills — enable/disable per platform
│   ├── skills_hub.py         # /skills slash command
│   ├── tools_config.py       # hermes tools — enable/disable per platform
│   ├── plugins.py            # PluginManager — discovery, loading, hooks
│   ├── callbacks.py          # Terminal callbacks (clarify, sudo, approval)
│   └── gateway.py            # hermes gateway start/stop
│
├── tools/                    # Tool implementations (one file per tool)
│   ├── registry.py           # Central tool registry
│   ├── approval.py           # Dangerous command detection
│   ├── terminal_tool.py      # Terminal orchestration
│   ├── process_registry.py   # Background process management
│   ├── file_tools.py         # read_file, write_file, patch, search_files
│   ├── web_tools.py          # web_search, web_extract
│   ├── browser_tool.py       # 10 browser automation tools
│   ├── code_execution_tool.py # execute_code sandbox
│   ├── delegate_tool.py      # Subagent delegation
│   ├── mcp_tool.py           # MCP client (large file)
│   ├── credential_files.py   # File-based credential passthrough
│   ├── env_passthrough.py    # Env var passthrough for sandboxes
│   ├── ansi_strip.py         # ANSI escape stripping
│   └── environments/         # Terminal backends (local, docker, ssh, modal, daytona, singularity)
│
├── gateway/                  # Messaging platform gateway
│   ├── run.py                # GatewayRunner — message dispatch (large file)
│   ├── session.py            # SessionStore — conversation persistence
│   ├── delivery.py           # Outbound message delivery
│   ├── pairing.py            # DM pairing authorization
│   ├── hooks.py              # Hook discovery and lifecycle events
│   ├── mirror.py             # Cross-session message mirroring
│   ├── status.py             # Token locks, profile-scoped process tracking
│   ├── builtin_hooks/        # Extension point for always-registered hooks (none shipped)
│   └── platforms/            # 20 adapters: telegram, discord, slack, whatsapp,
│                             #   signal, matrix, mattermost, email, sms,
│                             #   dingtalk, feishu, wecom, wecom_callback, weixin,
│                             #   bluebubbles, qqbot, homeassistant, webhook, api_server,
│                             #   yuanbao
│
├── acp_adapter/              # ACP server (VS Code / Zed / JetBrains)
├── cron/                     # Scheduler (jobs.py, scheduler.py)
├── plugins/memory/           # Memory provider plugins
├── plugins/context_engine/   # Context engine plugins
├── skills/                   # Bundled skills (always available)
├── optional-skills/          # Official optional skills (install explicitly)
├── website/                  # Docusaurus documentation site
└── tests/                    # Pytest suite (~3,000+ tests)

데이터 흐름

CLI 세션

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

게이트웨이 메시지

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

크론 작업

Scheduler tick → load due jobs from jobs.json
  → create fresh AIAgent (no history)
  → inject attached skills as context
  → run job prompt
  → deliver response to target platform
  → update job state and next_run

권장 읽기 순서

코드베이스를 처음 사용하는 경우:

이 페이지 — 알아보기
에이전트 루프 내부 — AIAgent 작동 방식
프롬프트 어셈블리 — 시스템 프롬프트 구축
공급자 런타임 해상도 — 공급자 선택 방법
공급자 추가 — 새 공급자 추가에 대한 실무 가이드
Tools Runtime — 도구 레지스트리, 디스패치, 환경
세션 저장소 — SQLite 스키마, FTS5, 세션 계보
게이트웨이 내부 — 메시징 플랫폼 게이트웨이
컨텍스트 압축 및 프롬프트 캐싱 — 압축 및 캐싱
ACP 내부 — IDE 통합

주요 하위 시스템

에이전트 루프

동기식 오케스트레이션 엔진(run_agent.py의 AIAgent). 공급자 선택, 프롬프트 구성, 도구 실행, 재시도, 대체, 콜백, 압축 및 지속성을 처리합니다. 다양한 공급자 백엔드에 대해 세 가지 API 모드를 지원합니다.

→ 에이전트 루프 내부

프롬프트 시스템

대화 수명주기 전반에 걸쳐 신속한 구축 및 유지 관리:

prompt_builder.py — 성격(SOUL.md), 메모리(MEMORY.md, USER.md), 기술, 컨텍스트 파일(AGENTS.md,.hermes.md), 도구 사용 지침 및 모델별 지침에서 시스템 프롬프트를 어셈블합니다.
prompt_caching.py — 접두사 캐싱을 위해 Anthropic 캐시 중단점을 적용합니다.
context_compressor.py — 컨텍스트가 임계값을 초과하는 경우 중간 대화 내용을 요약합니다.

→ 프롬프트 어셈블리, 컨텍스트 압축 및 프롬프트 캐싱

공급자 결정

CLI, 게이트웨이, cron, ACP 및 보조 호출에 사용되는 공유 런타임 확인자입니다. (provider, model) 튜플을 (api_mode, api_key, base_url)에 매핑합니다. 18개 이상의 공급자, OAuth 흐름, 자격 증명 풀 및 별칭 확인을 처리합니다.

→ 공급자 런타임 해상도

도구 시스템

~28개의 도구 세트에 걸쳐 70개 이상의 등록된 도구가 있는 중앙 도구 레지스트리(tools/registry.py). 각 도구 파일은 가져올 때 자체 등록됩니다. 레지스트리는 스키마 수집, 디스패치, 가용성 확인 및 오류 래핑을 처리합니다. 터미널 도구는 7개의 백엔드(로컬, Docker, SSH, Daytona, Modal, Singularity, Vercel Sandbox)를 지원합니다.

→ 도구 런타임

세션 지속성

FTS5 전체 텍스트 검색 기능을 갖춘 SQLite 기반 세션 저장소. 세션에는 계보 추적(압축 전반의 상위/하위), 플랫폼별 격리, 경합 처리를 통한 원자성 쓰기 기능이 있습니다.

→ 세션 저장

메시징 게이트웨이

20개의 플랫폼 어댑터, 통합 세션 라우팅, 사용자 인증(허용 목록 + DM 페어링), 슬래시 명령 디스패치, 후크 시스템, 크론 틱 및 백그라운드 유지 관리를 갖춘 장기 실행 프로세스입니다.

→ 게이트웨이 내부

플러그인 시스템

세 가지 검색 소스: ~/.hermes/plugins/(사용자), .hermes/plugins/(프로젝트) 및 pip 진입점. 플러그인은 컨텍스트 API를 통해 도구, 후크 및 CLI 명령을 등록합니다. 메모리 공급자(plugins/memory/)와 컨텍스트 엔진(plugins/context_engine/)이라는 두 가지 특수 플러그인 유형이 있습니다. 둘 다 단일 선택입니다. 한 번에 하나만 활성화할 수 있으며 hermes plugins 또는 config.yaml을 통해 구성됩니다.

→ 플러그인 가이드, 메모리 공급자 플러그인

크론

일급 에이전트 작업(셸 작업 아님). 작업은 JSON으로 저장되고 다양한 일정 형식을 지원하며 기술과 스크립트를 첨부하고 모든 플랫폼에 전달할 수 있습니다.

→ 크론 내부

ACP 통합

VS Code, Zed 및 JetBrains용 stdio/JSON-RPC를 통해 Hermes를 편집자 기반 에이전트로 노출합니다.

→ ACP 내부

궤적

학습 데이터 생성을 위해 에이전트 세션에서 ShareGPT 형식 궤적을 생성합니다.

→ 궤적 및 훈련 형식

디자인 원칙

원리	실제로 의미하는 것
신속한 안정성	시스템 프롬프트는 대화 도중에 변경되지 않습니다. 명시적인 사용자 작업(`/model`)을 제외하고 캐시 중단 변형이 없습니다.
관찰 가능한 실행	모든 도구 호출은 콜백을 통해 사용자에게 표시됩니다. CLI(스피너) 및 게이트웨이(채팅 메시지)의 진행 상황 업데이트.
중단 가능	API 호출 및 도구 실행은 사용자 입력 또는 신호에 의해 비행 중에 취소될 수 있습니다.
플랫폼에 구애받지 않는 핵심	하나의 AIAgent 클래스는 CLI, 게이트웨이, ACP, 배치 및 API 서버를 제공합니다. 플랫폼 차이는 에이전트가 아닌 진입점에 있습니다.
느슨한 결합	선택적 하위 시스템(MCP, 플러그인, 메모리 공급자, RL 환경)은 하드 종속성이 아닌 레지스트리 패턴과 check_fn 게이팅을 사용합니다.
프로필 격리	각 프로필(`hermes -p <name>`)은 고유한 HERMES_HOME, 구성, 메모리, 세션 및 게이트웨이 PID를 갖습니다. 여러 프로필이 동시에 실행됩니다.

파일 종속성 체인

tools/registry.py  (no deps — imported by all tool files)
       ↑
tools/*.py  (each calls registry.register() at import time)
       ↑
model_tools.py  (imports tools/registry + triggers tool discovery)
       ↑
run_agent.py, cli.py, batch_runner.py, environments/

이 체인은 에이전트 인스턴스가 생성되기 전 가져오기 시 도구 등록이 발생함을 의미합니다. 최상위 registry.register() 호출이 포함된 모든 tools/*.py 파일은 자동으로 검색되므로 수동으로 가져오기 목록이 필요하지 않습니다.

시스템 개요​

디렉토리 구조​

데이터 흐름​

CLI 세션​

게이트웨이 메시지​

크론 작업​

권장 읽기 순서​

주요 하위 시스템​

에이전트 루프​

프롬프트 시스템​

공급자 결정​

도구 시스템​

세션 지속성​

메시징 게이트웨이​

플러그인 시스템​

크론​

ACP 통합​

궤적​

디자인 원칙​

파일 종속성 체인​