HerMAS

Python-based event-driven orchestration core for multi-agent systems.

Why HerMAS | Quickstart | Product Surface |

HerMAS is an event-driven orchestration engine for multi-agent systems. The name is derived from combining Hermes — the fast and reliable messenger who routes information — and Multi Agent System. It acts as a central router—instead of letting agents call each other directly, HerMAS receives a routing trigger, evaluates the current knowledge state and policy, selects the next execution target, runs the selected agent, updates state, and records an explainable trace.

It is designed as the perfect infrastructure for scalable agent orchestration, bringing observability, traceability, and decoupled control to your AI teams.

Why HerMAS

• Central router ownership The router owns routing decisions via structured contracts (Message, Belief, KnowledgeState, AgentResult).
• Policy-driven routing Decisions are driven by policies (RouteRule) with when, score, mode, retry, and fallback settings, rather than hardcoded logic.
• Trigger-driven execution Designed to start when a trigger event occurs rather than arbitrary user actions, via adapters and consumers.
• Robust execution flow Supports retry, fallback, halt, and parallel arbitration flows built directly into the routing lifecycle.
• Traceability and operations Explainable session traces, metrics, replay capabilities, and role-based access-control extensions.

Quickstart

Install

Install dependencies via uv:

uv sync

Run tests and checks

Run the full test suite :

uv run --with pytest python -m pytest

Run lint and format checks:

uv run --with ruff ruff check .
uv run --with ruff ruff format --check .

Product Surface

Surface	Role	Description
Message	Contract	The standard unit passed between router and agents.
Belief	Contract	A structured knowledge unit with confidence, source, and provenance.
KnowledgeState	State Management	Session-scoped state that stores beliefs, context, goal, visited routes, and artifacts.
RouteRule	Policy Engine	A routing policy unit with when, score, mode, retry, and fallback settings.
SessionResult	Contract	The final structured result returned by the router after a session halts.
Routing Trigger	Execution Flow	Abstract event layer designed to connect to Pub/Sub, queues, or other trigger sources.

Design Notes

• The router returns a structured SessionResult, not a raw agent response.
• policy_version is frozen per session and propagated to state, trace, and result metadata.
• Trigger duplication is seamlessly guarded by an in-memory deduplication layer.
• Trace store and explain services are built-in for interpretability.