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

# Receitas de CLI para agentes

> Documentação de receitas de CLI do AgentEye para agentes.

Obtenha dados de sessões, eventos e avaliações (e acione reavaliações) diretamente de um script ou agente de codificação, com JSON limpo no stdout que pode ser redirecionado para o `jq`. Essas receitas transformam os dados de observabilidade do AgentEye em algo que um usuário de terminal ou um agente de codificação de IA (Claude Code, Cursor) pode consultar e automatizar, sem precisar clicar pelo dashboard.

Os padrões abaixo estão prontos para copiar e colar com a CLI do AgentEye (`agenteye`). Para instalação, autenticação e a lista completa de opções, consulte [CLI](/pt-br/agenteye/cli); execute `agenteye -h` ou `agenteye <command> -h` para obter a ajuda integrada.

## Regras de ouro

1. **As opções globais vêm *antes* do comando.** `agenteye --json sessions` está correto; `agenteye sessions --json` não está. As opções globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`.
2. **Use `--json` sempre que for processar a saída.** Os dados vão para o **stdout** como JSON; status e erros para humanos vão para o **stderr**, mantendo o stdout limpo para redirecionar ao `jq`.
3. **Tome decisões com base no código de saída**, não no texto do stderr: `0` ok · `2` argumentos inválidos · `3` não consegue alcançar o dashboard · `4` não autenticado ou sessão expirada · `5` permissão ausente.
4. **Descubra com `-h`.** Cada comando documenta seus filtros, formatos de valor e estrutura JSON.

## Configuração inicial

```bash theme={null}
export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # para não repetir --base-url
agenteye login --email you@example.com                       # cole o código enviado por e-mail; válido por ~24h
```

## Confirme a autenticação antes de começar

`whoami` nunca retorna erro quando a sessão está ausente ou expirada; ele reporta `logged_in:false`, permitindo que um agente verifique o estado de autenticação com segurança. (Ainda pode sair com código não zero se nenhuma URL base estiver definida ou se o dashboard estiver inacessível.)

```bash theme={null}
if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
  echo "Not authenticated. Run: agenteye login" >&2; exit 1
fi
```

## Encontre sessões com falhas ou pontuações baixas

```bash theme={null}
# sessões nas últimas 24h cujas avaliações retornaram erro
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# avaliações com pontuação <= 0.5 em helpfulness, para um agente específico
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'
```

O filtro por pontuação fica em **`evals`**, não em `sessions`. `--score KEY:MIN..MAX` pode ser repetido e é combinado com AND; qualquer um dos limites é opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Você pode passar até 20 filtros de pontuação por requisição; mais do que isso retorna HTTP 400. `sessions` compartilha os filtros `--env`, `--status`, `--agent-id`, `--session-id` e de intervalo de tempo com `evals`, mas não possui `--score`.

## Leia uma sessão completa

Não existe um único comando `session show` — combine o histórico de eventos com a avaliação da sessão:

```bash theme={null}
# a avaliação mais recente da sessão (status + pontuações)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# todos os eventos da execução (aumente --limit para varredura completa)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# apenas as chamadas de ferramenta de uma sessão
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'
```

## Busque tudo (paginação)

Os resultados são retornados do mais recente para o mais antigo e paginados por cursor.

```bash theme={null}
# em uma única chamada: busca até 500 registros em páginas de 200
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# paginação manual: repasse o next_cursor
page=$(agenteye --json events --limit 100)
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
```

## Reduza a saída com --fields

Restrinja as chaves (tanto na tabela quanto no `--json`) para diminuir o que um agente precisa processar.

```bash theme={null}
agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]'
agenteye --json events --session-id run-001 --fields ts,event_type --all
```

Nomes de campos desconhecidos são rejeitados (saída `2`) com a lista de valores válidos — uma forma rápida de descobrir os nomes dos campos.

## Descubra valores de filtro válidos

```bash theme={null}
agenteye --json list envs | jq -r '.values[]'           # valores para --env
agenteye --json list tools | jq -r '.values[]'          # nomes de ferramentas; também agents, models, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # KEY válida para --score KEY:MIN..MAX
```

## Escolha sua organização (multi-tenant)

Se você pertence a mais de uma organização, escolha o tenant ativo no momento do login (ele é salvo):

```bash theme={null}
agenteye login --org acme --email you@corp.com   # define o tenant no mesmo passo do login
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # substitui para um único comando
```

Um login com múltiplas organizações sem `--org` sai com código não zero e exibe as organizações disponíveis para escolha.

## Provisione uma chave de API para o SDK/coletor

```bash theme={null}
# o segredo é exibido UMA ÚNICA VEZ — com --json ele fica no campo .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # rotaciona; use agenteye keys disable ci-bot --yes para revogar
```

## Execute uma query salva ou ad-hoc

```bash theme={null}
agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # uma query salva + um argumento posicional $1
```

## Trate um incidente de forma não interativa

```bash theme={null}
id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id')
agenteye incidents ack "$id"
agenteye incidents assign "$id" --assignee you@corp.com
agenteye incidents resolve "$id" --yes
```

> Mutações ignoram automaticamente o prompt de confirmação quando `--json` está ativo ou quando o stdin não é um TTY, então agentes nunca ficam travados; use `--yes`/`-y` para ignorá-lo explicitamente em outros contextos.

## Tratamento de códigos de saída em um script

```bash theme={null}
out=$(agenteye --json sessions --since 1h) || code=$?
case "${code:-0}" in
  0) echo "$out" | jq '.sessions | length' ;;
  4) echo "Session expired - run 'agenteye login'." >&2 ;;
  5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;;
  3) echo "Dashboard unreachable - check the URL." >&2 ;;
  *) echo "Unexpected error (exit ${code})." >&2 ;;
esac
```

## Estruturas de saída JSON

| Comando                          | JSON no stdout (com `--json`)                                                                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`                         | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` ou `{"logged_in": false}` |
| `orgs list`                      | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}`                                                            |
| `events`                         | `{"events": [...], "next_cursor": <cursor or null>}`                                                                                          |
| `evals`                          | `{"evaluations": [...], "next_cursor": <cursor or null>}`                                                                                     |
| `sessions`                       | `{"sessions": [...], "next_cursor": <cursor or null>}`                                                                                        |
| `errors`                         | `{"errors": [...], "next_cursor": <cursor or null>}`                                                                                          |
| `list <kind>`                    | `{"kind", "values": [...]}`                                                                                                                   |
| `keys list` / `keys create`      | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` exibida uma única vez)                                                  |
| `query run`                      | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`                                                                              |
| `users list` / `settings list`   | `{"users": [...]}` / `{"settings": [...]}`                                                                                                    |
| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}`                                                                                                  |
| create/update/delete (qualquer)  | o objeto do recurso, ou `{"deleted": true, "id"}` para exclusões                                                                              |
| falha (qualquer, com `--json`)   | `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` no stdout                                                             |

* Cada item de **evento** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`.
* Cada item de **avaliação** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`.
* Cada item de **sessão** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`.

O `--fields` de cada comando aceita exatamente os nomes de campos do seu próprio item — o conjunto difere entre `sessions` e `evals`, portanto um nome válido para um pode ser rejeitado pelo outro.