feat: agent platform initial commit

- FastAPI + HTMX UI: dashboard, agents CRUD, chat, audit, tools - SQLite schema: agents, conversations, messages, audit, sessions - Code-agent sync (agents/*.py -> DB on startup) - MCP client with health check - Token auth (Bearer + session) - LiteLLM integration via llm.py - Docker Compose: agent-platform + mcp-tools services - Smoke tests pass: /health 200, /api/agents 200, / 401
2026-07-05 22:18:00 +02:00
commit 64b840c94c
30 changed files with 2690 additions and 0 deletions
@@ -0,0 +1,381 @@
+# 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/`