Leopoldadmin/agent-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2672bd86e610196195dcb5a3a8fb399111402eaa
agent-platform/docs/PLAN.md
T

382 lines
11 KiB
Markdown
Raw Normal View History

feat: agent platform initial commit
2026-07-05 22:18:00 +02:00
# 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/`
Reference in New Issue Copy Permalink