Emiyaaaaa/HiveMind
A Python-first runtime layer for multi-agent systems, with persistent run state, streaming execution events, and a pluggable orchestration interface.
Hivemind – Runtime layer for multi‑agent applications
What it is – Hivemind is a Python‑first, production‑grade runtime that sits between an LLM‑oriented agent framework (LangGraph, AutoGen, CrewAI, etc.) and the outside world. It gives every run a durable, queryable state, streams execution events, and lets you swap the underlying orchestration framework without rewriting persistence or API code.
Why it exists – Most open‑source agent libraries focus on the prompt‑to‑tool flow and assume everything runs in‑process. When you need to run agents as a service you also need:
- a database that survives restarts,
- ordered step/message logs for debugging and audit,
- live event feeds for UI or SDKs,
- cancellation/retry/resume semantics,
- a stable API that can work with any orchestration backend.
Hivemind provides exactly those runtime concerns while leaving the choice of orchestration framework to you.
Core capabilities (as described in the README)
| Feature | What you get |
|---|---|
| Orchestrator adapters | A pluggable system; the default adapter wraps LangGraph, and you can add adapters for AutoGen, CrewAI, or custom frameworks via a simple Python plugin. |
| Persistent execution model | Database tables (Run, Step, Message, ToolCall, Checkpoint) store the full lifecycle of every run, making it observable and replayable. |
| Server‑Sent Events (SSE) | Run state changes are pushed to clients over an SSE endpoint, so front‑ends can watch progress without polling. |
| Outbound webhooks | When a run finishes (success, failure, cancellation, or waiting for human input) a configurable webhook is called, with optional HMAC signing and retry logic. |
| Admin console | A lightweight Next.js UI lists runs, shows step‑by‑step details, and subscribes to the live SSE stream. |
| Multi‑language stack | Java 21 + Spring Boot 3 for the HTTP/SSE API, Python 3.12 workers (asyncio, uv), PostgreSQL 16 for durable state, Redis for job queues and live events, and TypeScript/Next.js for the console. |
Architecture at a glance
Next.js console <--SSE/REST--> Java Spring Boot API <--Redis jobs/events--> Python worker (uv) <--adapter--> LangGraph / Echo / …
|
▼
PostgreSQL (state)
- API tier (Java) – Exposes a versioned
/v1/*REST API and an SSE bridge, handles RBAC via API keys or OIDC tokens, and enqueues jobs in Redis. - Worker tier (Python) – Consumes jobs, runs the selected orchestrator adapter, writes step/message records to Postgres, and publishes live events back to Redis for the API to forward.
- Persistence – SQLAlchemy models with Alembic migrations store the immutable run history.
- Event bus – Redis streams/pub‑sub provide at‑least‑once delivery for jobs, cancellations, and live updates.
- Console – Next.js 15 app using React Query to fetch runs and listen to SSE.
Getting started (quick‑start steps from the README)
- Prerequisites – Docker,
uv(Python package manager), Node 20+, JDK 21, Maven 3.9. - Start infrastructure –
docker compose up -d postgres redis. - Create DB schema –
cd backend && uv sync && uv run alembic upgrade head. - Run the Python worker –
AGENTFLOW_WORKER_MODE=queue uv run python -m app.worker. - Run the Java API –
cd backend-java && mvn spring-boot:run. - Run the console –
cd frontend && npm install && npm run dev. - Open
http://localhost:3000– the UI talks to the API, which in turn schedules jobs for the worker.
The README also shows how to create an agent and start a run via curl calls, then listen to the live event stream with curl -N …/events/<run_id>.
Typical use cases
- Production‑grade agent services – Turn a prototype LangGraph or AutoGen graph into a durable microservice with audit logs and live monitoring.
- Multi‑tenant SaaS platforms – The API supports tenant‑scoped RBAC, making it suitable for hosted AI‑agent platforms.
- Observability & debugging – Because every step/message/tool call is persisted, you can replay runs, build dashboards, or export logs for compliance.
- Hybrid orchestration – Swap between different orchestration back‑ends (e.g., LangGraph for LLM flows, Echo for simple echo bots) without changing the client API.
License
Apache 2.0 – permissive open‑source license allowing commercial use.
Bottom line – Hivemind is not an LLM model or a new agent framework; it is the runtime that makes multi‑agent systems reliable, observable, and easy to operate in production. If you already use a Python‑based agent library and need persistence, streaming, and a stable API, Hivemind provides that glue layer out of the box.
Related
- Project
- Project
- Project
- Project
- Project