> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Erste Schritte mit AgentEye

> AgentEye – Dokumentation für den Einstieg.

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](/de/agenteye/github-token) für genaue Schritte und erforderliche Berechtigungen.

```bash theme={null}
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:**

```bash theme={null}
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`:

```bash theme={null}
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret
```

**Stack starten:**

```bash theme={null}
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](/de/agenteye/deployment).

***

## 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:

```bash theme={null}
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](/de/agenteye/api-keys).

***

## Schritt 4: Collector installieren

Installieren Sie den Collector-Daemon auf jedem Rechner, auf dem Ihre KI-Agenten laufen.

**Binärdatei herunterladen (Linux x86\_64):**

```bash theme={null}
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](/de/agenteye/collector-installation), das den Download für jede Plattform auflistet – der obige Befehl installiert eine Linux-Binärdatei, die auf anderen Plattformen nicht läuft.

**Konfigurieren:**

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

**Daemon starten:**

```bash theme={null}
agenteye-collector start
```

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

```bash theme={null}
agenteye-collector flush
```

Für Docker-, systemd- und launchd-Setup siehe [enterprise-docs/collector-installation.md](/de/agenteye/collector-installation).

***

## Schritt 5: Python SDK installieren

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

```bash theme={null}
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`:

```python theme={null}
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](/de/agenteye/python-sdk).

***

## 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.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="Der AgentEye-Anmeldebildschirm, der einen Einmal-Code an Ihre E-Mail-Adresse sendet" width="2880" height="1800" data-path="agenteye/images/login.png" />

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.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="Der Live-Events-Stream, farblich nach Event-Typ codiert und nach Umgebung, Agent und Session filterbar" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

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:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="Die Sessions-Liste, eine Zeile pro Lauf, mit Status-Indikatoren und Bewertungs-Badges" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

Zur Konfiguration der Session-Bewertung siehe [enterprise-docs/evaluation-suite.md](/de/agenteye/evaluation-suite).

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:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="Der Git-artige Ausführungsgraph einer Session neben ihrer Event-Timeline, mit dem Tool/Modell/Hook-Aufschlüsselungs-Panel" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="Die Bibliothek gespeicherter Abfragen: ein Raster wiederverwendbarer Abfragen, sowohl integrierte Voreinstellungen als auch benutzerdefinierte" width="2880" height="1800" data-path="agenteye/images/queries.png" />

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="Der SQL-Abfrage-Composer mit einer gespeicherten Abfrage, einer Schema-Seitenleiste und einem Live-Ergebnisraster" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="Ein aus gespeicherten Abfragen erstelltes Dashboard: eine Ereignisse-pro-Stunde-Linie, ein Fehler-nach-Typ-Balken, ein Latenz-Flächendiagramm und Tokens nach Modell" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **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](/de/agenteye/alerts).

***

## Nächste Schritte

* [Deployment](/de/agenteye/deployment): Für die Produktion absichern
* [API Keys](/de/agenteye/api-keys): Zugriff verwalten
* [Troubleshooting](/de/agenteye/troubleshooting): Probleme diagnostizieren