diag-agent

An LLM Agent for creating software architecture diagrams with autonomous syntax validation and design feedback.

Features

• 🤖 Autonomous diagram generation with syntax validation and design feedback loop
• ✅ Smart description validation - LLM checks descriptions for completeness and clarity before generation
• 🎨 Multi-format support via Kroki integration (PlantUML, C4, BPMN, Mermaid, etc.)
• 🚀 Flexible deployment: CLI tool, MCP server, or Python library
• 🔒 Privacy-first: Local-first approach with optional remote rendering
• 🔌 LLM-agnostic: Works with any LLM via LiteLLM (Anthropic, OpenAI, etc.)
• ⚡ Context-efficient: Minimal token consumption through optimized prompts

Why Use diag-agent?

Before: Manual Diagram Creation ❌

Creating diagrams manually means wrestling with syntax, debugging errors, and iterating repeatedly:

# Attempt 1: Write BPMN XML manually
$ vim order-process.bpmn
# ... 200 lines of XML later ...

# Attempt 2: Test with Kroki
$ curl -X POST https://kroki.io/bpmn/svg --data-binary @order-process.bpmn
# ❌ Error: "Syntax error at line 47: Missing closing tag"

# Attempt 3: Fix the error
$ vim order-process.bpmn
# ... fix line 47 ...

# Attempt 4: Test again
$ curl -X POST https://kroki.io/bpmn/svg --data-binary @order-process.bpmn
# ❌ Error: "Invalid reference: Flow_1 sourceRef not found"

# Attempt 5: Debug references
# ... 30 minutes later ...
# ❌ Still not working...

Result: Hours spent debugging syntax instead of designing architecture.

After: With diag-agent ✅

Let the LLM handle syntax while you focus on architecture:

# Single command with natural language description
$ uv run diag-agent create \
  "BPMN collaboration with Customer and Shop pools. \
   Customer: submit order, receive confirmation. \
   Shop: receive order, process payment, ship product." \
  --type bpmn

# diag-agent automatically:
# 1. Validates your description for completeness ✓
# 2. Generates valid BPMN XML ✓
# 3. Validates syntax with Kroki ✓
# 4. Refines based on errors (if any) ✓
# 5. Checks design quality with vision LLM ✓

✓ Generated in 1 iteration (3.2s)
✓ Output: diagrams/order-process.bpmn, order-process.svg

Result: Valid, well-designed diagram in seconds—no syntax debugging required.

Key Advantages

Manual Creation	With diag-agent
❌ Hours of syntax debugging	✅ Natural language description
❌ Trial-and-error iterations	✅ Autonomous validation loop
❌ No design feedback	✅ Vision-based quality checks
❌ Format-specific expertise required	✅ Works across 20+ diagram types
❌ Manual refinement cycles	✅ Self-healing error correction

Visual Comparison

Same prompt: "Erstelle ein PlantUML Context-Diagramm eines Webshops"

LLM Direct (No Validation) ❌ Generated without diag-agent orchestration: Issues: Cluttered relationships (external systems → users) 3 actors (includes warehouse worker, may be out of scope) No layout optimization Direct bidirectional flows not typical for C4

With diag-agent (Validated & Refined) ✅ Same prompt, orchestrated through diag-agent: Improvements: ✓ Clean C4 Context boundaries ✓ Focused scope (2 key actors) ✓ Layout optimization (LAYOUT_TOP_DOWN, hidden relations) ✓ Clear system-to-system relationships ✓ 2 iterations with syntax validation

Both diagrams generated from identical prompt. Left: Direct LLM call. Right: diag-agent orchestration with validation loop.

How it Works

The orchestrator coordinates a feedback loop between the calling LLM and validation services:

Orchestrator Workflow Diagrams

📊 Sequence Diagram (PlantUML) - Shows temporal flow and interactions

Sequence diagram showing the temporal flow between Calling LLM, Orchestrator, LLM Client, and Kroki components.

📊 BPMN Collaboration Diagram - Shows process structure with pools and lanes

BPMN collaboration diagram with two pools (Calling LLM and diag-agent System) and three lanes (Orchestrator, LLM Client, Kroki). Shows the complete process flow including iteration loops, validation gates, and message flows.

Key workflow steps:

1. Description Validation: LLM checks your description for completeness and clarity

   • Invalid → Returns specific questions for refinement
   • Valid → Proceeds to generation

2. Iterative Generation Loop (max 5 iterations):

   • LLM generates diagram code from prompt
   • Kroki validates syntax by attempting to render
   • Optional: Vision LLM analyzes design quality (PNG-capable diagrams only)
   • On errors: Refines prompt with specific feedback

3. Output: Valid diagram in requested formats (source, SVG, PNG, PDF)

The workflow ensures high-quality diagrams through autonomous validation and refinement.

Quick Start

CLI Usage

# Clone the repository
git clone https://github.com/docToolchain/diag-agent.git
cd diag-agent

# Install locally
uv pip install .

# Configure API key
export ANTHROPIC_API_KEY=your_key_here

# Generate a diagram (using uv run - no venv activation needed)
uv run diag-agent create "C4 context diagram for API gateway"

MCP Server (for Claude Desktop)

# Clone and install with MCP support
git clone https://github.com/docToolchain/diag-agent.git
cd diag-agent
uv pip install ".[mcp]"

# Add to Claude Desktop config (~/.config/Claude/claude_desktop_config.json)
{
  "mcpServers": {
    "diag-agent": {
      "command": "python",
      "args": ["-m", "diag_agent.mcp.server"],
      "env": {
        "ANTHROPIC_API_KEY": "your_key_here",
        "KROKI_URL": "http://localhost:8000"
      }
    }
  }
}

Then in Claude Desktop:

"Create a C4 context diagram for an e-commerce platform"

Docker

# Clone repository and build Docker image
git clone https://github.com/docToolchain/diag-agent.git
cd diag-agent
docker build -t diag-agent .

# Run with Docker
docker run --rm \
  -e ANTHROPIC_API_KEY=your_key_here \
  -v $(pwd)/diagrams:/diagrams \
  diag-agent \
  create "User authentication flow"

# Or use Docker Compose for full stack (CLI + Kroki)
docker-compose up -d kroki
docker-compose run --rm diag-agent-cli create "architecture diagram"

# MCP Server with Docker Compose
docker-compose --profile mcp up -d

See User Guide - Docker Deployment for details.

Documentation

• User Guide - Comprehensive reference with all CLI commands, configuration, and MCP setup
• Tutorial - Hands-on examples for different diagram types and use cases
• Architecture - Technical architecture documentation (arc42)

CLI Commands

# Generate diagrams
uv run diag-agent create "diagram description" [OPTIONS]

# Options:
#   --type TYPE        Diagram type (default: plantuml)
#   --output DIR       Output directory (default: ./diagrams)
#   --format FORMATS   Comma-separated formats: png,svg,pdf,source
#   --force, -f        Skip description validation

# Browse examples
uv run diag-agent examples list [--type TYPE]
uv run diag-agent examples show TYPE/NAME

# Manage local Kroki server
uv run diag-agent kroki start|stop|status|logs

Description Validation

By default, diag-agent validates your description before generating diagrams. If the description is unclear or incomplete, you'll receive specific questions:

❌ Die Beschreibung enthält Unklarheiten:

1. Which type of BPMN diagram is needed? (process/collaboration/choreography)
2. Who performs the "approval step"? Specify role or system name.

Bitte rufe das Tool mit einer präziseren Beschreibung erneut auf.
Oder nutze --force um diese Validierung zu überspringen.

Use --force to skip validation when needed (e.g., for automated workflows or intentionally vague descriptions).

See User Guide - CLI Commands for detailed documentation.

Supported Diagram Types

• C4 Architecture: c4plantuml - Context, Container, Component diagrams
• UML: plantuml - Sequence, Class, Component, Deployment, etc.
• BPMN: bpmn - Business processes and workflows
• Mermaid: mermaid - Flowcharts, Sequence, Gantt, etc.
• Database: erd - Entity Relationship Diagrams
• And 20+ more via Kroki

See Tutorial - Diagram Types for practical examples.

Installation

Requirements

• Python 3.10+ (for native installation)
• Docker (optional, for containerized deployment or local Kroki server)
• LLM API key (Anthropic, OpenAI, or other)
• uv package manager - Install uv

Local Installation (Recommended)

# Clone repository
git clone https://github.com/docToolchain/diag-agent.git
cd diag-agent

# Install locally
uv pip install .

# Or install with MCP server support
uv pip install ".[mcp]"

# Or install for development (editable mode)
uv pip install -e ".[dev,mcp]"

Docker Installation

# Clone repository
git clone https://github.com/docToolchain/diag-agent.git
cd diag-agent

# Build image locally
docker build -t diag-agent .

# Run
docker run --rm \
  -e ANTHROPIC_API_KEY=your_key \
  -v $(pwd)/diagrams:/diagrams \
  diag-agent create "architecture diagram"

See User Guide - Docker Deployment for full documentation.

Configuration

Configure via environment variables or .env file:

# LLM Configuration
export LLM_PROVIDER=anthropic        # anthropic, openai, azure, etc.
export LLM_MODEL=claude-sonnet-4     # Model name
export ANTHROPIC_API_KEY=your_key    # API key

# Kroki Configuration
export KROKI_URL=http://localhost:8000  # Local or remote Kroki server

# Agent Configuration
export MAX_ITERATIONS=10             # Max LLM iterations
export ENABLE_DESIGN_FEEDBACK=true   # Enable design feedback loop

See User Guide - Configuration for all options.

Examples

Generate Different Diagram Types

# C4 Context Diagram
uv run diag-agent create "C4 context diagram for e-commerce platform" --type c4plantuml

# BPMN Process
uv run diag-agent create "Order fulfillment process" --type bpmn

# Mermaid Flowchart
uv run diag-agent create "CI/CD pipeline stages" --type mermaid

# Database Schema
uv run diag-agent create "User management database schema" --type erd

Use Local Kroki Server

# Start local Kroki (requires Docker)
uv run diag-agent kroki start

# Generate diagram using local server
uv run diag-agent create "architecture diagram"

# Stop Kroki when done
uv run diag-agent kroki stop

Custom Output

# Custom output directory and formats
uv run diag-agent create "System architecture" \
  --type c4plantuml \
  --output ./docs/architecture \
  --format svg,pdf,source

See Tutorial for step-by-step examples.

Development

# Install development dependencies
uv pip install -e ".[dev,mcp]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=diag_agent --cov-report=html

# Format code
black src tests
ruff check src tests

# Type checking
mypy src

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT