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

# Démarrage avec AgentEye

> Documentation de démarrage avec AgentEye.

Ce guide vous accompagne pas à pas dans la configuration complète d'AgentEye : déploiement du serveur et du tableau de bord, installation du collecteur sur une machine d'agent, et instrumentation de votre code d'agent Python.

***

## Qu'est-ce qu'AgentEye ?

AgentEye est une **plateforme d'observabilité et d'évaluation auto-hébergée pour les agents IA**. Elle enregistre ce que font vos agents — chaque étape d'une exécution — et note automatiquement la qualité de chaque exécution terminée, afin que vous puissiez observer le comportement de vos agents en production et détecter les régressions avant vos utilisateurs.

Les données circulent dans un seul sens : votre code d'agent émet des **événements** via le **SDK Python** → un démon **collecteur** léger les regroupe et les envoie au **serveur** → les événements et les analyses sont stockés dans **ClickHouse** (l'état opérationnel comme les organisations, les utilisateurs, les clés API, les tableaux de bord et les requêtes sauvegardées réside dans **Postgres**) → vous explorez tout dans le **tableau de bord**.

Ce que vous obtenez :

* **Événements** — la trace brute, étape par étape, de chaque exécution d'agent (appels d'outils, appels de modèles, hooks, erreurs).
* **Sessions** — ces événements regroupés en une ligne par exécution, chacune **évaluée et notée automatiquement**.
* **Évaluations** — scores de qualité produits par vos propres services d'évaluation, pour que les baisses de qualité remontent à la surface sans révision manuelle.
* **Requêtes et tableaux de bord** — SQL ClickHouse sauvegardé sur vos données, transformé en tableaux de bord partagés à portée organisationnelle.
* **Alertes et incidents** — règles de seuil qui vous notifient (email, Slack, webhook, dans le tableau de bord), avec un workflow de triage des incidents.
* **CLI et assistant IA** — un client terminal (`agenteye`) et un assistant intégré au tableau de bord pour poser des questions en langage naturel.

Vous faites tourner l'ensemble dans votre propre infrastructure, sous forme d'une stack Docker Compose (ce guide), d'une installation Kubernetes en production, ou d'un pod unique co-localisé. La suite de ce guide configure la stack Compose de bout en bout.

***

## Étape 1 : S'authentifier

Tous les artefacts AgentEye sont distribués depuis l'organisation GitHub `agenteye-enterprise`. En tant que développeur entreprise, vous pouvez générer votre propre PAT GitHub. Suivez [enterprise-docs/github-token.md](/fr/agenteye/github-token) pour les étapes exactes et les permissions requises.

```bash theme={null}
export AGENTEYE_TOKEN=<your-github-pat>

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

***

## Étape 2 : Déployer le serveur et le tableau de bord

Le serveur reçoit les événements des collecteurs et les rend interrogeables ; le tableau de bord est l'endroit où vous les explorez. Les événements ingérés et les analyses résident dans ClickHouse (le store d'analyse requis), tandis que Postgres conserve l'état opérationnel comme les organisations, les utilisateurs, les clés API, les tableaux de bord et les requêtes sauvegardées.

**Télécharger le fichier compose publié :**

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

**Définir vos secrets :**

Créez un fichier `.env` pour que le déploiement ne tourne pas avec les identifiants `admin` par défaut. Définissez au minimum `ADMIN_KEY` et `POSTGRES_PASSWORD` :

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

**Démarrer la stack :**

```bash theme={null}
docker compose up -d
```

Cela lance la stack complète, incluant le store d'analyse ClickHouse requis et un cache Redis optionnel, aux côtés du serveur et du tableau de bord. ClickHouse doit être opérationnel pour que le serveur démarre.

Le serveur écoute désormais sur `http://localhost:8080` et le tableau de bord sur `http://localhost:3000`.

Pour les déploiements en production (Postgres personnalisé, TLS, reverse proxy), consultez [enterprise-docs/deployment.md](/fr/agenteye/deployment).

***

## Étape 3 : Créer une clé API pour le collecteur

Chaque collecteur s'authentifie avec une clé API à portée limitée. Utilisez l'`ADMIN_KEY` défini à l'étape 2 pour en créer une :

```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"]}'
```

Vous fournissez vous-même la valeur de `key` ; utilisez-la dans la configuration du collecteur à l'étape 4. Consultez [enterprise-docs/api-keys.md](/fr/agenteye/api-keys) pour la gestion complète des clés.

***

## Étape 4 : Installer le collecteur

Sur chaque machine qui exécute vos agents IA, installez le démon collecteur.

**Télécharger le binaire (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
```

> Ceci télécharge le build **Linux x86\_64**. Pour macOS (Apple Silicon ou Intel), Linux arm64, ou la configuration Docker / systemd / launchd, consultez [collector-installation.md](/fr/agenteye/collector-installation), qui liste le téléchargement pour chaque plateforme — la commande ci-dessus installe un binaire Linux qui ne fonctionnera pas ailleurs.

**Configurer :**

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

**Démarrer le démon :**

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

Vérifiez la connectivité avec un flush ponctuel (se termine après avoir traité tous les événements en attente) :

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

Pour la configuration Docker, systemd et launchd, consultez [enterprise-docs/collector-installation.md](/fr/agenteye/collector-installation).

***

## Étape 5 : Installer le SDK Python

Sur chaque machine où vous souhaitez instrumenter du code d'agent, installez le wheel depuis GitHub Releases.

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

***

## Étape 6 : Instrumenter votre agent

Ajoutez des événements à votre code d'agent. Au minimum, émettez `agent_start` et `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",
)
```

Les événements sont mis en mémoire tampon et transmis vers `$AGENTEYE_HOME/events/` (ou `~/.agenteye/events/` si `AGENTEYE_HOME` n'est pas défini) toutes les 500 ms. Le collecteur les récupère automatiquement.

Consultez [enterprise-docs/python-sdk.md](/fr/agenteye/python-sdk) pour l'API complète des événements.

***

## Étape 7 : Visualiser les événements dans le tableau de bord

Ouvrez `http://your-dashboard-host:3000` et connectez-vous. AgentEye vous envoie par email un code à usage unique (ou un lien magique en un clic), donc aucun mot de passe à gérer.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="L'écran de connexion AgentEye, qui envoie un code à usage unique à votre adresse email" width="2880" height="1800" data-path="agenteye/images/login.png" />

Une fois connecté, la page **Events** affiche un flux en direct de tous les événements ingérés. Filtrez par `session_id` ou `agent_id` pour explorer une exécution spécifique.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="Le flux d'événements en direct, coloré par type d'événement et filtrable par environnement, agent et session" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

La page **Sessions** regroupe ces événements en une ligne par exécution. AgentEye évalue automatiquement les sessions terminées, de sorte que chaque exécution est notée et les régressions de qualité remontent à la surface sans révision manuelle ; le dernier score d'évaluation apparaît sur chaque ligne en un coup d'œil :

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="La liste des sessions, une ligne par exécution, avec des indicateurs de statut et des badges de score d'évaluation" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

Pour configurer la façon dont les sessions sont notées, consultez [enterprise-docs/evaluation-suite.md](/fr/agenteye/evaluation-suite).

Cliquez sur une session pour ouvrir son **graphe d'exécution**, une vue de style git montrant comment les agents, les outils, les hooks et les appels de modèles se sont déroulés dans le temps, avec les sous-agents parallèles sur leurs propres voies et un récapitulatif par exécution dans le panneau droit :

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="Le graphe d'exécution de style git d'une session à côté de sa chronologie d'événements, avec le panneau de répartition outil/modèle/hook" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

## Étape 8 : Explorer, visualiser et alerter

Avec les événements qui transitent, les pages **analyser** transforment l'activité brute en réponses, pour mesurer le comportement des agents, partager les résultats avec l'équipe et être notifié dès qu'une régression survient. Les pages de tableau de bord sont à portée organisationnelle, donc les URLs visibles dans la barre d'adresse sont préfixées par votre slug d'organisation (`/<org>/…`).

* **Requêtes** (`/<org>/queries`) : commencez par une bibliothèque de requêtes sauvegardées et réutilisables sur vos événements et évaluations (préréglages intégrés et les vôtres)…

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="La bibliothèque de requêtes sauvegardées : une grille de requêtes réutilisables, à la fois des préréglages intégrés et des requêtes personnalisées" width="2880" height="1800" data-path="agenteye/images/queries.png" />

…puis ouvrez-en une dans le compositeur SQL pour l'ajuster et l'exécuter avec des résultats en direct :

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="Le compositeur de requêtes SQL exécutant une requête sauvegardée, avec une barre latérale de schéma et une grille de résultats en direct" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

* **Tableaux de bord** (`/<org>/dashboards`) : épinglez des requêtes sous forme de tuiles ligne, barre, aire ou camembert dans des tableaux de bord partagés à l'échelle de l'organisation.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="Un tableau de bord construit à partir de requêtes sauvegardées : une ligne d'événements par heure, un graphique à barres d'erreurs par type, un graphique en aire de latence et des tokens par modèle" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **Alertes** (`/<org>/alerts`) : transformez n'importe quel seuil en règle de notification par email, Slack, webhook ou dans le tableau de bord. Consultez [enterprise-docs/alerts.md](/fr/agenteye/alerts).

***

## Prochaines étapes

* [Déploiement](/fr/agenteye/deployment) : renforcer pour la production
* [Clés API](/fr/agenteye/api-keys) : gérer les accès
* [Dépannage](/fr/agenteye/troubleshooting) : diagnostiquer les problèmes