Enterprise AI Chat Agent

Ein interner Assistent: Multi-Turn-Chat plus Dateisystem-Tools, bereitgestellt von einem echten MCP-Server, der nur dann verbunden wird, wenn tatsächlich eine Datei im Spiel ist.

• Architektur und Begründung → WRITEUP.md

• Konventionen, Leitplanken und Entscheidungsprotokoll → CLAUDE.md

• Wortwörtlich verwendete Prompts zum Erstellen des Agenten → PROMPTS.md

Was Sie installieren müssen, und in welcher Reihenfolge

Das Projekt läuft eigenständig. Traces und Verhaltens-Evals sind zwei getrennte optionale Schichten, jede mit eigenen Voraussetzungen — keine davon ist nötig, um den Agenten arbeiten zu sehen. Wählen Sie eine Stufe und bleiben Sie dabei.

Stufe 2 und 3 sind unabhängig — Sie können entweder eine, beide oder keine davon machen. Auf Stufe 1 bricht nichts, wenn Docker oder Node nicht vorhanden sind.

Related MCP server: Files MCP Server

Stufe 1 — Kern (erforderlich)

Voraussetzungen

Die exakte Versionen stehen in requirements.txt; die Bereiche in pyproject.toml.

Warum mcp unter 2.0.0 gehalten wird: Das MCP-Python-SDK v2 hat FastMCP in MCPServer umbenannt und das Modul mcp.server.fastmcp entfernt. langchain-mcp-adapters 0.3.2 deklariert dieselbe Obergrenze, sodass die beiden oberhalb davon nicht zusammen installiert werden können. Der Pin macht eine implizite Einschränkung explizit; es ist kein Downgrade.

Ausführen

# 0. clone
git clone https://github.com/Semmargl/enterprise-ai-chat-agent.git
cd enterprise-ai-chat-agent

# 1. environment
python3 -m venv .venv                 # or: uv venv --python 3.14
source .venv/bin/activate             # Windows: .venv\Scripts\activate
pip install -r requirements.txt       # or: uv pip install -r requirements.txt

# 2. secrets
cp .env.example .env
# then open .env and put your OpenRouter key in OPENROUTER_API_KEY

# 3. sample files to play with (the working folder starts empty)
mkdir -p workspace && cp samples/* workspace/

# 4. check the wiring before spending a token
pytest -q                             # expect: 44 passed, <1s, no network needed

# 5. start
python -m src.main

Checkpoint: Der Agent begrüßt Sie je nach Tageszeit und beantwortet eine Frage. Wenn Schritt 4 44 passed ausgegeben hat, sind Sandbox, Memory-Fenster und Tool-Sichtbarkeit ohne einen einzigen API-Aufruf bestätigt.

Der Agent führt ein normales Gespräch und verbindet sich beim ersten Dateiwunsch mit dem Dateidienst.

python -m src.main --thread report   # a separate, named conversation

Beenden Sie die Sitzung mit exit. Starten Sie sie mit demselben --thread erneut, und das Gespräch wird fortgesetzt: Der Zustand wird in SQLite gespeichert, nicht im Speicher gehalten.

Zwei Möglichkeiten, den MCP-Server auszuführen

Hinweis: Beide „Standards“: Der Code fällt auf 0 zurück, wenn die Variable nicht gesetzt ist, während .env.example mit MCP_AUTOSTART=1 ausgeliefert wird, damit eine frische Installation ohne zweites Terminal läuft. Kopieren Sie die Vorlage und Sie erhalten den Autostart; stellen Sie ohne .env bereit und Sie erhalten die Produktionsform.

In beiden Fällen wird nichts verbunden, bis Sie nach einer Datei fragen.

Dinge, die einen Test wert sind

Auf was Sie in den Logs achten sollten

Die Logs sind JSON, eine Zeile pro Ereignis, auf stderr. Die Schlüssel correlation_id (eine Benutzerrunde) und thread_id (eine Konversation) verbinden sie miteinander.

Zusätzlich: var/audit.jsonl ist das Audit-Protokoll: eine Zeile pro Tool-Aufruf mit Ergebnis und Dauer. Es werden Pfade, Größen und Hashes erfasst — nie Dateiinhalte, nie Geheimnisse.

Es liegt absichtlich in var/ und nicht in workspace/: Die eigenen Datei-Datei-Tools des Agenten erreichen jeden Pfad unter dem Sandbox-Wurzelverzeichnis, ein abgelegtes Audit-Protokoll könnte also von dem Prozess geändert werden, den es protokolliert. Die Checkpoint-Datenbank (var/checkpoints.sqlite) liegt aus demselben Grund außerhalb — sie ist das Gedächtnis des Agenten, nicht sein Arbeitsbereich. Beim Start wird eine Konfiguration abgelehnt, die eine dieser Dateien in die Sandbox legt.

Stufe 2 — Traces in Phoenix (optional)

Voraussetzung: Docker. Überspringen Sie diesen gesamten Abschnitt, wenn Docker nicht vorhanden ist — der Agent benötigt es nicht. Standard ist OTEL_EXPORTER=none, eine saubere Installation läuft also ganz ohne Collector.

Instrumentierung ist OpenTelemetry mit OpenInference-Semantik, sodass Spans LLM- und Tool-Aufrufe beschreiben statt generische HTTP-Arbeit. Der Exporter ist eine Umgebungsvariable, kein Codepfad — der Wechsel von Phoenix zu einem anderen OTLP-Backend ist eine Variable, kein Refactoring.

# 1. start Phoenix (first run pulls the image, ~1-2 min)
docker run -d --name phoenix -p 6006:6006 -p 4317:4317 arizephoenix/phoenix

# 2. wait for it, then confirm it answers
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6006    # expect: 200

# 3. run the agent pointed at it — two turns, one plain and one about a file
OTEL_EXPORTER=otlp OTEL_ENDPOINT=http://127.0.0.1:6006/v1/traces \
  python -m src.main --thread traces

Checkpoint: Öffnen Sie http://localhost:6006. Zwei Runden ergeben zwei Traces. Öffnen Sie den Datei-Trace — der Tool-Aufruf ist innerhalb der create_agent-Schleife unter dem Modellaufruf. Diese Versch pourlich ist der Punkt: das ist der Kontrollfluss des Agenten, nicht eine flache Liste von HTTP-Anfragen.

# when finished
docker stop phoenix && docker rm phoenix

Verwenden Sie OTEL_EXPORTER=console nur zum lokalen Debuggen: Diese Spans geben den gesamten Prompt und alle Tool-Ergebnisse aus — also den Dateiinhalte — die das Audit-Protokoll bewusst nie speichert.

Stufe 3 — Verhaltens-Evals (optional)

Voraussetzung: Node.js 18+. Diesen Abschnitt überspringen, falls Node nicht installiert ist; pytest deckt bereits alles Deterministische ab.

pytest deckt ab, was sich ohne Netzwerk prüfen lässt: Pfad-Konfinierung, Fensterarithmetik, Tool-Sichtbarkeit. Was nicht leisten kann, ist zu testen, ob sich das System nach einem echten Neun-Turn-Gespräch mit einem echten Modell noch korrekt verhält. Diese drei Fälle stehen in promptfooconfig.yaml und laufen gegen den tatsächlichen Agenten — nicht gegen das bloße Modell — über scripts/promptfoo_provider.py.

# 1. install
npm i -g promptfoo@latest

# 2. the venv must be active and .env filled in — the provider spawns the real agent
source .venv/bin/activate

# 3. run
NODE_NO_WARNINGS=1 PROMPTFOO_DISABLE_TELEMETRY=1 PROMPTFOO_DISABLE_UPDATE=1 \
  promptfoo eval -o results.json; echo "EXIT=$?"

# 4. browse the results (optional)
promptfoo view

Checkpoint: EXIT=0, und in results.json steht "successes": 3, "failures": 0, "errors": 0. Der vollständige Lauf dauert 40–60 Sekunden — also bei mehreren neun echten Runden plus zwei Single-Turn-Gesprächen.

Wie bei Ihnen zwei Dinge, die aussehen wie Fehler, aber keine sind. Die Fortschrittsleiste kann bei 0% | 0/3 hängen bleiben: Node schreibt eine Warnung in dieselbe Terminalzeile und überschreibt sie. Lassen Sie sich durch EXIT und die JSON-Datei leiten, nicht durch die Leiste. Und assertions.cached > 0 bei einer Wiederholung ist der Grader, der seine eigenen Aufrufe cached — die Agenten-Konversationen selbst werden niemals gecacht cache. Fügen Sie --no-cache hinzu, für einen vollcache kalt Lauf.

Das kostet Tokens. Drei Testfälle, insgesamt elf Runden, außerdem LLM-Grader für die Rubrik-Assertions — ganz ohne auf denselben OPENROUTER_API_KEY aus Ihrer .env-Datei.

Konfiguration

Jede Einstellung ist in .env.example dokumentiert. Am stärksten verändern das Verhalten: MCP_AUTOSTART, SANDBOX_ROOT, MAX_FILE_BYTES, HISTORY_WINDOW_MESSAGES, SUMMARIZATION_TRIGGER_MESSAGES, OTEL_EXPORTER.

.env steht seit dem ersten Commit in .gitignore und wurde nie committet:

git log --all --full-history -- .env    # returns nothing