# Agent-Platform — Projekt-Plan

> Erstellt: 2026-07-05
> Status: Draft v1
> Ziel: Business-taugliche Agent-Plattform auf Coolify, 2 Container, MCP-Tools

---

## 1. Projekt-Übersicht

**Was wir bauen:**
Eine kleine, schlanke Multi-Agent-Plattform für interne Business-Use-Cases.

**Problem das wir lösen:**
- Agent Zero ist zu mächtig/komplex für Business-Agents
- Tool-Kapselung in Agent Zero erfordert Bastelei
- Wir brauchen eine schlanke Alternative mit klarer MCP-Tool-Architektur

**Outcome:**
Zwei Docker-Container auf coolify-01, deploybar via Coolify, mit:
- Web-UI für Agent-Verwaltung und Chat
- Audit-Trail aller Aktionen
- MCP-Tool-Container mit ersten Business-Tools
- Skaliert auf 50+ User / 5+ parallel Agents

---

## 2. Architektur

### 2-Container-Setup

```
┌─────────────────────────────────────────────┐
│  Container 1: agent-platform                │
│  - FastAPI + LiteLLM + Pydantic AI          │
│  - HTMX-UI (kein JS-Build)                  │
│  - SQLite (lokal)                           │
│  - Audit-Log, Auth                          │
│  Port: 8000                                 │
│  RAM: 256 MB, CPU: 0.5 Core                 │
└──────────────────┬──────────────────────────┘
                   │ MCP-Protokoll (HTTP)
                   ▼
┌─────────────────────────────────────────────┐
│  Container 2: mcp-tools                     │
│  - fastmcp Server                           │
│  - Business-Tools (KB, Email, HTTP, Files)  │
│  - Restart-Policy: unless-stopped           │
│  Port: 8501                                 │
│  RAM: 128 MB, CPU: 0.25 Core                │
└─────────────────────────────────────────────┘
```

### Komponenten-Verantwortlichkeiten

**agent-platform:**
- LLM-Loop (LiteLLM)
- Agent-Definitionen (hardcoded Python)
- HTTP-API (FastAPI)
- Web-UI (HTMX)
- Persistenz (SQLite)
- Audit-Log
- Auth (API-Token)

**mcp-tools:**
- Tool-Implementierungen (Python)
- MCP-Protokoll (HTTP via fastmcp)
- Keine Business-Logik
- Keine Agent-KI
- Stateless (jeder Call unabhängig)

---

## 3. Tech-Stack

| Schicht | Technologie | Begründung |
|---|---|---|
| LLM-Aufrufe | LiteLLM 1.40+ | 100+ Provider, einheitliche API |
| Agent-Loop | Pydantic AI 0.4+ | Type-safe, MCP eingebaut |
| Backend | FastAPI 0.115+ | Async, OpenAPI auto |
| UI | HTMX 2.0 + Jinja2 + Tailwind CDN | Kein Build-Step, klein |
| DB | SQLite 3.45+ | Zero-Config, embedded |
| Tool-Container | fastmcp 0.4+ | MCP-Standard |
| Validation | Pydantic v2 | Type-Safety überall |
| Container | python:3.12-slim | Klein, aktuell |
| Deploy | Docker + Coolify | Auf coolify-01 |

**Was wir NICHT nutzen:**
- ❌ LangChain / LangGraph (zu schwer)
- ❌ React / Next.js (zu viel RAM)
- ❌ Postgres (overkill)
- ❌ Redis / Celery (overkill)

---

## 4. Datenmodell (SQLite)

```sql
-- Agent-Definitionen (zur Laufzeit aus agents/*.py geladen, hier gecached)
CREATE TABLE agents (
    id TEXT PRIMARY KEY,           -- z.B. "kunden_email"
    name TEXT NOT NULL,
    description TEXT,
    system_prompt TEXT,
    allowed_tools TEXT,            -- JSON-Array
    enabled BOOLEAN DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Konversationen
CREATE TABLE conversations (
    id TEXT PRIMARY KEY,
    agent_id TEXT REFERENCES agents(id),
    user_id TEXT,
    title TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Messages
CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    conversation_id TEXT REFERENCES conversations(id),
    role TEXT NOT NULL,            -- "user" | "assistant" | "tool"
    content TEXT,
    tool_calls TEXT,               -- JSON
    tool_results TEXT,             -- JSON
    token_count INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Audit-Log
CREATE TABLE audit (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    agent_id TEXT,
    user_id TEXT,
    action TEXT,                   -- "tool_call" | "llm_call" | "auth" | "error"
    target TEXT,                   -- Tool-Name oder LLM-Model
    args TEXT,                     -- JSON
    result TEXT,                   -- JSON oder Status
    duration_ms INTEGER
);

-- Sessions / Auth
CREATE TABLE sessions (
    token TEXT PRIMARY KEY,
    user_id TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    expires_at TIMESTAMP
);
```

---

## 5. Komponenten mit Zeilen-Schätzung

### agent-platform (~1840 Zeilen)

| Datei | Zeilen | Zweck |
|---|---|---|
| `config.py` | 40 | Settings, Env-Loading |
| `db.py` | 130 | SQLite + Models |
| `llm.py` | 70 | LiteLLM-Wrapper |
| `mcp_client.py` | 120 | MCP-Client für Tool-Container |
| `agent.py` | 180 | Agent-Loop |
| `audit.py` | 60 | Audit-Helper |
| `auth.py` | 70 | Token-Auth |
| `api.py` | 250 | FastAPI-Endpoints |
| `agents/base.py` | 80 | Abstract Agent |
| `agents/kunden_email.py` | 90 | Erster Agent |
| `agents/recherche.py` | 70 | Zweiter Agent |
| `templates/base.html` | 60 | Layout |
| `templates/agents.html` | 80 | Liste |
| `templates/chat.html` | 120 | Chat |
| `templates/tools.html` | 60 | MCP-Status |
| `templates/audit.html` | 80 | Audit-Viewer |
| `static/style.css` | 200 | Minimal-CSS |
| `pyproject.toml` | 25 | Dependencies |
| `Dockerfile` | 25 | Container |
| **Gesamt** | **~1810** | |

### mcp-tools (~250 Zeilen)

| Datei | Zeilen | Zweck |
|---|---|---|
| `server.py` | 60 | fastmcp Setup |
| `tools/search_kb.py` | 40 | KB-Suche |
| `tools/fetch_url.py` | 30 | HTTP-Request |
| `tools/list_files.py` | 30 | Datei-Listing |
| `tools/save_note.py` | 40 | Notiz speichern |
| `tools/send_email.py` | 50 | E-Mail (Draft) |
| `requirements.txt` | 4 | fastmcp, httpx, pydantic |
| `Dockerfile` | 10 | Container |
| **Gesamt** | **~264** | |

### Deployment

| Datei | Zeilen | Zweck |
|---|---|---|
| `docker-compose.yml` | 40 | Beide Services |
| `.env.example` | 15 | Env-Vorlage |
| `deploy/coolify.json` | 30 | Coolify-Metadata |
| **Gesamt** | **~85** | |

---

## 6. Task-Graph (Reihenfolge)

```
T01: pyproject.toml + Dockerfile (agent-platform)
T02: config.py + db.py + Models
T03: llm.py (LiteLLM-Wrapper + Token-Tracking)
T04: audit.py + auth.py
T05: mcp_client.py (MCP-Client)
T06: agent.py (Agent-Loop — Herzstück)
T07: agents/base.py + agents/kunden_email.py (erster Agent)
T08: api.py (FastAPI-Endpoints)
T09: templates/* + static/* (HTMX-UI)
T10: Lokal testen (curl + Browser)

--- Pause, Freigabe ---

T11: mcp-tools/server.py + 5 Beispiel-Tools
T12: Dockerfile mcp-tools
T13: docker-compose.yml (beide Container)
T14: Lokal starten (docker compose up)
T15: Smoke-Tests (API + UI + Tools)

--- Pause, Freigabe ---

T16: Coolify-Deployment vorbereiten
T17: Auf coolify-01 deployen
T18: Smoke-Test Production
T19: Dokumentation + Runbook
```

**Geschätzter Aufwand:**
- T01-T10: 6-8 Stunden (MVP lokal)
- T11-T15: 2-3 Stunden (MCP-Container lokal)
- T16-T19: 2-3 Stunden (Deployment + Doku)

**Gesamt: 10-14 Stunden, verteilt auf 2-3 Tage**

---

## 7. Ressourcen-Budget

### Container-Limits

| Container | RAM Min | RAM Max | CPU Min | CPU Max |
|---|---|---|---|---|
| agent-platform | 64 MB | 256 MB | 0.1 | 0.5 |
| mcp-tools | 32 MB | 128 MB | 0.05 | 0.25 |

### Storage

| Was | Größe |
|---|---|
| Image agent-platform | ~150 MB |
| Image mcp-tools | ~100 MB |
| SQLite DB (1000 Konversationen) | ~5-10 MB |
| Audit-Log (10000 Einträge) | ~2-5 MB |

### LLM-Kosten (Schätzung)

Bei GPT-4o-mini:
- Input: ~$0.15 / 1M Token
- Output: ~$0.60 / 1M Token

Bei 100 User × 10 Messages/Tag × ~500 Token avg:
- Input: ~500k Token/Tag = ~$0.08
- Output: ~100k Token/Tag = ~$0.06
- **Gesamt: ~$0.14/Tag = ~$4/Monat**

---

## 8. Deployment-Plan

### Coolify-Konfiguration

1. Neues Projekt in Coolify: `agent-platform`
2. Service 1: `agent-platform`
   - Source: Git-Repo oder lokales Dockerfile
   - Port: 8000
   - Domain: `agents.media-on.de`
   - Env-Vars: LLM_API_KEY, MCP_SERVER_URL
3. Service 2: `mcp-tools`
   - Source: lokales Dockerfile
   - Port: 8501 (intern, nicht öffentlich)
   - Domain: nur intern erreichbar
4. Docker-Netzwerk: beide Services im selben Coolify-Network

### Env-Vars (agent-platform)

```bash
LLM_PROVIDER=openrouter          # oder openai, anthropic, ollama
LLM_API_KEY=***                  # via Coolify-Secret
LLM_MODEL=anthropic/claude-3.5-sonnet
MCP_SERVER_URL=http://mcp-tools:8501/mcp
AUTH_TOKEN=***                   # via Coolify-Secret
DB_PATH=/data/agent-platform.db
LOG_LEVEL=info
```

### Env-Vars (mcp-tools)

```bash
KB_PATH=/data/knowledge
EMAIL_DRAFT_PATH=/data/drafts
HTTP_TIMEOUT=10
LOG_LEVEL=info
```

---

## 9. Risiken

| Risiko | Wahrscheinlichkeit | Impact | Mitigation |
|---|---|---|---|
| MCP-Protokoll bricht bei Updates | Mittel | Mittel | Version pinnen, Tests |
| LLM-API-Änderungen | Niedrig | Mittel | LiteLLM abstrahiert |
| SQLite-Performance bei vielen Usern | Niedrig | Niedrig | Bei >10k Messages → Postgres |
| Container startet nicht auf Coolify | Niedrig | Hoch | Erst lokal voll testen |
| Token-Kosten explodieren | Mittel | Mittel | Hard-Limit pro User |
| Tool-Sicherheit (SSRF, Path-Traversal) | Mittel | Hoch | Input-Validation, Sandboxing |

---

## 10. Freigabe-Punkte

### Gate 1 — Vor Implementation
- [ ] Plan-Architektur genehmigt
- [ ] Stack-Entscheidungen bestätigt
- [ ] Datenmodell ok

### Gate 2 — Vor MCP-Container
- [ ] agent-platform läuft lokal
- [ ] Erste Tool-Calls funktionieren
- [ ] UI ist nutzbar

### Gate 3 — Vor Deployment
- [ ] Beide Container laufen lokal
- [ ] Smoke-Tests grün
- [ ] Audit-Log zeigt alle Aktionen

### Gate 4 — Vor Production
- [ ] Coolify-Deployment getestet
- [ ] Doku vorhanden
- [ ] User hat final freigegeben

---

## 11. Was wir NICHT in V1 machen

- Multi-Tenant (mehrere Firmen)
- Multi-LLM pro Agent
- Voice-Interface
- Bildgenerierung
- Vector-DB / echte RAG (kommt in V2)
- 10+ Beispiel-Agents
- E-Mail-Versand (nur Draft in V1)
- SSO / OAuth (nur Token-Auth)
- Tests / CI (kommt nach V1)

---

## 12. Nächste Schritte

1. **JETZT:** Freigabe vom User für Gate 1
2. **Dann:** T01-T10 (MVP lokal)
3. **Pause:** Smoke-Test + User-Freigabe
4. **Dann:** T11-T15 (MCP-Container)
5. **Pause:** Integration-Test
6. **Dann:** T16-T19 (Coolify-Deployment)

---

**Stand:** 2026-07-05 20:52
**Author:** Agent Zero (a0_software_orchestrator)
**Repo:** `/a0/usr/workdir/agent-platform/`