E.D.D.I — Multi-Agent Orchestration Middleware for Conversational AI

E.D.D.I (Enhanced Dialog Driven Interface) is a production-grade, config-driven multi-agent orchestration middleware for conversational AI. It coordinates users, AI agents, and business systems through intelligent routing, persistent memory, and API orchestration — without writing code.

Built with Java 25 and Quarkus. Ships as a Red Hat-certified Docker image. Selected as a UNIDO Trusted Partner for Industrial AI. Native support for MCP (Model Context Protocol), A2A (Agent-to-Agent), Slack, OpenAPI, and OAuth 2.0.

Website · Documentation · License: Apache 2.0

📑 Table of Contents

• 🏁 Quick Start
• 💡 Why EDDI?
• 📸 See It In Action
• ✨ Features
• 📖 Documentation
• 📋 Compliance & Privacy
• 🏗️ Development
  • Prerequisites
  • Quarkus Dev Mode
  • Maven Command Reference
  • Build & Docker
  • Kubernetes
• 🤝 Contributing
• 🔒 Security
• 📜 Code of Conduct

🏁 Quick Start

The fastest way to get EDDI running is the one-command installer. It sets up EDDI + your choice of database via Docker Compose and points you at the dashboard, where the Platform Operator (or the form-based agent wizard) creates your first AI agent for you.

Linux / macOS / WSL2:

curl -fsSL https://raw.githubusercontent.com/labsai/EDDI/main/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/labsai/EDDI/main/install.ps1" -OutFile "install.ps1"
Unblock-File .\install.ps1
.\install.ps1

Requires Docker. The wizard auto-generates a unique vault encryption key for secret management.

bash install.sh --defaults                 # All defaults, no prompts
bash install.sh --db=postgres --with-auth  # PostgreSQL + Keycloak
bash install.sh --full                     # Everything enabled (DB + auth + monitoring)
bash install.sh --local                    # Build Docker image from local source

./mvnw package -DskipTests    # Build the Java app
bash install.sh --local        # Build Docker image + start containers

🔄 Updating

The installer creates an eddi CLI wrapper that makes updating easy:

eddi update

This pulls the latest Docker image from the registry and restarts the containers. It works even when the same tag (e.g. latest) was re-published — Docker always checks the remote digest for changes.

eddi command not found? The CLI lives at ~/.eddi/eddi (Linux/macOS) or ~/.eddi/eddi.cmd (Windows). Either restart your terminal so the PATH takes effect, or use the full path:

# Linux / macOS
~/.eddi/eddi update

# Windows (PowerShell)
& "$HOME\.eddi\eddi.cmd" update

cd ~/.eddi
docker compose --env-file .env -f docker-compose.yml pull
docker compose --env-file .env -f docker-compose.yml up -d

🐳 Docker Compose (Manual)

If you prefer manual control over Docker Compose:

# Default (EDDI + MongoDB)
docker compose up

# PostgreSQL instead of MongoDB — a complete stack, so it is NOT layered on
# docker-compose.yml (an overlay cannot un-declare the base's mongodb service)
docker compose -f docker-compose.postgres-only.yml up

# With Keycloak authentication
docker compose -f docker-compose.yml -f docker-compose.auth.yml up

# With Prometheus + Grafana monitoring
docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up

# With a local LLM — Ollama on the same Docker network, reachable as
# http://ollama:11434 (no host.docker.internal needed)
docker compose -f docker-compose.yml -f docker-compose.ollama.yml up -d

# Auth + monitoring + NATS together (overlays stack in any combination)
docker compose -f docker-compose.yml -f docker-compose.auth.yml \
  -f docker-compose.monitoring.yml -f docker-compose.nats.yml up

Available compose overlays: docker-compose.auth.yml (Keycloak), docker-compose.monitoring.yml (Prometheus+Grafana), docker-compose.nats.yml (NATS JetStream), docker-compose.ollama.yml (local LLM), docker-compose.chroma.yml (vector store), docker-compose.local.yml (build from source). docker-compose.postgres-only.yml is a complete standalone stack rather than an overlay — use it on its own, not with -f docker-compose.yml.

The Ollama overlay pulls llama3.2:3b on first start and keeps models in a named volume; override with OLLAMA_PULL_MODEL=qwen3:4b, or set it empty to skip the pull. It also sets EDDI_OLLAMA_DEFAULT_BASE_URL, so the agent wizard and the setup API pre-fill a base URL that resolves from inside the container — the one thing that trips up every first local-LLM agent, because localhost there is the container, not the host.

docker pull labsai/eddi    # Pull latest from Docker Hub

→ hub.docker.com/r/labsai/eddi

💡 Why EDDI?

Most multi-agent frameworks (LangGraph, CrewAI, AutoGen) are Python/Node libraries — great for prototyping, hard to govern in production. EDDI approaches from the opposite direction: a deterministic engine built to safely govern non-deterministic AI.

"The engine is strict so the AI can be creative." — Project Philosophy

📸 See It In Action

📊 Dashboard Platform overview with active agents, workflows, quick actions, and recent conversations	🤖 Agent Fleet All deployed agents at a glance with status, descriptions, and one-click chat
💬 Live Conversation Real-time conversation with visible actions, step timing, and tool calls	🗣️ Multi-Agent Debate Peer Review with phased discussion: Opinion → Critique → Revision → Synthesis
🛡️ Secrets Vault Envelope-encrypted secrets with rotation tracking, checksums, and per-agent access control	💰 Tenant Quotas Rate limits, cost budgets, and live usage monitoring per tenant

More screenshots: LLM Config, Logs, User Memory, Schedules, Agent Detail

⚡ LLM Task Configuration System prompt, model parameters, cascading, RAG, context window, and budget settings	📋 Real-Time Logs Live log stream with per-call cost tracking, token counts, warnings, and errors
🧠 Persistent User Memory Cross-session memory with categorized entries, visibility scoping, and conflict detection	⏰ Scheduled Execution Cron jobs and heartbeats with fire history, retry logic, and dead-letter tracking
🔧 Agent Detail Full agent config: environments, workflows, A2A, security, capabilities, and memory policy

✨ Features

🤖 Multi-Agent Orchestration

• 🔀 Intelligent Routing — Direct conversations to different agents based on context, rules, and intent
• 🗣️ Group Conversations — Multi-agent debates with 7 built-in discussion styles: Round Table, Peer Review, Devil's Advocate, Delphi, Debate, Task Force, and Negotiation
• 🔄 Follow-up & Continue — After a group discussion completes, follow up with any specific member agent or continue all phases with a new question — agents retain full context across rounds
• 💬 Slack Integration — Deploy agents to Slack channels and run multi-agent debates directly in threads
• 🪆 Nested Groups — Compose groups of groups for tournament brackets, red-team vs blue-team, and panel reviews
• 🤖 Dynamic Agents — Create, recruit, and delegate to new agents at runtime during group discussions with configurable guardrails
• 🗳️ Group Voting — VOTE phases collect explicit ballots (majority or approval, weighted, quorum-gated) and record a decision with the full tally, the raw ballots, and the losing side's dissents
• 📋 Shared Artifacts — A blackboard members co-edit through tools, with compare-and-set concurrency and declarative JSON-Schema, regex, or max-length validators — never an LLM merge
• 🧑‍🤝‍🧑 Humans as Members — A person can hold a seat in the group: their turn pauses the discussion until they answer, or the configured timeout policy resolves it
• 🎚️ Facilitator — An optional facilitator agent is briefed at checkpoints and picks one move from a config-enumerated list (end, extend, call a vote, recruit, escalate) — bounded adaptation, never free-form orchestration
• 🤝 Negotiation — Typed two-party bargaining: positions → proposals → a quoted concession ledger → signed acceptances, with arbitration skipped once agreement is reached
• 🎯 Bid-Based Assignment — Contract-Net-lite task auctions: eligible members bid blind in parallel, highest confidence wins, with deterministic tie-break and fallback to role assignment
• 🎓 Team Memory — A RETRO phase distils lessons into team-owned group memory, so they surface in every member's later discussions — institutional knowledge that compounds run over run
• 🏢 Standing Teams — A persistent workspace per group: a backlog that survives between discussions, cron cadences that pull from it, cross-run retry of unverified work, and running team metrics
• 📦 Preset Group Templates — Five packaged, validated group configs (research pod, editorial team, ops task force, decision board, negotiation table) — instantiate by assigning agents to named roles, not by hand-writing phases
• 👥 Managed Conversations — Intent-based auto-routing with one conversation per user per intent
• 🎯 Capability Matching — Discover and route to agents by skill, confidence score, and custom attributes
• 🧙 Platform Operator — Meta-agent that reads and operates the deployment — including creating other agents — with every write behind a human approval gate

🧠 LLM Provider Support (12 Providers)

• 🔀 Multi-Model Cascading — Start with cheap/fast models, escalate to powerful ones based on confidence (details)
• 📋 JSON Response Mode — jsonResponseFormat policy (auto | on | off) negotiates structured JSON output across all execution paths with provider-aware rules
• 🔧 Tool Calling — Native function/tool calling across all providers that support it
• 🗄️ Tool Result Caching — Per-tool cache scoping (GLOBAL, USER, CONVERSATION) to avoid redundant calls; fail-safe to USER on misconfiguration

🔗 Standards & Interoperability

EDDI implements open standards — not proprietary APIs:

💭 Memory & Context Management

• 💾 Persistent User Memory — Agents remember facts, preferences, and context across conversations via structured key-value entries with visibility scoping (global, agent, group)
• 🧠 LLM Memory Tools — Built-in tools agents can call to read, write, and search their own persistent memory
• 💤 Dream Consolidation — Background memory maintenance: stale entry pruning, contradiction detection, and fact summarization (inspired by Anthropic's research on background memory consolidation)
• 🪟 Token-Aware Windowing — Intelligent context packing with model-specific tokenizer support and anchored opening steps
• 📝 Rolling Summary — Incremental LLM-powered summarization of older turns with a Conversation Recall Tool for drill-back into compressed history
• 🔧 Property Extraction — Config-driven slot-filling with longTerm / conversation / step scoping — EDDI's importance extraction mechanism
• 🛡️ Memory Policy (Commit Flags) — Strict write discipline marks failed task output as uncommitted (hidden from LLM context) and injects concise error digests for graceful degradation
• 🧹 Tool Context Ceiling — maxToolContextTokens caps tool output within a single turn (default 60k tokens), evicting oldest tool exchanges to prevent provider context-window errors while preserving tool-call pairing
• 🔄 Conversation State — Full history with undo/redo support

📚 RAG (Retrieval-Augmented Generation)

• 📦 7 Embedding Providers — OpenAI, Ollama, Azure OpenAI, Mistral, Bedrock, Cohere, Vertex AI
• 🗄️ 6 Vector Stores — pgvector, Chroma, In-Memory, MongoDB Atlas, Elasticsearch, Qdrant
• 🌐 httpCall RAG — Zero-infrastructure RAG via any search API (BM25, Elasticsearch, custom)
• 📥 REST Ingestion API — Async document ingestion with status tracking

🛠️ Built-In AI Agent Tools

📎 Multimodal Attachments

• 📤 3 Input Paths — URL reference, base64 inline, or file upload (POST /conversations/{id}/attachments with multipart/form-data)
• 🗄️ DB-Agnostic Storage — GridFS (MongoDB) or bytea (PostgreSQL) via IAttachmentStore SPI with grant-based access control and per-tenant quotas
• 📄 Hybrid PDF Extraction — PDFs are auto-extracted to text (shared AttachmentTextExtractor) and forwarded as inline context to any LLM, not just vision models
• 🔍 readAttachment Tool — Agents can recall attachments from earlier turns in multi-turn conversations
• 🧠 Model Capability Gating — ModelCapabilityService routes images to vision-capable LLMs and falls back to text metadata for others
• 🔀 Content-Type Routing — contentTypeMatcher behavior rule condition routes image/*, application/pdf, etc. to different workflows
• 👥 Group Parity — Attachments fan out with grant injection so group member agents can access the original user's files
• 🗑️ GDPR Cleanup — deleteByConversation() cascades to attachment storage when conversations are erased

⏰ Scheduled Execution & Heartbeats

• 🫀 Heartbeat Triggers — Periodic agent wake-ups at configurable intervals for proactive behavior (inspired by OpenClaw's heartbeat architecture)
• ⏲️ Cron Scheduling — Standard cron expressions for timed agent execution
• 🔄 Conversation Strategies — persistent (reuse same conversation across fires) or new (fresh context each time)
• 📊 Fire Logging — Complete execution history with status, duration, cost tracking, and retry logic
• 🌙 Dream Cycles — Scheduled background memory consolidation with cost ceilings per run

📈 Smart Model Cascading

• 📉 Cost Optimization — Try cheap/fast models first, escalate to powerful models only when confidence is low
• 📊 4 Confidence Strategies — Structured output, heuristic, judge model, or none
• 💰 Per-Conversation Budgets — Automatic cost tracking with budget caps and eviction
• 🏢 Tenant Cost Ceilings — Monthly cost budgets per tenant with automatic enforcement
• 🔢 Tenant Agent Quotas — maxAgentsPerTenant enforcement on agent deployment

✋ Human-in-the-Loop Governance

• 🚦 Turn-Level Approval — PAUSE_CONVERSATION action halts the entire pipeline; new user input returns 409 Conflict until a human resumes
• 🔧 Per-Tool-Call Gating — Individual tool invocations can require human approval before execution, with glob-pattern allow/exempt lists across built-in, HTTP, MCP, A2A, dynamic, and memory tools
• 👥 Group Phase Approval — Multi-agent discussion phases can require human sign-off at PHASE or TASK granularity
• 🧑‍🤝‍🧑 Humans in the Room — Beyond approving, a human can be a full group member with their own speaking turn; a facilitator can also pause a discussion to put a question to a named principal
• ⏱️ Timeout Policies — WAIT_INDEFINITELY, AUTO_APPROVE, AUTO_REJECT, or ABORT when humans don't respond in time
• 🔁 No-Progress Guard — Detects infinite approval loops (identical pause fingerprints after automated decisions) and breaks the cycle
• 💬 Slack Approvals — Interactive Block Kit cards with redacted argument previews and approver whitelists
• 🔌 MCP Approvals — External clients can list pending approvals and approve/reject via MCP tools
• 🔄 Crash Recovery — Pending approvals survive server restarts; timeout timers are re-armed automatically

🔐 Enterprise Security & Compliance

⚙️ Configuration-Driven Architecture

• 📄 JSON Configs, Not Code — Agent behavior defined in versioned, diffable JSON documents
• 🔧 Lifecycle Pipeline — Pluggable task pipeline: Input → Parse → Rules → API/LLM → Output
• 📦 Composable Agents — Agents assembled from reusable, version-controlled workflows and extensions
• 🧪 Behavior Rules — IF-THEN logic engine for routing, orchestration, and business logic
• 📤 Import / Export — Agents portable as ZIP files with automatic secret scrubbing on export
• 🔄 Agent Sync — Live instance-to-instance sync with structural matching, content diffing, and selective resource picking — no ZIP intermediary needed
• 📝 Prompt Snippets — Reusable, versioned system prompt building blocks available as {{snippets.safety_rules}}
• 📎 Content Type Routing — MIME-based behavior rule conditions for multimodal attachment routing

🚀 Cloud-Native & Observable

• 🐳 One-Command Install — Interactive wizard sets up EDDI + database via Docker
• ☸️ Kubernetes / OpenShift — Kustomize overlays, Helm charts, PDB, NetworkPolicy (no HPA: EDDI is single-writer per conversation, so both delivery paths pin one replica)
• 📊 Prometheus & Grafana — 50+ Micrometer metrics at /q/metrics (tools, vault, memory, scheduling, conversations). Pre-built Grafana dashboard included
• 🔭 OpenTelemetry Tracing — Per-task distributed traces via OTLP (Jaeger, Tempo, Datadog). Every pipeline task emits a span named eddi.pipeline.task carrying eddi.task.id, eddi.task.type, eddi.task.index, eddi.conversation.id and eddi.agent.id. The equivalent metric tags are un-prefixed (task.id, task.type)
• 🩺 Health Checks — Liveness & readiness probes at /q/health/live and /q/health/ready
• 🔄 NATS JetStream — Async event bus for distributed processing
• 🛟 Error Handling & Recovery — Automatic retry with exponential backoff, MCP circuit breakers (3 failures / 60s cooldown), LLM response validation (onEmpty / onTruncation / onRefusal), streaming timeout retry, and admin endpoint to reset stuck conversations
• ⚡ Virtual Threads — Java 25 virtual threads for true OS-level concurrency (no Python GIL or Node.js event loop bottleneck)
• 🗃️ DB-Agnostic — Choose MongoDB or PostgreSQL; switch with one env var. Single Docker image for both
• 🏗️ Red Hat Certified — Container certification with automated preflight checks in CI/CD

📖 Monitoring Guide: See docs/monitoring/monitoring-guide.md for architecture overview, metrics reference, alerting rules, and a production checklist.

🖥️ Manager Dashboard & Chat UI

• 🎨 React 19 Manager — Modern admin dashboard for agent building, testing, deployment, and monitoring
• 💬 Chat Widget — Embeddable React chat UI with SSE streaming and Keycloak auth
• 🔍 Audit Trail Viewer — Timeline-based compliance and debugging UI
• 📋 Logs Panel — Live SSE log streaming + searchable history
• 🔑 Secrets Manager — Write-only vault UI with copy-reference support
• 🌍 11 Languages — English, German, Spanish, French, Portuguese, Chinese, Japanese, Korean, Arabic (RTL), Hindi, Thai

📖 Documentation

📋 Compliance & Privacy

EDDI provides built-in infrastructure for regulatory compliance:

🏗️ Development

Prerequisites

Windows users: Replace ./mvnw with .\mvnw.cmd in all commands below.

Quarkus Dev Mode

Dev mode starts the application with live reload — code changes are picked up automatically without restarting:

# Linux / macOS
./mvnw compile quarkus:dev

# Windows (PowerShell)
.\mvnw.cmd compile quarkus:dev

Then open http://localhost:7070. The Quarkus Dev UI is available at http://localhost:7070/q/dev.

Dev mode also enables:

• Continuous testing — press r in the terminal to re-run tests on changes
• Dev UI — browse endpoints, CDI beans, configuration, and health checks
• Live reload — Java and resource changes apply instantly

💡 Secrets Vault: To use the secrets vault (storing API keys encrypted), set the master key before starting:

# Linux/macOS
export EDDI_VAULT_MASTER_KEY=my-dev-passphrase

# Windows (PowerShell)
$env:EDDI_VAULT_MASTER_KEY = "my-dev-passphrase"

# Or in a .env file (already in .gitignore)
echo "EDDI_VAULT_MASTER_KEY=my-dev-passphrase" > .env

Without this, the vault is disabled and secret management returns HTTP 503. Any passphrase works for local development. See Secrets Vault for production setup.

Maven Command Reference

target/site/jacoco/index.html

Build & Docker

# Build app + Docker image
./mvnw clean package '-Dquarkus.container-image.build=true'

# Build without container (for install.sh --local)
./mvnw package -DskipTests

# Generate third-party licenses (Red Hat certification)
./mvnw package -Plicense-gen -DskipTests

☸️ Kubernetes

No shipped manifest creates the eddi-secrets Secret that holds the vault master key — a Secret in the manifests would be reconciled on every kubectl apply and overwrite a live key, making everything already encrypted with it undecryptable. So the Secret is created out-of-band, before the first apply. Without it the EDDI pod sits in ContainerCreating (MountVolume.SetUp failed: secret "eddi-secrets" not found) and never starts.

# Kustomize overlays — create the vault Secret first, then apply
bash k8s/create-secrets.sh                 # PowerShell 7: pwsh -File .\k8s\create-secrets.ps1
kubectl apply -k k8s/overlays/mongodb/     # MongoDB backend
kubectl apply -k k8s/overlays/postgres/    # PostgreSQL backend

# Quickstart (one-file manifest; same Secret step, see the Kubernetes Guide)
kubectl apply -f https://raw.githubusercontent.com/labsai/EDDI/main/k8s/quickstart.yaml

# Helm (renders the Secret itself, so the key is a required value)
helm install eddi ./helm/eddi \
  --set eddi.vaultMasterKey="$(openssl rand -base64 24)" \
  --namespace eddi --create-namespace

Includes overlays for auth (Keycloak), monitoring (Prometheus/Grafana), NATS messaging, Ingress, and production hardening (PDB, NetworkPolicy — deliberately no HPA). See the Kubernetes Guide for details, including the Keycloak upgrade note for existing installs.

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details on setting up your development environment, code style, commit conventions, and the pull request process.

Every PR is automatically checked by CI (build + tests), CodeQL (security), dependency review, and AI-powered code review.

🔒 Security

EDDI ships with security-by-default for production deployments:

• Authentication enforced — AuthStartupGuard fails startup if OIDC is disabled in production without explicit opt-out
• Secrets encrypted at rest — Envelope encryption (PBKDF2 → AES-256-GCM) with per-deployment salt. Never plaintext in DB
• SSRF protection — All LLM tool HTTP calls go through SafeHttpClient with private IP blocking, redirect validation, and scheme enforcement
• Security headers — X-Content-Type-Options, X-Frame-Options, Content-Security-Policy configured out of the box
• CI/CD security gates — Every push/PR is scanned by:
  • CodeQL — Semantic SAST analysis with security-extended queries
  • Trivy — CVE scanning for both filesystem dependencies and Docker images (blocking on CRITICAL/HIGH)
  • Gitleaks — Git history scanning to prevent secret/credential leakage
  • ZAP — DAST API scanning against the live Docker image (report-only)
  • CycloneDX — SBOM generation for supply chain transparency
  • Jazzer — Coverage-guided fuzz testing for security-critical parsers (PathNavigator, MatchingUtilities)
  • All actions SHA-pinned to prevent supply-chain attacks

For vulnerability reports, see our Security Policy. For architecture details, see Security Architecture.

📜 Code of Conduct

This project follows the Contributor Covenant Code of Conduct.