Начало работы с AgentEye

Это руководство проведёт вас через полную настройку AgentEye: развёртывание сервера и панели управления, установка сборщика на машину агента и инструментирование кода вашего агента на Python.

Что такое AgentEye?

AgentEye — это самостоятельно размещаемая платформа наблюдаемости и оценки для AI-агентов. Она записывает, что делают ваши агенты — каждый шаг выполнения — и автоматически оценивает качество каждого завершённого запуска, чтобы вы могли видеть, как ваши агенты ведут себя в production, и выявлять регрессии до того, как это заметят ваши пользователи. Поток данных идёт в одном направлении: код вашего агента генерирует события через Python SDK → лёгкий демон сборщика группирует их и отправляет на сервер → события и аналитика сохраняются в ClickHouse (операционное состояние, такое как организации, пользователи, API-ключи, панели управления и сохранённые запросы, находится в Postgres) → вы исследуете всё это в панели управления. Что вы получаете:

События — необработанный, пошаговый журнал каждого запуска агента (вызовы инструментов, вызовы модели, хуки, ошибки).
Сеансы — эти события свёрнуты в одну строку на запуск, каждый автоматически оценивается и получает оценку.
Оценки — оценки качества, полученные от ваших собственных служб оценки, чтобы снижение качества проявлялось без ручной проверки.
Запросы и панели управления — сохранённый SQL ClickHouse по вашим данным, визуализированный в общих панелях управления с охватом организации.
Оповещения и инциденты — правила по пороговым значениям, которые оповещают вас (по электронной почте, Slack, webhook, на панели управления) и рабочий процесс инцидентов для их классификации.
CLI и ассистент AI — клиент терминала (agenteye) и ассистент на панели управления для задания вопросов на простом английском языке.

Вы запускаете всё это в своей собственной инфраструктуре как единый стек Docker Compose (это руководство), production-установку Kubernetes или отдельный совмещённый pod. Остальная часть этого руководства настраивает стек Compose с начала до конца.

Шаг 1: Аутентификация

Все артефакты AgentEye распространяются из организации GitHub agenteye-enterprise. Как корпоративный разработчик, вы можете создать свой собственный GitHub PAT. Следуйте enterprise-docs/github-token.md для точных шагов и необходимых разрешений.

export AGENTEYE_TOKEN=<your-github-pat>

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

Шаг 2: Развёртывание сервера и панели управления

Сервер получает события от сборщиков и делает их доступными для запросов; панель управления — это место, где вы их исследуете. Принятые события и аналитика находятся в ClickHouse (необходимое хранилище аналитики), а Postgres содержит операционное состояние, такое как организации, пользователи, API-ключи, панели управления и сохранённые запросы. Загрузите опубликованный файл compose:

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

Установите ваши секреты: Создайте файл .env, чтобы развёртывание не использовало учётные данные admin по умолчанию. Как минимум установите ADMIN_KEY и POSTGRES_PASSWORD:

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

Запустите стек:

docker compose up -d

Это запускает полный стек, включая необходимое хранилище аналитики ClickHouse и опциональный кэш Redis, вместе с сервером и панелью управления. ClickHouse должен быть здоровым, чтобы сервер запустился. Сервер теперь слушает на http://localhost:8080, а панель управления на http://localhost:3000. Для production-развёртываний (пользовательский Postgres, TLS, обратный прокси) см. enterprise-docs/deployment.md.

Шаг 3: Создание API-ключа для сборщика

Каждый сборщик аутентифицируется с помощью защищённого API-ключа. Используйте ADMIN_KEY, который вы установили на шаге 2, чтобы создать его:

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

Вы самостоятельно предоставляете значение key; используйте его в конфигурации сборщика на шаге 4. См. enterprise-docs/api-keys.md для полного управления ключами.

Шаг 4: Установка сборщика

На каждой машине, которая запускает ваши AI-агенты, установите демон сборщика. Загрузите двоичный файл (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

Это загружает сборку Linux x86_64. Для macOS (Apple Silicon или Intel), Linux arm64 или Docker / systemd / launchd установки см. collector-installation.md, которая список загрузки для каждой платформы — команда выше устанавливает двоичный файл Linux, который не будет работать нигде в другом месте.

Настройка:

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

Запустите демон:

agenteye-collector start

Проверьте подключение одноразовой очисткой (выходит после слива всех ожидающих событий):

agenteye-collector flush

Для Docker, systemd и launchd установки см. enterprise-docs/collector-installation.md.

Шаг 5: Установка Python SDK

На каждой машине, где вы хотите инструментировать код агента, установите wheel из 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

Шаг 6: Инструментирование вашего агента

Добавьте события в код вашего агента. Как минимум выпускайте agent_start и 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",
)

События буферизируются и сбрасываются в $AGENTEYE_HOME/events/ (или ~/.agenteye/events/, если AGENTEYE_HOME не установлена) каждые 500 мс. Сборщик автоматически их подхватывает. См. enterprise-docs/python-sdk.md для полного API событий.

Шаг 7: Просмотр событий на панели управления

Откройте http://your-dashboard-host:3000 и войдите. AgentEye отправляет вам одноразовый код по электронной почте (или ссылку one-click magic), поэтому нет необходимости управлять паролем.

Экран входа AgentEye, который отправляет одноразовый код на вашу электронную почту

После входа страница Events показывает живой журнал всех принятых событий. Фильтруйте по session_id или agent_id для углубления в конкретный запуск.

Живой поток Events, цветовой код по типу события и фильтруется по окружению, агенту и сеансу

Страница Sessions сворачивает эти события в одну строку на запуск. AgentEye автоматически оценивает завершённые сеансы, поэтому каждый запуск получает оценку и регрессии качества проявляются без ручной проверки; последний балл оценки появляется на каждой строке с первого взгляда:

Список сеансов, одна строка на запуск, с пилюлями статуса и значками оценки

Для настройки того, как оцениваются сеансы, см. enterprise-docs/evaluation-suite.md. Нажмите на любой сеанс, чтобы открыть его граф выполнения, представление в стиле git того, как агенты, инструменты, хуки и вызовы моделей развёртывались с течением времени, с параллельными подагентами на своих дорожках и разбивкой по запускам в правой колонке:

Граф выполнения сеанса в стиле git рядом с его временной шкалой событий, с панелью разбивки инструмент/модель/хук

Шаг 8: Исследуйте, отображайте в диаграммах и предупреждайте

С потоком событий, страницы analyze превращают необработанную активность в ответы, поэтому вы можете измерять поведение агента, делиться находками с командой и получать оповещение в момент, когда что-то регрессирует. Страницы панели управления имеют охват организации, поэтому URL-адреса, которые вы видите в адресной строке, имеют префикс с вашим слагом организации (/<org>/…).

Queries (/<org>/queries): начните с библиотеки сохранённых, многократно используемых запросов по вашим событиям и оценкам (встроенные предустановки плюс ваши собственные)…

Библиотека сохранённых запросов: сетка многократно используемых запросов, как встроенных предустановок, так и пользовательских

…затем откройте один в SQL-компоновщике, чтобы настроить его и запустить с живыми результатами:

Композитор SQL-запросов запускает сохранённый запрос с боковой панелью схемы и живой сеткой результатов

Dashboards (/<org>/dashboards): закрепите запросы как линейные, столбчатые, площадные или круговые плитки в общие панели управления на уровне организации.

Панель управления, построенная из сохранённых запросов: линия событий в час, столбец ошибок по типу, диаграмма площади задержки и токены по модели

Alerts (/<org>/alerts): превратите любой порог в правило оповещения, которое уведомляет по электронной почте, Slack, webhook или на панели управления. См. enterprise-docs/alerts.md.

Следующие шаги

Развёртывание: укрепите для production
API-ключи: управляйте доступом
Устранение проблем: диагностируйте проблемы

​Что такое AgentEye?

​Шаг 1: Аутентификация

​Шаг 2: Развёртывание сервера и панели управления

​Шаг 3: Создание API-ключа для сборщика

​Шаг 4: Установка сборщика

​Шаг 5: Установка Python SDK

​Шаг 6: Инструментирование вашего агента

​Шаг 7: Просмотр событий на панели управления

​Шаг 8: Исследуйте, отображайте в диаграммах и предупреждайте

​Следующие шаги