Erste Schritte mit AgentEye

Diese Anleitung führt Sie durch eine vollständige AgentEye-Einrichtung: Bereitstellung des Servers und Dashboards, Installation des Collectors auf einem Agent-Rechner sowie die Instrumentierung Ihres Python-Agent-Codes.

Was ist AgentEye?

AgentEye ist eine selbst gehostete Observability- und Evaluierungsplattform für KI-Agenten. Sie zeichnet auf, was Ihre Agenten tun – jeden Schritt eines Laufs – und bewertet automatisch die Qualität jedes abgeschlossenen Laufs. So können Sie das Verhalten Ihrer Agenten in der Produktion nachverfolgen und Regressionen erkennen, bevor Ihre Nutzer sie bemerken. Die Daten fließen in eine Richtung: Ihr Agent-Code sendet Events über das Python SDK → ein leichtgewichtiger Collector-Daemon bündelt und übermittelt sie an den Server → Events und Analysen werden in ClickHouse gespeichert (operativer Zustand wie Organisationen, Nutzer, API-Schlüssel, Dashboards und gespeicherte Abfragen liegt in Postgres) → alles wird im Dashboard exploriert. Was Sie erhalten:

Events — der rohe, schrittweise Verlauf jedes Agent-Laufs (Tool-Aufrufe, Modell-Aufrufe, Hooks, Fehler).
Sessions — diese Events zusammengefasst zu einer Zeile pro Lauf, jeweils automatisch bewertet und bewertet.
Evaluierungen — Qualitätswerte, die von Ihren eigenen Evaluierungs-Services erzeugt werden, damit Qualitätseinbrüche ohne manuellen Review sichtbar werden.
Abfragen & Dashboards — gespeicherte ClickHouse-SQL-Abfragen über Ihre Daten, als gemeinsame, organisationsweite Dashboards dargestellt.
Alerts & Incidents — Schwellenwertregeln, die Sie benachrichtigen (E-Mail, Slack, Webhook, im Dashboard) sowie ein Incident-Workflow zur Triage.
CLI & KI-Assistent — ein Terminal-Client (agenteye) und ein Dashboard-integrierter Assistent für Fragen in natürlicher Sprache.

Sie betreiben alles in Ihrer eigenen Infrastruktur – als einzelner Docker-Compose-Stack (diese Anleitung), als produktives Kubernetes-Setup oder als einzelner co-located Pod. Der Rest dieser Anleitung richtet den Compose-Stack vollständig ein.

Schritt 1: Authentifizierung

Alle AgentEye-Artefakte werden aus der GitHub-Organisation agenteye-enterprise bereitgestellt. Als Enterprise-Entwickler können Sie Ihren eigenen GitHub PAT generieren. Folgen Sie enterprise-docs/github-token.md für genaue Schritte und erforderliche Berechtigungen.

export AGENTEYE_TOKEN=<your-github-pat>

# Authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

Schritt 2: Server und Dashboard bereitstellen

Der Server empfängt Events von Collectors und macht sie abfragbar; das Dashboard ist der Ort, an dem Sie diese explorieren. Aufgenommene Events und Analysen liegen in ClickHouse (dem erforderlichen Analytics-Store), während Postgres den operativen Zustand wie Organisationen, Nutzer, API-Schlüssel, Dashboards und gespeicherte Abfragen vorhält. Veröffentlichte Compose-Datei herunterladen:

mkdir -p ./agenteye
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o ./agenteye/docker-compose.yml
cd agenteye

Secrets setzen: Erstellen Sie eine .env-Datei, damit das Deployment nicht mit den Standard-admin-Zugangsdaten läuft. Setzen Sie mindestens ADMIN_KEY und POSTGRES_PASSWORD:

POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

Stack starten:

docker compose up -d

Dadurch wird der vollständige Stack hochgefahren, einschließlich des erforderlichen ClickHouse-Analytics-Stores und eines optionalen Redis-Caches, neben Server und Dashboard. ClickHouse muss bereit sein, damit der Server starten kann. Der Server lauscht nun unter http://localhost:8080 und das Dashboard unter http://localhost:3000. Für Produktions-Deployments (eigenes Postgres, TLS, Reverse Proxy) siehe enterprise-docs/deployment.md.

Schritt 3: API-Schlüssel für den Collector erstellen

Jeder Collector authentifiziert sich mit einem bereichsgebundenen API-Schlüssel. Verwenden Sie den in Schritt 2 gesetzten ADMIN_KEY, um einen zu erstellen:

curl -s -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}'

Den key-Wert legen Sie selbst fest; verwenden Sie ihn in der Collector-Konfiguration in Schritt 4. Vollständiges Key-Management finden Sie unter enterprise-docs/api-keys.md.

Schritt 4: Collector installieren

Installieren Sie den Collector-Daemon auf jedem Rechner, auf dem Ihre KI-Agenten laufen. Binärdatei herunterladen (Linux x86_64):

VERSION=0.0.1-beta.13
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-collector-linux-x86_64'
chmod +x agenteye-collector-linux-x86_64
sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector

Hiermit wird das Linux x86_64-Build heruntergeladen. Für macOS (Apple Silicon oder Intel), Linux arm64 oder ein Setup mit Docker / systemd / launchd siehe collector-installation.md, das den Download für jede Plattform auflistet – der obige Befehl installiert eine Linux-Binärdatei, die auf anderen Plattformen nicht läuft.

Konfigurieren:

mkdir -p ~/.agenteye
cat > ~/.agenteye/config.json <<EOF
{
  "url": "http://your-server-host:8080/events",
  "key": "the-key-from-step-3"
}
EOF

Daemon starten:

agenteye-collector start

Konnektivität mit einem einmaligen Flush prüfen (beendet sich nach dem Leeren ausstehender Events):

agenteye-collector flush

Für Docker-, systemd- und launchd-Setup siehe enterprise-docs/collector-installation.md.

Schritt 5: Python SDK installieren

Installieren Sie das Wheel von GitHub Releases auf jedem Rechner, auf dem Sie Agent-Code instrumentieren möchten.

VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install agenteye-${VERSION}-py3-none-any.whl

Schritt 6: Ihren Agenten instrumentieren

Fügen Sie Events in Ihren Agent-Code ein. Senden Sie mindestens agent_start und agent_end:

import agenteye

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="my-agent",
    goal="answer the user query",
)

# your agent logic here

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="my-agent",
    outcome="success",
)

Events werden gepuffert und alle 500 ms nach $AGENTEYE_HOME/events/ (bzw. ~/.agenteye/events/, falls AGENTEYE_HOME nicht gesetzt ist) geschrieben. Der Collector nimmt sie automatisch auf. Vollständige Event-API unter enterprise-docs/python-sdk.md.

Schritt 7: Events im Dashboard anzeigen

Öffnen Sie http://your-dashboard-host:3000 und melden Sie sich an. AgentEye sendet Ihnen einen Einmal-Code per E-Mail (oder einen Magic Link mit einem Klick), sodass kein Passwort verwaltet werden muss.

Der AgentEye-Anmeldebildschirm, der einen Einmal-Code an Ihre E-Mail-Adresse sendet

Nach der Anmeldung zeigt die Seite Events einen Live-Verlauf aller aufgenommenen Events. Filtern Sie nach session_id oder agent_id, um in einen bestimmten Lauf einzutauchen.

Der Live-Events-Stream, farblich nach Event-Typ codiert und nach Umgebung, Agent und Session filterbar

Die Seite Sessions fasst diese Events zu einer Zeile pro Lauf zusammen. AgentEye bewertet abgeschlossene Sessions automatisch, sodass jeder Lauf bewertet wird und Qualitätsregressionen ohne manuellen Review sichtbar werden; der aktuelle Bewertungswert erscheint auf einen Blick in jeder Zeile:

Die Sessions-Liste, eine Zeile pro Lauf, mit Status-Indikatoren und Bewertungs-Badges

Zur Konfiguration der Session-Bewertung siehe enterprise-docs/evaluation-suite.md. Klicken Sie auf eine Session, um ihren Ausführungsgraphen zu öffnen – eine Git-ähnliche Ansicht, wie Agenten, Tools, Hooks und Modell-Aufrufe über die Zeit verlaufen sind, mit parallelen Sub-Agenten in eigenen Spuren und einer laufspezifischen Aufschlüsselung in der rechten Spalte:

Der Git-artige Ausführungsgraph einer Session neben ihrer Event-Timeline, mit dem Tool/Modell/Hook-Aufschlüsselungs-Panel

Schritt 8: Explorieren, visualisieren und Alerts einrichten

Sobald Events einfließen, verwandeln die Analyse-Seiten die rohe Aktivität in Antworten, sodass Sie das Agentenverhalten messen, Erkenntnisse im Team teilen und sofort benachrichtigt werden, wenn etwas regressiert. Dashboard-Seiten sind organisationsweit, daher sind die URLs in der Adressleiste mit Ihrem Org-Slug prefixiert (/<org>/…).

Abfragen (/<org>/queries): Starten Sie mit einer Bibliothek gespeicherter, wiederverwendbarer Abfragen über Ihre Events und Evaluierungen (integrierte Voreinstellungen und eigene)…

Die Bibliothek gespeicherter Abfragen: ein Raster wiederverwendbarer Abfragen, sowohl integrierte Voreinstellungen als auch benutzerdefinierte

…öffnen Sie dann eine im SQL-Composer, um sie anzupassen und mit Live-Ergebnissen auszuführen:

Der SQL-Abfrage-Composer mit einer gespeicherten Abfrage, einer Schema-Seitenleiste und einem Live-Ergebnisraster

Dashboards (/<org>/dashboards): Heften Sie Abfragen als Linien-, Balken-, Flächen- oder Kreisdiagramm-Kacheln in gemeinsame, organisationsweite Dashboards.

Ein aus gespeicherten Abfragen erstelltes Dashboard: eine Ereignisse-pro-Stunde-Linie, ein Fehler-nach-Typ-Balken, ein Latenz-Flächendiagramm und Tokens nach Modell

Alerts (/<org>/alerts): Wandeln Sie jeden Schwellenwert in eine Benachrichtigungsregel um, die per E-Mail, Slack, Webhook oder im Dashboard informiert. Siehe enterprise-docs/alerts.md.

Nächste Schritte

Deployment: Für die Produktion absichern
API Keys: Zugriff verwalten
Troubleshooting: Probleme diagnostizieren

​Was ist AgentEye?

​Schritt 1: Authentifizierung

​Schritt 2: Server und Dashboard bereitstellen

​Schritt 3: API-Schlüssel für den Collector erstellen

​Schritt 4: Collector installieren

​Schritt 5: Python SDK installieren

​Schritt 6: Ihren Agenten instrumentieren

​Schritt 7: Events im Dashboard anzeigen

​Schritt 8: Explorieren, visualisieren und Alerts einrichten

​Nächste Schritte