HermesX

English | 中文

---

English

HermesX is an Agent-first Runtime Control Plane for governed, multi-tenant AI automation.

It is for platform and product teams that need to run agents as production infrastructure: every agent turn, tool call, workflow step, tenant boundary, and operational signal has to be controlled, audited, and recoverable.

HermesX is not just a chat loop. It combines an agent runtime, a SaaS control plane, and fixed SOP workflows so teams can ship agentic systems without rebuilding identity, tenancy, audit, sandboxing, and observability from scratch.

Release State

Field	Value
Current docs/API baseline	v2.4.0-dev
Latest released baseline	v2.3.0
OpenAPI info.version	2.4.0-dev
Release-state rule	Features marked Unreleased are present in the current branch or changelog, but are not part of the latest released baseline until a v2.4.0 release is cut.

Who It Is For

Audience	Why HermesX fits
Platform teams	Provide a shared runtime for internal agents with tenant isolation, API keys, RBAC, audit logs, and usage controls.
Product teams	Add AI workflows, human approvals, and tool execution to SaaS products without making every feature team own agent infrastructure.
Security and operations teams	Review execution receipts, sandbox policy, auth chains, audit trails, metrics, and disaster-recovery posture in one place.

Why HermesX

1. Governed Agent Execution: agents can call tools, use memory, delegate work, and stream responses while staying inside auth, policy, sandbox, and audit boundaries.
2. Multi-Tenant SaaS Control Plane: tenants, roles, API keys, quotas, usage records, audit logs, GDPR actions, and admin operations are first-class runtime objects.
3. Workflow + Human-in-the-Loop Automation: fixed SOP workflows persist definitions, immutable versions, runs, step state, retries, and human approval tasks.

Architecture

flowchart TB
    entry["Entry Layer\nCLI, REST API, Web UI, messaging adapters, MCP"]
    runtime["Runtime Layer\nAgent loop, tools, skills, memory, model routing"]
    governance["Governance Layer\nAuth chain, tenant context, RBAC, scopes, audit, safety"]
    execution["Execution Layer\nLocal process, Docker sandbox, K8s Job sandbox (Unreleased)"]
    workflow["Workflow Layer\nDefinitions, versions, runs, human tasks, retries"]
    operations["Operations Layer\nPostgreSQL RLS, Redis, object storage, metrics, traces, backup"]

    entry --> governance
    governance --> runtime
    runtime --> execution
    runtime --> workflow
    workflow --> execution
    governance --> operations
    runtime --> operations
    workflow --> operations

Loading

Detailed one-page overview: docs/AGENT_FIRST_ARCHITECTURE.md.

Architecture diagrams are also available in docs/diagrams/:

Diagram	File
Technical architecture	technical-architecture.png
Product architecture	product-architecture.png
Application architecture	application-architecture.png
Data architecture	data-architecture.png

Minimal Demo

CLI Agent

git clone https://github.com/Colin4k1024/hermesx.git
cd hermesx
go build -o hermesx ./cmd/hermesx/

./hermesx setup
./hermesx chat "What tools do you have?"

SaaS Control Plane

docker compose -f docker-compose.prod.yml up -d
./examples/enterprise-saas-demo/demo.sh

Agent-first Governance Loop

./examples/agent-first-minimal-demo/demo.sh fixture

This deterministic fixture demo shows the API -> Agent Task -> Tool -> Receipt -> Audit correlation without requiring external services.

Capability Matrix

Capability	Latest released baseline (v2.3.0)	Current branch (v2.4.0-dev)
Agent runtime	OpenAI-compatible chat, native agent chat, tools, skills, memory, MCP client, context compression	Eino 0.9 main path, checkpoint resume, include_agentic_blocks debug output
SaaS control plane	Tenant isolation, PostgreSQL RLS, auth chain, API key scopes, RBAC, audit logs, GDPR export/delete, execution receipts	Admin usage aggregation API
Workflow automation	Fixed SOP workflow definitions, immutable versions, runs, step records, human tasks, retry/cancel API	Workflow agent_task default executor uses the Eino TurnLoop path
Sandbox and execution	Local and Docker execution policy with tenant-level sandbox controls	K8s Job sandbox mode via SANDBOX_MODE=k8s-job
Observability and ops	Prometheus metrics, OpenTelemetry tracing, structured logs, production compose, PG backup/restore	Grafana dashboard, Prometheus alert rules, OTel collector compose, Redis/MinIO backup scripts
Distributed scheduling	SaaS cron scheduler with Redis lock, PG poll-sync, idempotent runs, result delivery	Release hardening and follow-up docs tracked in Unreleased

Project Signals

Metric	Current value
Go source files	532
Go test files	156
Bundled skills	81 core + 45 optional
OpenAPI paths	45
Current docs/API baseline	v2.4.0-dev
Latest released baseline	v2.3.0

Counts are intentionally small and evidence-oriented. The full API contract is available from GET /v1/openapi.

Documentation

Document	Purpose
Agent-first architecture	Product positioning and layer boundaries
API reference	Endpoint-level API documentation
Workflow guide	Fixed SOP workflows and human tasks
Execution receipts	Receipt semantics, idempotency, and API examples
Workflow/Agent boundary	Where fixed SOP workflow logic ends and agent runtime logic begins
Security model	Threat model, auth chain, RLS, sandboxing
RBAC matrix	Role and resource permission matrix
Enterprise readiness	Evidence-based enterprise readiness matrix
Deployment guide	Docker, Kubernetes, HA, backup, alerting
Changelog	Released vs unreleased change history

When To Use HermesX

Use HermesX when agents must run inside product-grade boundaries: multiple tenants, real users, sensitive tools, auditable execution, approval workflows, and operational ownership.

For a single local assistant, a pure prompt prototype, or a workflow that does not need tenant isolation or auditability, a smaller agent framework may be the shorter path.

Acknowledgements

HermesX was originally forked from hermes-agent by Nous Research. HermesX has since diverged into an independent runtime-control-plane project for enterprise agent systems.

License

MIT

---

中文

HermesX 是面向 Agent 的运行时控制平面，用于受治理、多租户的 AI 自动化。

它面向需要把 Agent 当作生产基础设施运行的平台团队和产品团队：每一次 Agent 对话、工具调用、工作流步骤、租户边界和运维信号都需要可控制、可审计、可恢复。

HermesX 不只是一个聊天循环。它把 Agent Runtime、SaaS 控制平面和固定 SOP 工作流组合在一起，让团队不必从零重建身份认证、租户隔离、审计、沙箱和可观测性。

发布状态

字段	值
当前文档/API 基线	v2.4.0-dev
最新已发布基线	v2.3.0
OpenAPI info.version	2.4.0-dev
发布状态规则	标记为 Unreleased 的能力存在于当前分支或 changelog 中，但在 v2.4.0 正式发布前不属于最新稳定发布。

适用对象

对象	为什么适合 HermesX
平台团队	为内部 Agent 提供统一运行时，并内置租户隔离、API Key、RBAC、审计日志和用量控制。
产品团队	在 SaaS 产品中加入 AI 工作流、人工审批和工具执行，而不让每个业务团队都维护 Agent 基础设施。
安全与运维团队	在一个控制面中审查执行回执、沙箱策略、认证链、审计轨迹、指标和灾备状态。

三个支柱

1. 受治理的 Agent 执行：Agent 可以调用工具、使用记忆、委派任务和流式响应，同时受认证、策略、沙箱和审计约束。
2. 多租户 SaaS 控制平面：租户、角色、API Key、配额、用量、审计、GDPR 操作和管理端能力都是一等运行时对象。
3. 工作流 + 人在回路自动化：固定 SOP 工作流持久化定义、不可变版本、实例、步骤状态、重试和人工审批任务。

架构

flowchart TB
    entry["入口层\nCLI、REST API、Web UI、消息平台、MCP"]
    runtime["运行时层\nAgent 循环、工具、技能、记忆、模型路由"]
    governance["治理层\n认证链、租户上下文、RBAC、Scope、审计、安全"]
    execution["执行层\n本地进程、Docker 沙箱、K8s Job 沙箱（未发布）"]
    workflow["工作流层\n定义、版本、实例、人工任务、重试"]
    operations["运维层\nPostgreSQL RLS、Redis、对象存储、指标、链路、备份"]

    entry --> governance
    governance --> runtime
    runtime --> execution
    runtime --> workflow
    workflow --> execution
    governance --> operations
    runtime --> operations
    workflow --> operations

Loading

一页架构说明见 docs/AGENT_FIRST_ARCHITECTURE.md。

架构图位于 docs/diagrams/：

图	文件
技术架构	technical-architecture.png
产品架构	product-architecture.png
应用架构	application-architecture.png
数据架构	data-architecture.png

最小演示

CLI Agent

git clone https://github.com/Colin4k1024/hermesx.git
cd hermesx
go build -o hermesx ./cmd/hermesx/

./hermesx setup
./hermesx chat "你有什么工具？"

SaaS 控制平面

docker compose -f docker-compose.prod.yml up -d
./examples/enterprise-saas-demo/demo.sh

Agent-first 治理闭环

./examples/agent-first-minimal-demo/demo.sh fixture

这个确定性的 fixture demo 展示 API -> Agent Task -> Tool -> Receipt -> Audit 的关联链路，不依赖外部服务。

能力矩阵

能力	最新已发布基线（v2.3.0）	当前分支（v2.4.0-dev）
Agent Runtime	OpenAI 兼容 Chat、原生 Agent Chat、工具、技能、记忆、MCP、上下文压缩	Eino 0.9 主链、checkpoint resume、include_agentic_blocks 调试输出
SaaS 控制平面	租户隔离、PostgreSQL RLS、认证链、API Key Scope、RBAC、审计、GDPR、执行回执	Admin usage aggregation API
工作流自动化	固定 SOP 工作流定义、不可变版本、实例、步骤记录、人工任务、重试/取消 API	workflow agent_task 默认走 Eino TurnLoop
沙箱与执行	本地/Docker 执行策略，租户级沙箱控制	SANDBOX_MODE=k8s-job K8s Job 沙箱
可观测与运维	Prometheus 指标、OpenTelemetry 链路、结构化日志、生产 compose、PG 备份/恢复	Grafana Dashboard、Prometheus 告警、OTel Collector compose、Redis/MinIO 备份脚本
分布式调度	Redis Lock、PG 同步、幂等运行、结果投递的 SaaS cron scheduler	未发布区跟踪发布加固和后续文档

项目信号

指标	当前值
Go 源文件	532
Go 测试文件	156
内置技能	81 core + 45 optional
OpenAPI 路径	45
当前文档/API 基线	v2.4.0-dev
最新已发布基线	v2.3.0

这些数字只保留能帮助判断项目规模和契约状态的信号。完整 API 契约以 GET /v1/openapi 为准。

文档

文档	用途
Agent-first architecture	产品定位与层边界
API 参考	API 端点说明
工作流指南	固定 SOP 工作流与人工任务
执行回执	回执语义、幂等行为与 API 示例
工作流/Agent 边界	固定 SOP 工作流逻辑与 Agent Runtime 逻辑的边界
安全模型	威胁模型、认证链、RLS、沙箱
RBAC 矩阵	角色与资源权限
企业就绪度	基于证据的企业能力矩阵
部署指南	Docker、Kubernetes、高可用、备份、告警
Changelog	已发布与未发布变更

何时使用 HermesX

当 Agent 需要进入真实产品边界时使用 HermesX：多租户、真实用户、敏感工具、可审计执行、审批工作流和运维责任。

如果只是本地助手、提示词原型，或不需要租户隔离和审计能力的简单编排，选择更小的 Agent 框架会更直接。

致谢

HermesX 最初 fork 自 Nous Research 的 hermes-agent。HermesX 之后已经演进为独立的企业 Agent 运行时控制平面项目。

许可证

MIT