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

# Primeiros Passos com o AgentEye

> Documentação de introdução ao 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](/pt-br/agenteye/github-token) para os passos exatos e as permissões necessárias.

```bash theme={null}
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:**

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

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

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

**Inicie a stack:**

```bash theme={null}
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](/pt-br/agenteye/deployment).

***

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

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

Você fornece o valor de `key` você mesmo; use-o na configuração do coletor no Passo 4. Veja [enterprise-docs/api-keys.md](/pt-br/agenteye/api-keys) 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):**

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

> 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](/pt-br/agenteye/collector-installation), que lista o download para cada plataforma — o comando acima instala um binário Linux que não funcionará em outros sistemas.

**Configure:**

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

**Inicie o daemon:**

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

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

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

Para configuração com Docker, systemd e launchd, veja [enterprise-docs/collector-installation.md](/pt-br/agenteye/collector-installation).

***

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

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

***

## Passo 6: Instrumentar Seu Agente

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

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](/pt-br/agenteye/python-sdk) 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.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="A tela de login do AgentEye, que envia um código de uso único para o seu e-mail" width="2880" height="1800" data-path="agenteye/images/login.png" />

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.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="O stream de eventos ao vivo, com código de cores por tipo de evento e filtrável por ambiente, agente e sessão" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

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:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="A lista de sessões, uma linha por execução, com indicadores de status e emblemas de pontuação de avaliação" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

Para configurar como as sessões são pontuadas, veja [enterprise-docs/evaluation-suite.md](/pt-br/agenteye/evaluation-suite).

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:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="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" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="A biblioteca de consultas salvas: uma grade de consultas reutilizáveis, tanto predefinições integradas quanto personalizadas" width="2880" height="1800" data-path="agenteye/images/queries.png" />

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="O compositor de consultas SQL executando uma consulta salva, com uma barra lateral de esquema e uma grade de resultados em tempo real" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="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" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **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](/pt-br/agenteye/alerts).

***

## Próximos Passos

* [Implantação](/pt-br/agenteye/deployment): fortaleça para produção
* [Chaves de API](/pt-br/agenteye/api-keys): gerencie o acesso
* [Solução de Problemas](/pt-br/agenteye/troubleshooting): diagnostique problemas