Hermes Agent 架构概述

Hermes Agent 是一个设计用于构建企业级智能体应用的框架。本文介绍 Hermes 的整体架构和核心设计理念。

项目定位

Hermes Agent 是一个 Python 驱动的 AI 智能体框架，专注于提供可扩展、可插拔的基础设施，帮助企业在此之上构建定制化的智能体应用。

核心架构原则

1. 模块化设计

整个项目采用严格的模块化架构，将核心功能隔离到独立的包中：

hermes-agent/
├── run_agent.py          # AIAgent 核心 orchestration
├── cli.py                # 命令行交互接口
├── model_tools.py        # 工具调用调度
├── toolsets.py           # 工具集定义
├── hermes_state.py       # 会话状态管理
├── agent/                # Agent 核心模块
├── gateway/              # 消息网关
├── plugins/              # 插件系统
└── tools/                # 工具实现

2. 单一职责原则

每个模块负责单一的功能领域：

run_agent.py: 负责编排整个智能体对话循环，管理工具调用、上下文、预算
model_tools.py: 统一调度所有工具的注册、发现和调用
gateway/: 负责将不同平台的消息转换为统一的内部格式
plugins/: 提供运行时扩展机制，支持热插拔
tools/: 封装具体的工具实现，支持懒加载

3. 配置驱动架构

所有行为都可以通过配置控制，支持多实例隔离：

# config.yaml 片段
model:
  default: "claude-opus-4-20250514"
  provider: "anthropic"

terminal:
  env_type: "local"
  timeout: 60

gateway:
  platforms:
    - telegram
    - discord

核心组件剖析

AIAgent 类 (run_agent.py)

这是 Hermes 的核心 orchestration 类，负责整个智能体的生命周期管理：

class AIAgent:
    def __init__(
        self,
        base_url: str = None,
        api_key: str = None,
        provider: str = None,
        model: str = "",
        max_iterations: int = 90,
        enabled_toolsets: List[str] = None,
        # ... 60+ 参数
    ):
        # 初始化工具集、记忆管理器、会话上下文等
    
    def chat(self, message: str) -> str:
        """简化接口，单轮对话"""
    
    def run_conversation(self, user_message: str, ...) -> dict:
        """完整的对话循环，支持工具调用"""

核心设计亮点：

Tool Calling Loop: 完全同步的工具调用循环，支持中断检查和预算控制
Context Management: 内置上下文压缩机制，自动管理token成本
Memory Integration: 与多家记忆提供商无缝集成

工具系统 (tools/)

工具系统采用 自注册模式，每个工具文件在导入时自动注册：

# tools/registry.py
def register(
    name: str,
    toolset: str,
    schema: dict,
    handler: callable,
    check_fn: callable = None,
    requires_env: list = None,
):
    # 自动注册工具 schema 和处理函数

工具发现机制：

导入 tools/registry.py 触发发现
动态导入所有 tools/*.py 文件
每个工具调用 registry.register() 完成注册
插件工具通过 ctx.register_tool() 注册

插件系统 (plugins/)

Hermes 支持两级插件：

通用插件: 提供生命周期钩子和工具注册
- pre_tool_call, post_tool_call 等钩子
- on_session_start, on_session_end 生命周期
专业插件: 专用于特定领域
- 记忆提供商插件 (plugins/memory/)
- 模型提供商插件 (plugins/model-providers/)
- 上下文引擎插件 (plugins/context_engine/)

会话管理 (hermes_state.py)

基于 SQLite 的会话存储，支持：

FTS5 全文检索: 跨所有会话进行智能搜索
WAL 模式: 支持多进程并发读写
WAL 降级: 自动适配 NFS 等不支持的文件系统

数据库 Schema 设计：

sessions: 会话元数据和统计信息
messages: 完整的消息历史
messages_fts: 全文搜索索引
state_meta: 全局元数据

技术栈

组件	技术选型	原因
推理框架	OpenAI SDK	生态丰富，支持多种 API 模式
工具调用	异步事件循环	高并发工具执行，避免阻塞
状态存储	SQLite + FTS5	轻量、无需部署、全文检索
消息网关	平台适配器模式	统一不同平台的消息格式
插件系统	动态导入 + 注册	运行时扩展，无需重启

企业级特性

1. 多实例支持 (Profiles)

hermes -p production run
hermes -p development run

每个 Profile 独立的配置、API Key、技能库和会话历史。

2. 内置调度 (Cron)

使用 Hermes 自带的 cron 系统，而非系统 crontab：

cron:
  jobs:
    - name: "daily-report"
      schedule: "0 9 * * *"
      prompt: "生成今日工作总结"

3. 技能管理 (Curator)

内置技能库维护系统，自动归档不活跃的技能，支持手工 Pin 保护重要技能。

4. 多代理协作 (Kanban)

基于 SQLite 的任务看板，支持多智能体并行工作，具有任务阻塞、心跳、评论等功能。

架构图

                    ┌─────────────────────────┐
                    │    用户/开发者          │
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │    网关 (gateway)       │
                    │  (Telegram/Discord/...) │
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │    AIAgent 核心         │
                    │  - 对话循环              │
                    │  - 工具调用              │
                    │  - 上下文管理            │
                    └───────────┬─────────────┘
                                │
            ┌───────────────────┼───────────────────┐
            │                   │                   │
    ┌───────▼───────┐   ┌───────▼───────┐   ┌───────▼───────┐
    │   工具系统     │   │   记忆系统     │   │  插件系统     │
    │  (tools/)     │   │(memory_manager)│   │  (plugins/)   │
    └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
            │                   │                   │
    ┌───────▼───────┐   ┌───────▼───────┐   ┌───────▼───────┐
    │  具体工具实现  │   │ 记忆提供商    │   │  扩展模块     │
    │  (web_search) │   │ (honcho/mem0) │   │ (image_gen)   │
    └───────────────┘   └───────────────┘   └───────────────┘

总结

Hermes Agent 采用模块化、配置驱动的架构，为企业构建智能体应用提供了坚实的基础设施。其核心设计理念是：

可扩展性: 插件系统和工具系统支持热扩展
可配置性: 所有行为都可以通过配置控制
可维护性: 清晰的模块职责划分
企业级: 内置调度、技能管理、多实例支持