# Hypocaust: A Backend Orchestration System for Long-Running Intelligent Agent Workflows

> Hypocaust is an intelligent agent workflow orchestration system developed using Java and Spring Boot. It adopts an event sourcing architecture, transactional outbox pattern, and semantic tool discovery mechanism. It supports converting natural language tasks into versioned artifacts (images, audio, videos, scripts, etc.) and provides real-time SSE stream updates and selective re-run capabilities.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-01T17:14:42.000Z
- 最近活动: 2026-04-01T17:22:57.025Z
- 热度: 154.9
- 关键词: Hypocaust, AI代理, 工作流编排, 事件溯源, Java, Spring Boot, 智能代理, SSE, 产物管理, 语义工具发现
- 页面链接: https://www.zingnex.cn/en/forum/thread/hypocaust
- Canonical: https://www.zingnex.cn/forum/thread/hypocaust
- Markdown 来源: floors_fallback

---

## Hypocaust: Core Overview

# Hypocaust: Core Overview

Hypocaust is an open-source backend system developed by lukeashford, built with Java 21 and Spring Boot. It orchestrates long-running AI agent workflows, addressing key challenges like reliability, real-time feedback, and efficient iteration. Key features include:
- Event sourcing for state consistency
- Transactional outbox for distributed system reliability
- Semantic tool discovery
- Real-time SSE updates
- Versioned artifact management and selective partial re-run

Its goal is to provide a robust infrastructure for production-grade AI agent applications.

## Background & Problem Statement

# Background & Problem Statement

As AI agent applications grow, orchestrating long-running workflows (minutes or longer) presents critical challenges:
- Ensuring asynchronous execution and state consistency after crashes
- Providing real-time progress feedback to users
- Integrating diverse AI/deterministic tools flexibly
- Managing versioned artifacts (images, audio, videos) and efficient iterations

Hypocaust is tailored to tackle these issues.

## Architecture & Design Patterns

# Core Architecture & Design

## Event Sourcing
- Append-only event storage for all state changes
- Enables audit trails, time travel, and fault recovery

## Transactional Outbox
- Solves double-write problem (atomic DB updates + message publishing)
- Uses `bigserial` for event order

## SSE Real-Time Updates
- Pushes progress via Server-Sent Events
- Supports gapless reconnection with `Last-Event-ID`

## Artifact Lifecycle
- State machine: `GESTATING` → `MANIFESTED` (or `FAILED/CANCELLED`)
- Version chain via `supersedes_id`

## Bounded Executor
- Prevents web thread blocking, handles concurrent long tasks

## Technology Stack
- Backend: Java21 + Spring Boot
- DB: PostgreSQL
- Containerization: Podman (Postgres, pgAdmin, FFmpeg sidecar)
- Media: FFmpeg sidecar

## API Design
- REST endpoints: `POST /tasks` (submit), `GET /task-executions/{id}/events` (SSE)
- OpenAPI docs (`/v3/api-docs`) and Swagger UI

## Quick Start
- Requirements: Java21, Podman, OpenAI/Anthropic keys
- Commands: `./gradlew pods-create` (start dependencies), `./gradlew bootRun` (run app)

## Project Status
- Active development, FFmpeg decomposer integration in progress

## Workflow Execution Model

# Workflow Execution

## Plan-Clarify-Execute
1. **Plan**: Analyze task, split into sub-tasks
2. **Clarify**: Ask user for missing info
3. **Execute**: Generate artifacts

## Decomposer Pattern
- Split complex tasks into independent sub-tasks
- Each sub-task can retry/recover separately

## Selective Partial Re-run
- Only re-run affected sub-tasks when requirements change
- Improves iteration efficiency for creative workflows

## Tool System & Semantic Discovery

# Tool System

## SemanticSearchToolRegistry
- Embeds tool descriptions, uses vector similarity to find best tools

## Core Tools
1. **generate_creative**: AI-based, uses RAG for model selection, fallback on failure
2. **ffmpeg_process**: Deterministic media tool, LLM constructs API requests from OpenAPI schema

## Tool Lifecycle
- Follows `AbstractArtifactTool` for consistent, observable calls

## Application Scenarios & Value

# Application Scenarios

## Creative Content Generation
- Multimedia stories, marketing materials, personalized content

## Intelligent Workflow Automation
- Data pipelines, document generation, media processing chains

## Research & Experiment Platforms
- AI experiment management, A/B testing, collaborative creation

## Comparison with Others
| Feature | Hypocaust | LangChain | Temporal |
|---------|-----------|-----------|----------|
| Event Sourcing | ✅ | ❌ (custom) | ✅ |
| Artifact Management | ✅ | ❌ (custom) | ❌ (custom) |
| Semantic Tool Discovery | ✅ | ❌ | ❌ |
| SSE Real-Time | ✅ | ❌ (custom) | ❌ (custom) |
| AI Native | ✅ | ✅ | ❌ |

## Conclusion & Future Outlook

# Conclusion & Future

Hypocaust is a specialized infrastructure for long-running AI workflows, focusing on reliability, real-time feedback, and efficiency. It solves critical production pain points, letting developers focus on business logic.

As AI agents move to production, systems like Hypocaust will be essential for ensuring scalability and reliability. The project is actively developing, with FFmpeg decomposer integration ongoing.