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 pour les étapes exactes et les permissions requises.

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

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 :

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

Démarrer la stack :

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.

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

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

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, qui liste le téléchargement pour chaque plateforme — la commande ci-dessus installe un binaire Linux qui ne fonctionnera pas ailleurs.

Configurer :

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 :

agenteye-collector start

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

agenteye-collector flush

Pour la configuration Docker, systemd et launchd, consultez enterprise-docs/collector-installation.md.

Étape 5 : Installer le SDK Python

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

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 :

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

L'écran de connexion AgentEye, qui envoie un code à usage unique à votre adresse email

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.

Le flux d'événements en direct, coloré par type d'événement et filtrable par environnement, agent et session

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 :

La liste des sessions, une ligne par exécution, avec des indicateurs de statut et des badges de score d'évaluation

Pour configurer la façon dont les sessions sont notées, consultez enterprise-docs/evaluation-suite.md. 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 :

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

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

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

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

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

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.

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

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.

Prochaines étapes

Déploiement : renforcer pour la production
Clés API : gérer les accès
Dépannage : diagnostiquer les problèmes

​Qu’est-ce qu’AgentEye ?

​Étape 1 : S’authentifier

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

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

​Étape 4 : Installer le collecteur

​Étape 5 : Installer le SDK Python

​Étape 6 : Instrumenter votre agent

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

​Étape 8 : Explorer, visualiser et alerter

​Prochaines étapes