AgentEye ile Başlayın

Bu kılavuz, tüm AgentEye kurulumunda size yol gösterir: sunucuyu ve panoyu dağıtma, collector’ı bir agent makinesine yükleme ve Python agent kodunuzu enstrümentasyon yapma.

AgentEye Nedir?

AgentEye, AI ajanları için kendi barındırılan gözlemlenebilirlik ve değerlendirme platformudur. Ajanlarınızın ne yaptığını — bir çalıştırmanın her adımını — kaydeder ve tamamlanan her çalıştırmanın kalitesini otomatik olarak puanlandırır, böylece ajanlarınızın üretimde nasıl davrandığını görebilir ve kullanıcılarınız bunu fark etmeden önce gerileme yakalayabilirsiniz. Veri tek yönde akar: agent kodunuz olaylar gönderir Python SDK aracılığıyla → hafif bir collector daemon bunları toplar ve sunucuya gönderir → olaylar ve analitiğer ClickHouse’da saklanır (kuruluşlar, kullanıcılar, API anahtarları, panolar ve kaydedilmiş sorgular gibi operasyonel durum Postgres’te yaşar) → panosunda her şeyi keşfedersiniz. Neler elde edersiniz:

Olaylar — her agent çalıştırmasının ham, adım adım izi (araç çağrıları, model çağrıları, hook’lar, hatalar).
Oturumlar — bu olaylar çalıştırma başına bir satıra toplandı, her biri otomatik olarak değerlendirildi ve puanlandırıldı.
Değerlendirmeler — kendi değerlendirici hizmetleriniz tarafından üretilen kalite puanları, böylece kalite düşüşleri manuel inceleme olmadan ortaya çıkar.
Sorgular ve panolar — verileriniz üzerinde kaydedilmiş ClickHouse SQL, paylaşılan, kuruluş kapsamlı panolara çizelgeler halinde dönüştürülür.
Uyarılar ve olaylar — sizi sayfalayan eşik kuralları (e-posta, Slack, webhook, panonun içinde) ve bunları sınıflandırmak için bir olay iş akışı.
CLI ve AI asistanı — terminal istemcisi (agenteye) ve sorulara düz İngilizce ile yanıt vermek için panonun içinde bir asistan.

Tüm bunları kendi altyapınızda çalıştırırsınız, tek bir Docker Compose yığını (bu kılavuz), production Kubernetes kurulumu veya tek bir ortak bulundurulan pod olarak. Bu kılavuzun geri kalanı Compose yığınını sondan sona kurar.

Adım 1: Kimlik Doğrulama

Tüm AgentEye yapıları agenteye-enterprise GitHub kuruluşundan dağıtılır. Bir enterprise geliştirici olarak kendi GitHub PAT’inizi oluşturabilirsiniz. Tam adımlar ve gerekli izinler için enterprise-docs/github-token.md adresini izleyin.

export AGENTEYE_TOKEN=<your-github-pat>

# Docker'ı GHCR'a karşı kimlik doğrulama
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

Adım 2: Sunucuyu ve Panoyu Dağıtın

Sunucu, collectors’lardan olaylar alır ve bunları sorgulanabilir hale getirir; pano onları keşfettiğiniz yerdir. Alınan olaylar ve analitiğer ClickHouse’da yaşar (gerekli analitiğer deposu), Postgres ise kuruluşlar, kullanıcılar, API anahtarları, panolar ve kaydedilmiş sorgular gibi operasyonel durumu tutar. Yayınlanan compose dosyasını indirin:

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

Gizli anahtarlarınızı ayarlayın: Dağıtım varsayılan admin kimlik bilgileriyle çalışmayacak şekilde bir .env dosyası oluşturun. En azından ADMIN_KEY ve POSTGRES_PASSWORD ayarlayın:

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

Yığını başlatın:

docker compose up -d

Bu, gerekli ClickHouse analitiğer deposu ve isteğe bağlı bir Redis önbelleğinin yanı sıra sunucu ve panoyu içeren tam yığını başlatır. ClickHouse sunucunun başlaması için sağlıklı olması gerekir. Sunucu artık http://localhost:8080 adresinde dinliyor ve pano http://localhost:3000 adresinde. Production dağıtımları için (özel Postgres, TLS, ters proxy), enterprise-docs/deployment.md adresine bakın.

Adım 3: Collector için bir API Anahtarı Oluşturun

Her collector, kapsamlı bir API anahtarı ile kimlik doğrulama yapar. Adım 2’de ayarladığınız ADMIN_KEY öğesini kullanarak bir tane oluşturun:

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 değerini kendiniz sağlarsınız; Adım 4’teki collector yapılandırmasında kullanın. Tam anahtar yönetimi için enterprise-docs/api-keys.md adresine bakın.

Adım 4: Collector’ı Yükleyin

AI ajanlarınızı çalıştıran her makineye collector daemon’ı yükleyin. İkili dosyayı indirin (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

Bu, Linux x86_64 derlemesini indirir. macOS (Apple Silicon veya Intel), Linux arm64 veya Docker / systemd / launchd kurulumu için, her platform için indirme sağlayan collector-installation.md adresine bakın — yukarıdaki komut başka yerlerde çalışmayacak bir Linux ikili dosyasını yükler.

Yapılandırın:

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

Daemon’ı başlatın:

agenteye-collector start

Bağlantıyı tek seferlik flush ile doğrulayın (beklemede olan olayları boşalttıktan sonra çıkar):

agenteye-collector flush

Docker, systemd ve launchd kurulumu için enterprise-docs/collector-installation.md adresine bakın.

Adım 5: Python SDK’yı Yükleyin

Agent kodunu enstrümentasyon yapmak istediğiniz her makinede, GitHub Releases’tan wheel’i yükleyin.

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

Adım 6: Ajanınızı Enstrümente Edin

Agent kodunuza olaylar ekleyin. En azından agent_start ve agent_end gönderin:

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",
)

Olaylar arabelleğe alınır ve $AGENTEYE_HOME/events/ (AGENTEYE_HOME ayarlanmadıysa ~/.agenteye/events/) öğesine her 500 ms’de boşaltılır. Collector bunları otomatik olarak alır. Tam olay API’si için enterprise-docs/python-sdk.md adresine bakın.

Adım 7: Panodan Olayları Görüntüleyin

http://your-dashboard-host:3000 adresini açın ve oturum açın. AgentEye size tek kullanımlı bir kod gönderir (veya tek tıklamayla sihirli bir bağlantı), bu nedenle yönetilecek şifre yoktur.

AgentEye oturum açma ekranı, tek kullanımlı kod gönderen

İçeri girdikten sonra, Olaylar sayfası tüm alınan olayların canlı izini gösterir. Belirli bir çalıştırmaya inmek için session_id veya agent_id ile filtreleyin.

Canlı Olaylar akışı, olay türüne göre renk kodlu ve ortam, ajan ve oturuma göre filtrelenebilir

Oturumlar sayfası bu olayları çalıştırma başına bir satıra toplar. AgentEye tamamlanan oturumları otomatik olarak değerlendirir, bu nedenle her çalıştırma puanlandırılır ve kalite gerillemeleri manuel inceleme olmadan ortaya çıkar; en son değerlendirme puanı her satırda bir bakışta görünür:

Oturumlar listesi, çalıştırma başına bir satır, durum rozeti ve değerlendirme puanı rozetleriyle

Oturumların nasıl puanlandırıldığını yapılandırmak için enterprise-docs/evaluation-suite.md adresine bakın. Herhangi bir oturuma tıklayarak yürütme grafiğini açın, ajanların, araçların, hook’ların ve model çağrılarının zaman içinde nasıl ortaya çıktığının git tarzı görünümü, kendi şeritlerinde paralel alt ajanlar ve sağ ray’de çalıştırma başına döküm:

Bir oturumun git tarzı yürütme grafiği, olay zaman çizelgesi yanında, araç/model/hook döküm paneli ile

Adım 8: Keşfetme, grafiklendirme ve uyarı verme

Olaylar aktığında, analiz sayfaları ham etkinliği cevaplara dönüştürür, böylece ajan davranışını ölçebilir, bulguları ekip genelinde paylaşabilir ve bir şey geriledikleri anda sayfaya alınabilirsiniz. Pano sayfaları kuruluş kapsamlıdır, bu nedenle adres çubuğunda gördüğünüz URL’ler kuruluş slug’ınız (/<org>/…) ile başına getirilir.

Sorgular (/<org>/queries): olaylarınız ve değerlendirmeleriniz üzerindeki kaydedilmiş, yeniden kullanılabilir sorgulardan oluşan bir kitaplıktan başlayın (yerleşik ön ayarlar artı kendi sorgularınız)…

Kaydedilmiş sorgular kitaplığı: yeniden kullanılabilir sorgulardan oluşan bir ızgara, hem yerleşik ön ayarlar hem de özel olanlar

…ardından bunu SQL bestecisinde açın, değiştirin ve canlı sonuçlarla çalıştırın:

agenteye-collector start

Panolar (/<org>/dashboards): sorguları satır, çubuk, alan veya pasta kutucuklara sabitle paylaşılan, kuruluş genelindeki panolara.

Kaydedilmiş sorgulardan oluşturulan bir pano: saatlik olaylar satırı, tür başına hatalar çubuğu, gecikme alan grafiği ve modele göre tokenler

Uyarılar (/<org>/alerts): herhangi bir eşiği e-posta, Slack, webhook veya panonun içi ile bildirim yapan sayfalama kuralına yükseltin. enterprise-docs/alerts.md adresine bakın.

Sonraki Adımlar

Dağıtım: production için sertleştirin
API Anahtarları: erişim yönetimi
Sorun Giderme: sorunları tanıla

​AgentEye Nedir?

​Adım 1: Kimlik Doğrulama

​Adım 2: Sunucuyu ve Panoyu Dağıtın

​Adım 3: Collector için bir API Anahtarı Oluşturun

​Adım 4: Collector’ı Yükleyin

​Adım 5: Python SDK’yı Yükleyin

​Adım 6: Ajanınızı Enstrümente Edin

​Adım 7: Panodan Olayları Görüntüleyin

​Adım 8: Keşfetme, grafiklendirme ve uyarı verme

​Sonraki Adımlar