Primeiros Passos com o AgentEye

Este guia apresenta uma configuração completa do AgentEye: implantando o servidor e o dashboard, instalando o coletor em uma máquina de agente e instrumentando o código do seu agente Python.

O que é o AgentEye?

O AgentEye é uma plataforma de observabilidade e avaliação self-hosted para agentes de IA. Ele registra o que seus agentes fazem — cada etapa de uma execução — e pontua automaticamente a qualidade de cada execução concluída, para que você possa ver como seus agentes se comportam em produção e detectar regressões antes que seus usuários percebam. Os dados fluem em uma única direção: seu código de agente emite eventos por meio do SDK Python → um daemon coletor leve agrupa e os envia ao servidor → eventos e análises são armazenados no ClickHouse (o estado operacional, como organizações, usuários, chaves de API, dashboards e consultas salvas, fica no Postgres) → você explora tudo no dashboard. O que você obtém:

Eventos — o rastro bruto, por etapa, de cada execução de agente (chamadas de ferramenta, chamadas de modelo, hooks, erros).
Sessões — esses eventos consolidados em uma linha por execução, cada uma avaliada e pontuada automaticamente.
Avaliações — pontuações de qualidade produzidas pelos seus próprios serviços de avaliação, para que quedas de qualidade apareçam sem revisão manual.
Consultas e dashboards — SQL ClickHouse salvo sobre seus dados, visualizado em dashboards compartilhados com escopo de organização.
Alertas e incidentes — regras de limiar que notificam você (e-mail, Slack, webhook, no dashboard) além de um fluxo de trabalho de incidentes para triagem.
CLI e assistente de IA — um cliente de terminal (agenteye) e um assistente no dashboard para fazer perguntas em linguagem natural.

Você executa tudo isso na sua própria infraestrutura, como uma stack Docker Compose (este guia), uma instalação Kubernetes para produção ou um único pod colocado. O restante deste guia configura a stack Compose do início ao fim.

Passo 1: Autenticar

Todos os artefatos do AgentEye são distribuídos pela organização agenteye-enterprise no GitHub. Como desenvolvedor enterprise, você pode gerar seu próprio GitHub PAT. Siga enterprise-docs/github-token.md para os passos exatos e as permissões necessárias.

export AGENTEYE_TOKEN=<your-github-pat>

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

Passo 2: Implantar o Servidor e o Dashboard

O servidor recebe eventos dos coletores e os torna consultáveis; o dashboard é onde você os explora. Eventos ingeridos e análises ficam no ClickHouse (o armazenamento de análises obrigatório), enquanto o Postgres mantém o estado operacional, como organizações, usuários, chaves de API, dashboards e consultas salvas. Baixe o arquivo compose publicado:

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

Configure seus segredos: Crie um arquivo .env para que a implantação não use a credencial padrão admin. No mínimo, defina ADMIN_KEY e POSTGRES_PASSWORD:

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

Inicie a stack:

docker compose up -d

Isso sobe a stack completa, incluindo o armazenamento de análises ClickHouse obrigatório e um cache Redis opcional, junto com o servidor e o dashboard. O ClickHouse precisa estar saudável para o servidor iniciar. O servidor agora está escutando em http://localhost:8080 e o dashboard em http://localhost:3000. Para implantações em produção (Postgres personalizado, TLS, proxy reverso), veja enterprise-docs/deployment.md.

Passo 3: Criar uma Chave de API para o Coletor

Cada coletor se autentica com uma chave de API com escopo. Use o ADMIN_KEY definido no Passo 2 para criar uma:

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

Você fornece o valor de key você mesmo; use-o na configuração do coletor no Passo 4. Veja enterprise-docs/api-keys.md para o gerenciamento completo de chaves.

Passo 4: Instalar o Coletor

Em cada máquina que executa seus agentes de IA, instale o daemon coletor. Baixe o binário (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

Isso baixa o build para Linux x86_64. Para macOS (Apple Silicon ou Intel), Linux arm64, ou configuração via Docker / systemd / launchd, veja collector-installation.md, que lista o download para cada plataforma — o comando acima instala um binário Linux que não funcionará em outros sistemas.

Configure:

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

Inicie o daemon:

agenteye-collector start

Verifique a conectividade com um flush único (encerra após drenar quaisquer eventos pendentes):

agenteye-collector flush

Para configuração com Docker, systemd e launchd, veja enterprise-docs/collector-installation.md.

Passo 5: Instalar o SDK Python

Em cada máquina onde você deseja instrumentar o código do agente, instale o wheel a partir do 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

Passo 6: Instrumentar Seu Agente

Adicione eventos ao código do seu agente. No mínimo, emita agent_start e 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",
)

Os eventos são armazenados em buffer e enviados para $AGENTEYE_HOME/events/ (ou ~/.agenteye/events/ se AGENTEYE_HOME não estiver definido) a cada 500 ms. O coletor os captura automaticamente. Veja enterprise-docs/python-sdk.md para a API completa de eventos.

Passo 7: Visualizar Eventos no Dashboard

Abra http://your-dashboard-host:3000 e faça login. O AgentEye envia um código de uso único por e-mail (ou um link mágico de um clique), então não há senha para gerenciar.

A tela de login do AgentEye, que envia um código de uso único para o seu e-mail

Após entrar, a página Events exibe um rastro em tempo real de todos os eventos ingeridos. Filtre por session_id ou agent_id para detalhar uma execução específica.

O stream de eventos ao vivo, com código de cores por tipo de evento e filtrável por ambiente, agente e sessão

A página Sessions consolida esses eventos em uma linha por execução. O AgentEye avalia automaticamente as sessões concluídas, portanto cada execução é pontuada e regressões de qualidade aparecem sem revisão manual; a pontuação de avaliação mais recente é exibida em cada linha de relance:

A lista de sessões, uma linha por execução, com indicadores de status e emblemas de pontuação de avaliação

Para configurar como as sessões são pontuadas, veja enterprise-docs/evaluation-suite.md. Clique em qualquer sessão para abrir seu gráfico de execução, uma visualização no estilo git de como agentes, ferramentas, hooks e chamadas de modelo se desenrolaram ao longo do tempo, com sub-agentes paralelos em suas próprias faixas e um detalhamento por execução no painel lateral direito:

O gráfico de execução no estilo git de uma sessão ao lado da linha do tempo de eventos, com o painel de detalhamento de ferramenta/modelo/hook

Passo 8: Explorar, visualizar e alertar

Com os eventos fluindo, as páginas de análise transformam atividade bruta em respostas, para que você possa medir o comportamento do agente, compartilhar descobertas com a equipe e ser notificado no momento em que algo regredir. As páginas do dashboard têm escopo de organização, portanto as URLs que você vê na barra de endereços são prefixadas com o slug da sua organização (/<org>/…).

Queries (/<org>/queries): comece a partir de uma biblioteca de consultas salvas e reutilizáveis sobre seus eventos e avaliações (predefinições integradas mais as suas próprias)…

A biblioteca de consultas salvas: uma grade de consultas reutilizáveis, tanto predefinições integradas quanto personalizadas

…depois abra uma no compositor SQL para ajustá-la e executá-la com resultados em tempo real:

O compositor de consultas SQL executando uma consulta salva, com uma barra lateral de esquema e uma grade de resultados em tempo real

Dashboards (/<org>/dashboards): fixe consultas como blocos de linha, barra, área ou pizza em dashboards compartilhados em toda a organização.

Um dashboard construído a partir de consultas salvas: uma linha de eventos por hora, uma barra de erros por tipo, um gráfico de área de latência e tokens por modelo

Alerts (/<org>/alerts): promova qualquer limite a uma regra de notificação que avisa por e-mail, Slack, webhook ou no dashboard. Veja enterprise-docs/alerts.md.

Próximos Passos

Implantação: fortaleça para produção
Chaves de API: gerencie o acesso
Solução de Problemas: diagnostique problemas

​O que é o AgentEye?

​Passo 1: Autenticar

​Passo 2: Implantar o Servidor e o Dashboard

​Passo 3: Criar uma Chave de API para o Coletor

​Passo 4: Instalar o Coletor

​Passo 5: Instalar o SDK Python

​Passo 6: Instrumentar Seu Agente

​Passo 7: Visualizar Eventos no Dashboard

​Passo 8: Explorar, visualizar e alertar

​Próximos Passos