Leopold
64b840c94c
- 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
382 lines
11 KiB
Markdown
382 lines
11 KiB
Markdown
# 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/`
|