agent-platform/docs/PLAN.md

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)

-- 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)

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)

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/