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

The --local flag is for contributors testing pre-release builds:

./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

If the eddi CLI isn't available, run the equivalent docker commands from your install directory (~/.eddi by default):

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

Adjust the -f flags to match your setup (e.g. add -f docker-compose.auth.yml if using Keycloak).

🐳 Docker Compose (Manual)

If you prefer manual control over Docker Compose:

# Default (EDDI + MongoDB)
docker compose up

# PostgreSQL instead of MongoDB
EDDI_DATASTORE_TYPE=postgres docker compose -f docker-compose.yml -f docker-compose.postgres.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.postgres.yml / docker-compose.postgres-only.yml, docker-compose.local.yml (build from source).

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

✨ 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

• 🏦 Secrets Vault — Envelope encryption (PBKDF2 + AES-256) with tenant-scoped DEK/KEK rotation. Never plaintext in DB
• 🛡️ SSRF Protection — All tools validate URLs against private IPs, internal hostnames, and non-HTTP schemes before any request
• 🔒 Sandboxed Evaluation — Recursive-descent math parser only. No eval(), no script engines, no reflection-based execution
• 🔑 OAuth 2.0 / Keycloak — Multi-tenant authentication, authorization, and role-based access control
• ✍️ Agent Signing — Ed25519 cryptographic identity per agent; audit entries signed with agent private keys
• 🚫 No Dynamic Code Execution — Custom logic runs in external MCP servers, outside the EDDI security perimeter

• 📜 Audit Ledger — Every agent decision recorded in a write-once, HMAC-secured, append-only ledger
• 🔍 Compliance Startup Checks — Advisory warnings on boot for TLS and database encryption gaps
• 🗑️ GDPR Orchestration — One-call cascading erasure across 6 stores + audit trail pseudonymization
• 📤 Data Portability — Complete user data export (memories, conversations, audit entries) via REST and MCP

⚙️ 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, HPA, PDB, NetworkPolicy
• 📊 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 spans with task.id, task.type, conversation.id, and agent.id
• 🩺 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