failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/pt-br/agenteye/cli.mdx

@@ -0,0 +1,350 @@
+---
+title: "CLI"
+description: "Controle toda a Observabilidade do Failproof AI pelo terminal ou por um script: sem precisar acessar o dashboard."
+---
+
+
+Controle toda a Observabilidade do Failproof AI pelo terminal ou por um script: sem precisar acessar o dashboard. O CLI `agenteye` consulta seus dados (sessões, logs de eventos, avaliações) e administra sua organização (chaves de API, usuários, configurações, alertas, incidentes, consultas salvas), sendo ideal para automatizar verificações, integrar a Observabilidade ao CI ou permitir que um agente de codificação inspecione o ambiente de produção. Todos os comandos suportam o flag `--json`, funcionando igualmente bem para uso interativo no terminal ou para um agente de codificação (Claude Code, Cursor) que executa o comando e processa o resultado.
+
+Com um único binário você pode:
+
+- **Ler seus dados**: `sessions`, `events`, `evals`, `errors` (filtre por tempo, agente, ambiente, pontuação).
+- **Gerenciar sua organização**: `keys`, `users`, `settings`, `alerts`, `incidents`.
+- **Executar análises**: SQL salvo e um executor de consultas ad-hoc (`query`).
+- **Consultar o assistente de IA**: o mesmo analista somente leitura disponível no dashboard (`agent`).
+
+> **Nota:** Este é o CLI `agenteye`, uma ferramenta diferente do daemon coletor (`agenteye-collector`). O CLI se comunica com o seu dashboard; o coletor envia eventos para o servidor.
+
+---
+
+## Início rápido
+
+Do zero ao seu primeiro resultado em quatro linhas. Aponte o CLI para o seu dashboard, faça login, confirme quem você é e, em seguida, busque as execuções das últimas 24 horas:
+
+```bash
+pipx install agenteye
+agenteye --base-url https://agenteye.example.com login --email you@example.com   # código de 6 dígitos enviado por e-mail
+agenteye whoami                                                                  # confirma usuário + org ativa
+agenteye --json sessions --since 24h                                             # uma linha por execução do agente, últimas 24h
+```
+
+O último comando imprime um objeto JSON com as sessões mais recentes (as mais novas primeiro, limitado a 50 por padrão). Encadeie com `jq` para filtrar, ou remova `--json` para obter uma tabela colorida em caixas. Cada linha contém o status da execução e, se um avaliador atribuiu uma pontuação, as métricas correspondentes (abreviadas aqui):
+
+```json
+{
+  "sessions": [
+    {
+      "session_id": "run-8f2a",
+      "agent_id": "checkout-bot",
+      "environment": "prod",
+      "status": "error",
+      "scores": { "helpfulness": 0.42, "tool_efficiency": 0.55 },
+      "event_count": 37,
+      "started_at": "2026-07-16T09:14:02Z",
+      "last_event_at": "2026-07-16T09:14:48Z"
+    }
+  ],
+  "next_cursor": null
+}
+```
+
+O restante desta página explica cada parte: [instalação](#installation) em ambiente isolado, [autenticação](#authentication), [configuração](#configuration), as [convenções globais](#global-options--conventions) compartilhadas por todos os comandos e a [referência completa de comandos](#command-reference).
+
+---
+
+## Instalação
+
+O CLI é um pacote público no PyPI chamado **`agenteye`**. Instale-o em um ambiente isolado para que sempre tenha suas próprias dependências:
+
+```bash
+pipx install agenteye
+# ou
+uv tool install agenteye
+```
+
+Requer Python 3.10+. O comando instalado é **`agenteye`**:
+
+```bash
+agenteye --version
+agenteye --help
+```
+
+> **Nota:** O SDK Python de Observabilidade do Failproof AI também usa o nome de distribuição `agenteye`. Instalar o CLI com `pipx` ou `uv tool` (em vez de `pip install` em um virtualenv compartilhado) evita conflitos entre os dois. Um simples `pip install agenteye` só é adequado se o SDK não estiver instalado no mesmo ambiente.
+
+---
+
+## Autenticação
+
+O CLI autentica no **dashboard** com um código de uso único enviado por e-mail:
+
+```bash
+agenteye login --email you@example.com
+# Um código de 6 dígitos é enviado para você; cole-o no prompt.
+```
+
+O token de sessão é armazenado em `~/.agenteye/cli.json` (legível apenas por você, modo `0600`) e é válido por 24 horas por padrão. Quando expirar, execute `agenteye login` novamente.
+
+```bash
+agenteye whoami     # exibe o usuário atual, a org ativa e as permissões
+agenteye logout     # revoga a sessão e limpa o token armazenado
+```
+
+`whoami` nunca retorna erro por sessão ausente ou expirada; em vez disso, retorna `logged_in: false`, para que um script ou agente possa verificar o estado de autenticação com segurança (ainda pode sair com código diferente de zero se nenhuma URL base estiver definida ou se o dashboard estiver inacessível).
+
+**Requisitos:** seu e-mail deve ter permissão para acessar o dashboard (solicite ao administrador do Failproof AI Observability), e o dashboard deve estar acessível na sua URL base (consulte [Configuração](#configuration)). Se você solicitar um código e ele não chegar, provavelmente seu e-mail ainda não está habilitado para acesso ao dashboard.
+
+---
+
+## Escolhendo sua organização (multi-tenant)
+
+Se sua conta pertence a mais de uma organização, escolha a ativa **no momento do login**; ela é salva e usada em todos os comandos subsequentes:
+
+```bash
+agenteye login --org acme           # autentica e define o tenant ativo em uma etapa
+agenteye orgs list                  # as orgs que você pode acessar (a ativa está marcada)
+agenteye orgs switch globex         # altera o padrão salvo
+agenteye --org globex sessions      # substituição para um único comando
+```
+
+Se você pertence a exatamente uma organização, ela é selecionada automaticamente e você pode ignorar `--org` completamente. Se pertencer a várias e não escolher uma, o CLI lista-as e solicita que você reexecute com `--org <slug>`. A org ativa é enviada ao dashboard em cada requisição, e suas permissões são resolvidas **por organização**; `agenteye whoami` exibe a org ativa, suas permissões nela e todas as suas associações.
+
+---
+
+## Configuração
+
+| Configuração | Flag | Variável de ambiente | Padrão |
+|---|---|---|---|
+| URL base do dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **obrigatório** (sem padrão) |
+| Org/tenant ativa | `--org` | `AGENTEYE_ORG` | definida no login; salva em `~/.agenteye/cli.json` |
+| Token de sessão | `--token` | `AGENTEYE_CLI_TOKEN` | de `~/.agenteye/cli.json` |
+| Saída JSON | `--json` | `AGENTEYE_CLI_JSON` | desativado |
+| Ignorar verificação TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | desativado (salvo no login) |
+| Timeout da requisição (segundos) | `--timeout` | _(nenhum)_ | 30 |
+| Desativar telemetria de uso | _(nenhum)_ | `AGENTEYE_ANALYTICS_DISABLED` (ou `DO_NOT_TRACK`) | telemetria está desativada no momento; nada é enviado |
+
+A ordem de resolução é **flag → variável de ambiente → arquivo de configuração**. Não há padrão; você deve apontar o CLI para o seu dashboard, seja por comando (`--base-url https://agenteye.example.com`) ou uma vez via variável de ambiente (também é salvo após o primeiro `login`):
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com
+```
+
+O diretório de configuração respeita `AGENTEYE_HOME` (a mesma convenção usada pelo SDK e pelo coletor); se definido, `cli.json` fica em `$AGENTEYE_HOME/cli.json`.
+
+### TLS autoassinado ou interno
+
+Se o seu dashboard usa HTTPS com um certificado autoassinado ou interno (por exemplo, o nome de host bruto de um balanceador de carga), a verificação TLS rejeita a conexão com um erro `CERTIFICATE_VERIFY_FAILED`. Use `--insecure` para ignorar a verificação de certificado:
+
+```bash
+agenteye --base-url https://agenteye.internal --insecure login
+```
+
+`--insecure` é **salvo em `cli.json` quando você faz login**, portanto os comandos posteriores ignoram a verificação automaticamente; você não precisa repetir o flag. Use `--secure` para uma chamada verificada pontual, ou para restaurar a verificação no próximo login. O CLI exibe um aviso no stderr antes de qualquer comando que contate o dashboard com a verificação desativada. Ignorar a verificação remove a proteção contra ataques man-in-the-middle; certifique-se de confiar no caminho de rede até o seu dashboard (VPN, sub-rede privada etc.) antes de depender disso.
+
+---
+
+## Telemetria e privacidade
+
+> **Nota:** O CLI distribuído **não envia telemetria de uso hoje.** Um interruptor mestre está ativo, portanto nada é transmitido independentemente do seu ambiente. A seção abaixo descreve a capacidade de desativação para quando a telemetria vier a ser habilitada.
+
+Mesmo quando habilitada, a telemetria seria **apenas análises de uso anônimo**, nunca seus dados de agente, sessão ou eventos:
+
+- **Nenhum dado de agente, sessão ou evento sai da sua infraestrutura.** Apenas o uso do CLI seria reportado: o nome do comando e subcomando (ex.: `keys create`), os **nomes** dos flags usados (nunca seus valores), status de sucesso/saída e duração, além de um evento por ação para mutações (ex.: `api_key_created`, `query_run`) contendo apenas nomes/enums estáticos e contagens aproximadas. Sua URL do dashboard, token de sessão, e-mail, slug da org, IDs de recursos, SQL, segredos de chaves e filtros de consulta **nunca** seriam enviados. Os operadores seriam identificados apenas por um ID interno opaco, nunca por e-mail.
+- **Desative antecipadamente** definindo `AGENTEYE_ANALYTICS_DISABLED=1` no ambiente do CLI (o CLI também respeita a convenção entre ferramentas `DO_NOT_TRACK=1`). Isso entra em vigor no momento em que a telemetria for ativada, permitindo que um ambiente voltado para privacidade permaneça desativado permanentemente.
+- Se a telemetria fosse habilitada, o CLI enviaria diretamente para o PostHog (`https://us.i.posthog.com`); uma máquina com esse host bloqueado simplesmente não enviaria nada e o CLI não seria afetado.
+
+---
+
+## Opções globais e convenções
+
+Leia esta seção uma vez; ela se aplica a todos os comandos.
+
+- **As opções globais vêm ANTES do comando.** `agenteye --json sessions` está correto; `agenteye sessions --json` é um erro de uso. As opções globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` e `--no-color`.
+- **`--json` imprime JSON puro no stdout e nada mais.** Linhas de status, avisos e erros vão para o **stderr**, para que uma captura do stdout com `--json` permaneça limpa para encadear com `jq`, mesmo quando uma linha de status é exibida. Sem `--json`, você obtém uma visualização colorida em caixas para leitura humana.
+- **Descubra com `--help`.** Cada comando e subcomando tem `--help` (e o alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. O help de nível superior também lista os códigos de saída e as opções globais. Não há uma superfície global legível por máquina; use `--help` por comando, além de `agenteye query schema` e `agenteye settings schema` específicos de domínio para esses dois registros.
+- **Confirmações são ignoradas automaticamente para scripts e agentes.** Comandos de criação/atualização/exclusão exibem "tem certeza?" em um terminal interativo, mas **ignoram esse prompt automaticamente sob `--json` ou quando o stdin não é um TTY** (um TTY é uma sessão de terminal interativa; um pipe ou um runner de CI não é), para que scripts e agentes nunca fiquem travados. Use `--yes`/`-y` para ignorá-lo explicitamente. Como o prompt não será exibido para um agente, ele deve confirmar ações destrutivas com o humano antes de executar.
+- **Paginação:** os resultados são os mais novos primeiro e usam paginação por cursor (cada página retorna um token para buscar a próxima). `--limit N` (alias `-n`) limita as linhas e **tem padrão de 50**; `--all` pagina automaticamente (em blocos de 200 linhas) **até `--limit`**, portanto um `--all` simples ainda para em 50. Para uma varredura completa, passe um limite alto explícito: `--all --limit 1000`. `--page-size N` controla o bloco por requisição (máximo 200); `--cursor <id>` retoma a partir do `next_cursor` de uma página anterior.
+- **Filtros de tempo:** `--since` aceita uma janela relativa: `15m`, `1h`, `6h`, `24h`, `7d` ou `all` (os presets do dashboard). Para um intervalo mais longo ou personalizado (como os últimos 30 dias), use `--from`/`--to`: timestamps UTC explícitos no formato ISO-8601 **com `T` e timezone** (ex.: `2026-06-01T00:00:00Z`) que substituem `--since`. Um valor separado por espaço ou sem timezone é um erro de uso.
+- **`--fields a,b,c`** (em `events`, `sessions`, `evals`, `errors`) restringe a saída a essas chaves, tanto na tabela quanto no `--json`. Nomes desconhecidos são rejeitados com a lista válida, uma forma barata de descobrir os nomes de campos.
+- **`--file payload.json`** (ou `--file -` para ler do stdin) fornece um corpo de requisição JSON completo quando um recurso tem uma forma complexa (em `alerts create/update`, `settings set` e `users create/update`). SQL de consultas salvas usa `--sql @file.sql` em vez disso.
+- **Filtros com múltiplos valores** são separados por vírgula → correspondidos como um conjunto (união dentro de um filtro, AND entre filtros): `--event-type tool_use,tool_result`. As opções Click não são variádicas, portanto `--add a b` não funciona. Use `--add a,b`, repita o flag (`--add a --add b`) ou use aspas (`--add "a b"`).
+
+---
+
+## Referência de comandos
+
+### Os 5 comandos que você mais usará
+
+A maior parte do trabalho cotidiano passa por um conjunto de comandos de leitura. Comece por aqui e recorra à superfície completa abaixo quando necessário:
+
+| Comando | O que faz | Experimente |
+|---|---|---|
+| `sessions` | Uma linha por execução do agente: tempo, ambiente, agente, status, última pontuação. | `agenteye --json sessions --since 24h --status error` |
+| `events` | O rastro bruto passo a passo dentro de uma execução (adicione `--full` para os payloads). | `agenteye --json events --session-id run-001 --all` |
+| `evals` | Resultados de avaliação e pontuações; `--aggregate` os agrega. | `agenteye --json evals --aggregate --since 7d --env prod` |
+| `errors` | Apenas os eventos com erro; `--aggregate` para contagens por tipo. | `agenteye --json errors --since 24h --aggregate` |
+| `list` | Descubra os valores de filtro válidos (agentes, ambientes, modelos, …). | `agenteye list agents` |
+
+### Tudo o que o CLI pode fazer
+
+A superfície completa segue abaixo. O CLI tem **18 comandos de nível superior**. Todos os comandos de leitura aceitam `--json` e as opções globais acima; execute `agenteye <command> -h` (ou `<command> <subcommand> -h`) para a lista completa de flags e o formato JSON de qualquer um deles.
+
+### Identidade: `login` · `logout` · `whoami` · `orgs` · `version` · `help`
+
+```bash
+agenteye login --email you@example.com [--org acme]   # código de uso único por e-mail; salva a sessão
+agenteye logout                                       # limpa a sessão salva nesta máquina
+agenteye whoami                                       # usuário atual, org ativa, permissões
+agenteye version                                      # exibe a versão do CLI (igual a --version)
+agenteye help                                         # help de nível superior (igual a --help)
+```
+
+`orgs` inspeciona e alterna o tenant ativo:
+
+```bash
+agenteye orgs list        # suas orgs + sua função em cada uma (a ativa está marcada)
+agenteye orgs switch acme # altera a org ativa salva (omita o slug para escolher de uma lista em um TTY)
+agenteye orgs current     # cartão de identidade da org ativa
+agenteye orgs perms       # suas permissões na org ativa, agrupadas por recurso
+```
+
+### Observar (somente leitura): `events` · `sessions` · `evals` · `errors` · `list`
+
+Nenhum desses requer confirmação. Filtros compartilhados: `--session-id`, `--agent-id`, `--env` (**não** `--environment`) e o intervalo de tempo (`--since` / `--from` / `--to`).
+
+```bash
+# events (alias: rastro bruto passo a passo), mais novos primeiro
+agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
+agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'
+
+# sessions: uma linha por execução do agente (tempo/ambiente/agente/sessão/status; sem filtro por pontuação)
+agenteye --json sessions --since 24h --status error
+agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000
+
+# evals: resultados de avaliação + pontuações; --score filtra por métrica, --aggregate agrega
+agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
+agenteye --json evals --aggregate --since 7d --env prod        # mix de status + estatísticas de pontuação por chave
+
+# errors: eventos com erro; --aggregate para contagens/sessões/agentes/último registro
+agenteye --json errors --since 24h --aggregate
+agenteye --json errors --since 24h --error-type timeout --all --limit 1000
+
+# list: descubra valores de filtro válidos antes de filtrar
+agenteye list envs        # também: agents event_types score_filters models hooks tools error_types
+```
+
+`--score KEY:MIN..MAX` (em **`evals`**, não em `sessions`) é repetível e combinado com AND; qualquer um dos limites é opcional (`..0.5` significa ≤ 0,5; `0.9..` significa ≥ 0,9). Até 20 filtros de pontuação por requisição. `evals --scores-full` é um flag de exibição **apenas para a tabela humana**; mostra todos os pares de pontuação em vez dos primeiros mais uma contagem `+N`. Não tem efeito com `--json`, que sempre retorna o objeto de pontuação completo. Para ler **uma sessão de ponta a ponta**, combine o rastro de eventos com sua avaliação:
+
+```bash
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+agenteye --json evals  --session-id run-001                       # suas pontuações + status
+```
+
+### Gerenciar (com controle de permissão): `keys` · `users` · `settings` · `alerts` · `incidents`
+
+**`keys`**: chaves de API. O segredo é gerado localmente, enviado ao servidor (que armazena apenas um hash) e **exibido uma única vez** no momento da criação/regeneração; capture-o imediatamente. Com `--json` ele aparece apenas no campo `key`. Referenciado por **nome**.
+
+```bash
+agenteye keys list                                   # chaves ativas primeiro, depois revogadas
+agenteye keys show ci-bot
+agenteye keys create ci-bot --add events:read.add    # escopo mínimo necessário; imprime o segredo UMA VEZ
+agenteye keys create ops --permission-set standard --remove queries:run   # começa com um preset, depois ajusta
+agenteye keys update ci-bot --add evaluations:read --yes
+agenteye keys regenerate ci-bot --yes                # rotaciona o segredo (o anterior para de funcionar)
+agenteye keys disable ci-bot --yes                   # revoga
+```
+
+As permissões funcionam como `(permission-set ∪ --add) − --remove`. Os tokens são `slug:action` (ex.: `events:read`) ou `slug:action.action` para expandir várias ações em um recurso (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Permissões exclusivas para humanos (`keys:update`) não podem ser concedidas a uma chave.
+
+**`users`**: membros da organização, referenciados por **e-mail** (um UUID de id também é aceito).
+
+```bash
+agenteye users list [--active-only]
+agenteye users show dev@corp.com
+agenteye users create dev@corp.com --permission-set standard
+agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # prevê + confirma
+agenteye users disable dev@corp.com --yes            # possui proteções para usuário protegido/próprio
+agenteye users enable dev@corp.com
+```
+
+**`settings`**: um registro fixo (você lê e altera chaves existentes; não é possível criar novas).
+
+```bash
+agenteye settings list                               # chave · valor · tipo · atualizado (segredos mascarados)
+agenteye settings schema                             # o que cada chave aceita (tipo · intervalo · descrição)
+agenteye settings set session_ttl_secs --value 86400 --yes
+```
+
+**`alerts`**: definições de alertas, referenciadas por **nome**. `create` aceita um NOME posicional mais flags ou um corpo JSON completo via `--file`.
+
+```bash
+agenteye alerts list
+agenteye alerts show high-errors
+agenteye alerts create high-errors --file alert.json          # NAME é obrigatório (posicional)
+agenteye alerts update high-errors --severity critical --yes
+agenteye alerts test high-errors --yes                        # dispara uma notificação de teste
+agenteye alerts delete high-errors --yes
+```
+
+**`incidents`**: incidentes de alerta, referenciados por id (ids curtos são aceitos). `show` imprime o log completo de atividades; leia-o antes de agir.
+
+```bash
+agenteye incidents list --state firing                # também: acknowledged, resolved
+agenteye incidents count
+agenteye incidents show <id>
+agenteye incidents ack <id>
+agenteye incidents assign <id> you@corp.com           # o responsável deve ser um operador
+agenteye incidents resolve <id> --yes
+agenteye incidents open --alert-id <id> --severity critical    # abre manualmente contra um alerta
+agenteye incidents comment-add <id> "root cause: upstream 5xx"
+agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
+agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>
+```
+
+### Análises e assistente: `query` · `agent`
+
+**`query`**: SQL salvo contra seu armazenamento de análises mais um executor ad-hoc. Consultas salvas são referenciadas por **nome**; o SQL é validado no servidor (apenas SELECT/WITH, timeout de instrução, limite de linhas).
+
+```bash
+agenteye query schema [TABLE]                         # layout de colunas das views de análise
+agenteye query run --sql "select count(*) from analytics.events"
+agenteye query run errs --arg prod --limit 100        # executa uma consulta salva + um $1 posicional
+agenteye query list ; agenteye query show errs
+agenteye query create errs --sql @errs.sql --description "errored events (24h)"
+agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes
+```
+
+**`agent`**: fala com o **assistente de IA** integrado (o mesmo analista somente leitura disponível para chat no dashboard). Os chats são referenciados por um chat-id curto (resolvido por prefixo).
+
+```bash
+agenteye agent health                                 # verifica se o assistente de IA está configurado/acessível
+agenteye agent models                                 # modelos que podem ser passados para --model (o padrão está marcado)
+agenteye agent ask "which agents errored most in the last day?"    # inicia um chat; imprime seu id curto
+agenteye agent ask --chat <short-id> "and which tools did they call?"   # continua aquele chat
+agenteye agent chats ; agenteye agent show <short-id>
+agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>
+```
+
+---
+
+## Códigos de saída
+
+| Código | Significado |
+|---|---|
+| 0 | Sucesso |
+| 1 | Erro inesperado (ex.: o dashboard retornou um 5xx) |
+| 2 | Erro de uso (argumentos inválidos, comando/flag desconhecido, colisão de nomes) |
+| 3 | Não foi possível alcançar o dashboard |
+| 4 | Não autenticado ou sessão expirada; execute `agenteye login` |
+| 5 | Autenticado, mas sua conta não tem a permissão necessária (a mensagem a identifica) |
+| 6 | O recurso solicitado não foi encontrado (ex.: sessão ou id de incidente desconhecido) |
+
+Esses códigos tornam o CLI seguro para scripts: um agente de codificação pode ramificar em um `4` para solicitar reautenticação, ou em um `5` para expor a permissão ausente. Consulte [Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes) para padrões de tratamento de códigos de saída e formatos de saída JSON.
+
+---
+
+## Próximos passos
+
+- **[Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes)**: padrões de consulta prontos para uso, one-liners com `jq`, projeções com `--fields`, tratamento de códigos de saída e formatos de saída JSON, escritos para agentes de codificação que operam o CLI.
+- **[Skill de agente CLI](/pt-br/agenteye/cli-skill)**: empacote este CLI como uma *skill* instalável para Claude Code / Codex, permitindo que um agente de codificação opere o Failproof AI Observability com solicitações em linguagem natural.
+- **[Chaves de API](/pt-br/agenteye/api-keys)**: o modelo de permissões por trás de `keys create --add …`.
+- **[Assistente de IA](/pt-br/agenteye/assistant)**: habilitando o assistente que `agent ask` utiliza.

package/.next/standalone/docs-old/pt-br/agenteye/codex-capture.mdx

@@ -0,0 +1,55 @@
+---
+title: "Captura de sessão do Codex"
+description: "Transmita as sessões locais do OpenAI Codex da sua equipe para o AgentEye como sessões e eventos comuns — sem nenhuma alteração na forma como eles executam o Codex."
+---
+
+Seus engenheiros já executam o OpenAI Codex todos os dias. A captura de sessão do Codex traz essas sessões de codificação para o AgentEye como sessões e eventos comuns, para que você possa pesquisar, reproduzir e avaliar junto a tudo o mais que você observa. Ela complementa o [Python SDK](/pt-br/agenteye/python-sdk): o SDK instrumenta os agentes que você escreve, enquanto este recurso captura o trabalho que sua equipe já realiza no Codex — sem nenhuma alteração na forma como eles o executam.
+
+Um pequeno coletor em segundo plano lê os transcritos de sessão locais do Codex à medida que são gravados e os envia para o AgentEye. Um coletor por máquina captura todas as superfícies locais do Codex de uma vez — sem necessidade de configuração por superfície.
+
+O mesmo coletor também captura outros agentes — veja [OpenClaw](/pt-br/agenteye/openclaw-capture) e [Hermes](/pt-br/agenteye/hermes-capture). Ative cada um que você utiliza; um único coletor pode capturar vários ao mesmo tempo.
+
+---
+
+## O que é capturado
+
+Toda superfície do Codex que executa **localmente** produz os mesmos transcritos de sessão em disco, e o coletor processa todos eles:
+
+- o **CLI** do Codex e o `codex exec`
+- a **extensão para VS Code / IDE**
+- o **aplicativo desktop**, quando executa uma sessão localmente
+
+Cada sessão do Codex se torna uma [sessão](/pt-br/agenteye/sessions) no AgentEye; suas mensagens de usuário e assistente, raciocínio, chamadas de ferramentas, resultados de ferramentas e uso de tokens se tornam os [eventos](/pt-br/agenteye/event-stream) correspondentes. A superfície de origem de cada sessão (CLI, IDE ou desktop) é registrada, permitindo diferenciá-las.
+
+> **Sessões na nuvem não são capturadas.** O aplicativo desktop executa cada vez mais sessões na nuvem do Codex e mantém apenas os metadados na máquina — não há transcrito local para leitura. Somente sessões executadas localmente são capturadas.
+
+---
+
+## Como ativar
+
+A captura está desativada até que você a habilite. Instale o coletor com uma chave de API que tenha a permissão `events:add` (veja [Chaves de API](/pt-br/agenteye/api-keys)) e ative a captura do Codex:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --codex-enabled
+```
+
+Isso instala o coletor, registra-o como um serviço em segundo plano e inicia a captura. Confirme que está em execução:
+
+```bash
+agenteye-collector health
+```
+
+Na primeira execução, suas sessões do Codex existentes são preenchidas retroativamente uma vez e, em seguida, novas atividades são transmitidas em segundos. Os arquivos do próprio Codex são apenas lidos — nunca modificados, movidos ou excluídos — e cada sessão é enviada exatamente uma vez, mesmo entre reinicializações.
+
+---
+
+## Onde aparece
+
+As sessões capturadas aparecem em **Sessions**, e seus eventos no fluxo **Events**, da mesma forma que qualquer outro agente que você observa — portanto, [replay de sessão](/pt-br/agenteye/sessions), [pesquisa](/pt-br/agenteye/queries), [avaliações](/pt-br/agenteye/evaluations) e [alertas](/pt-br/agenteye/alerts) funcionam normalmente nelas. Filtre pelo agente do Codex para visualizá-las separadamente.
+
+---
+
+## Privacidade
+
+Os transcritos do Codex contêm a sessão completa — incluindo saída de comandos, conteúdo de arquivos e tudo o que o Codex leu ou escreveu — e podem conter segredos. As sessões capturadas são enviadas como estão, portanto, ative a captura apenas em máquinas e para equipes nas quais centralizar esse conteúdo no AgentEye seja adequado, e forneça ao coletor uma chave com escopo apenas para `events:add`. Veja [Segurança](/pt-br/agenteye/security) para entender como seus dados são mantidos isolados.

package/.next/standalone/docs-old/pt-br/agenteye/concepts.mdx

@@ -0,0 +1,87 @@
+---
+title: "Conceitos"
+description: "O vocabulário por trás da Observabilidade do Failproof AI — eventos, sessões, avaliações, auditorias, descobertas e incidentes — definido em um só lugar."
+---
+
+
+Esta página define o vocabulário utilizado pela Observabilidade do Failproof AI. Se algum termo em outro guia parecer desconhecido, ele está definido aqui. Você não precisa ler do início ao fim: percorra rapidamente ou volte quando quiser esclarecer uma palavra específica.
+
+---
+
+## O modelo de dados
+
+**Evento**
+A menor unidade de dados. Um evento registra um único passo executado pelo seu agente: um `tool_use`, um `model_request`, um `hook_completed`, um `error`, entre outros. Seu agente emite eventos por meio do [Python SDK](/pt-br/agenteye/python-sdk); eles aparecem em tempo real na página **Events**.
+
+**Sessão**
+Uma execução do agente, identificada por um `session_id`. Uma sessão é composta por todos os eventos que compartilham esse id, consolidados em uma única linha na página **Sessions** e representados como um grafo de execução na página de detalhes. Uma sessão normalmente começa com `agent_start` e termina com `agent_end`.
+
+**Agente**
+Um ator nomeado dentro de uma execução, identificado por um `agent_id`. Uma execução pode envolver vários agentes: por exemplo, um planejador que cria um sub-agente de resumo. Sub-agentes carregam um `parent_id`, que é o que permite ao Failproof AI Observability exibi-los em suas próprias faixas no grafo de execução.
+
+**Ambiente**
+Um rótulo que indica onde a execução ocorreu: `production`, `staging`, `dev`. Você o define uma única vez ao configurar o SDK. Quase todas as páginas do dashboard permitem filtrar por ambiente.
+
+**Preenchimento da janela de contexto**
+O percentual da janela de contexto de um modelo consumido por uma resposta. O Failproof AI Observability registra esse valor em eventos `model_response` para os modelos que reconhece, tornando o crescimento do prompt e a compactação iminente visíveis diretamente no fluxo de eventos.
+
+---
+
+## Qualidade
+
+**Avaliação**
+Uma pontuação de qualidade para uma sessão concluída, produzida por um serviço de pontuação que você executa. As avaliações são opcionais: até que você conecte um avaliador, as sessões são registradas, mas não pontuadas. Cada avaliação pode conter várias pontuações nomeadas (por exemplo, `helpfulness`, `factuality`, `tool_efficiency`), cada uma com uma breve nota de raciocínio. Veja [Evaluation suite](/pt-br/agenteye/evaluation-suite).
+
+**Chave de pontuação**
+O nome de uma dimensão que um avaliador reporta, como `helpfulness`. Alertas e auditorias podem monitorar uma chave de pontuação específica ao longo do tempo.
+
+**Avaliador**
+Seu serviço de pontuação. O Failproof AI Observability faz um POST com a transcrição de uma execução concluída para ele e armazena as pontuações retornadas. Não há um avaliador padrão incluído; a lógica de pontuação é sua.
+
+---
+
+## Identificando e corrigindo falhas
+
+**Hook**
+Uma salvaguarda ou efeito colateral que seu framework de agentes executa em torno de um passo: uma verificação de segurança de conteúdo, anonimização de dados pessoais, um controle de orçamento. Hooks emitem eventos `hook_triggered` / `hook_completed` com um `outcome` (allow, deny, modify) e têm sua própria página de observação.
+
+**Regra de alerta**
+Uma regra que é acionada quando uma métrica ultrapassa um limite definido por você: taxa de erros, latência p95, custo em tokens ou uma pontuação de avaliação. Quando uma regra é acionada, ela abre um incidente e notifica os canais escolhidos (e-mail, Slack, webhook, no dashboard). Veja [Alerts](/pt-br/agenteye/alerts).
+
+**Incidente**
+Uma questão em aberto criada quando uma regra de alerta é acionada. Incidentes têm um ciclo de vida (reconhecer, atribuir, resolver) e uma linha do tempo de atividades que registra cada ação. Você também pode abrir um manualmente.
+
+**Auditoria**
+Uma investigação recorrente (de hora em hora a semanalmente) que analisa seus logs *entre* sessões em busca de padrões de falha para os quais você ainda não escreveu uma regra: clusters de erros, pontuações baixas, outliers de latência, loops de chamadas de ferramentas e execuções que nunca foram concluídas. Enquanto um alerta monitora uma métrica que você já conhece, uma auditoria indica o que você deve examinar a seguir. Veja [Audits](/pt-br/agenteye/audits).
+
+**Descoberta**
+Um resultado classificado e embasado em evidências proveniente de uma execução de auditoria. Uma descoberta nomeia um padrão, vincula às sessões exatas que o sustentam e possui um ciclo de vida de triagem (reconhecer, resolver, silenciar, descartar). O Failproof AI Observability deduplica descobertas entre execuções, de forma que um padrão conhecido seja atualizado em vez de se acumular.
+
+**O assistente de IA**
+O chat integrado ao dashboard que responde perguntas sobre seus agentes em linguagem natural, utilizando seus próprios dados. Por padrão, é somente leitura; qualquer coisa que ele crie (uma consulta salva, um dashboard) requer aprovação, e ele nunca pode excluir dados. Veja [AI assistant](/pt-br/agenteye/assistant).
+
+---
+
+## Operação
+
+**Organização (tenant)**
+Um espaço de trabalho isolado. Uma instância do Failproof AI Observability pode hospedar várias organizações, cada uma com seus próprios usuários, chaves e dados. Toda URL do dashboard é delimitada pelo slug da sua organização (`/<org-slug>/…`).
+
+**Coletor**
+`agenteye-collector`, o daemon leve que é executado em cada máquina de agente, agrupa os eventos que o SDK grava em disco e os envia para o servidor.
+
+**Chave de API**
+Um token com escopo definido que autentica um cliente junto ao servidor. As chaves carregam permissões granulares (por exemplo, `events:add` para o coletor, escopos somente leitura para uma chave de dashboard). Veja [API keys](/pt-br/agenteye/api-keys).
+
+**Servidor**
+O serviço de ingestão e API. Ele ingere eventos, armazena o estado operacional nos seus bancos de dados e serve o dashboard e a CLI.
+
+**Dashboard**
+A interface web. Cada página é delimitada a uma organização e lê os dados por meio da API do servidor.
+
+---
+
+## Próximos passos
+
+- [Overview](/pt-br/agenteye/overview): como essas peças se encaixam.
+- [Observability](/pt-br/agenteye/observability): as superfícies de observação (Events, Sessions, Models, Tools, Hooks, Errors).

package/.next/standalone/docs-old/pt-br/agenteye/dashboards.mdx

@@ -0,0 +1,45 @@
+---
+title: "Dashboards"
+description: "Transforme os dados ao vivo do seu agente em uma visão compartilhada que toda a equipe acompanha."
+---
+
+Transforme os dados ao vivo do seu agente em uma visão compartilhada que toda a equipe acompanha. Fixe as consultas mais importantes como gráficos e todos têm acesso aos mesmos números de forma imediata, sem precisar executar uma única consulta novamente.
+
+![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](/agenteye/images/dashboard-fleet.png)
+
+*Um painel, quatro consultas salvas: eventos por hora, erros por tipo, latência e tokens por modelo.*
+
+## Todos veem a mesma realidade
+
+Pare de colar capturas de tela no chat e de executar a mesma consulta cinco vezes por dia. Um dashboard é um painel compartilhado, visível para toda a organização, que qualquer membro da equipe pode abrir e ver exatamente a mesma visão. Quando os dados subjacentes mudam, os gráficos acompanham, então o painel está sempre atualizado e ninguém discute por causa de números desatualizados.
+
+O dashboard de frota acima é um bom ponto de partida para operações do dia a dia:
+
+- uma linha de **eventos por hora**, para acompanhar o throughput e detectar quedas repentinas
+- uma barra de **erros por tipo**, para que as principais categorias de falha fiquem evidentes
+- um gráfico de área de **latência**, para que lentidões apareçam antes que os usuários reclamem
+- uma divisão de **tokens por modelo**, para manter os custos sempre visíveis
+
+Você encontrará seus painéis em `/<org-slug>/dashboards`.
+
+## Fixe as consultas que você já salvou
+
+Cada tile começa como uma consulta salva. Crie e salve a consulta desejada na biblioteca de [Queries](/pt-br/agenteye/queries) (presets integrados mais os seus próprios, sobre seus eventos e avaliações) e, em seguida, fixe-a em um dashboard como o gráfico que melhor representa os dados: uma **linha** para tendências ao longo do tempo, uma **barra** para comparar categorias, uma **área** para volume ou um **pizza** para mostrar distribuição percentual.
+
+Como um tile é apenas sua consulta salva renderizada como gráfico, não há nada para sincronizar manualmente. Atualize a consulta uma vez e todos os dashboards que a utilizam são atualizados automaticamente.
+
+## Monitore qualidade, não apenas volume
+
+Volume indica que os agentes estão ocupados. Qualidade indica que eles estão realmente fazendo o trabalho. Aponte um dashboard para suas [pontuações de avaliação](/pt-br/agenteye/evaluations) e você terá um painel que acompanha o desempenho das execuções ao longo do tempo — assim, uma regressão de qualidade aparece como uma queda no gráfico, e não como uma surpresa vinda de um cliente.
+
+![Um dashboard focado em qualidade construído a partir de consultas de avaliação salvas](/agenteye/images/dashboard-quality.png)
+
+*Um painel de qualidade mantém suas pontuações de avaliação em destaque, lado a lado com os números operacionais.*
+
+Mantenha um painel de operações e um painel de qualidade lado a lado e sua equipe terá um único lugar para responder tanto "está funcionando?" quanto "está sendo feito bem?" — sem que ninguém precise executar uma consulta novamente.
+
+## Relacionados
+
+- [Queries](/pt-br/agenteye/queries): crie e salve as consultas que se tornarão seus tiles.
+- [Evaluations](/pt-br/agenteye/evaluations): pontue suas execuções para poder visualizar a qualidade ao longo do tempo.
+- [Alerts](/pt-br/agenteye/alerts): transforme um limite em qualquer uma dessas métricas em um alerta.

package/.next/standalone/docs-old/pt-br/agenteye/error-tracking.mdx

@@ -0,0 +1,40 @@
+---
+title: "Rastreamento de Erros"
+description: "Veja todas as falhas dos seus agentes em um único lugar, agrupadas para que uma enxurrada de erros apareça como um único problema."
+---
+
+Veja todas as falhas dos seus agentes em um único lugar, agrupadas para que uma enxurrada de erros apareça como um único problema. Você tem um caminho de um clique entre "algo está vermelho" e a execução exata que quebrou, sem precisar rolar um feed ao vivo para encontrá-la.
+
+![A página de Erros: um histograma de falhas ao longo do tempo acima de linhas de erros vermelhas agrupadas, cada uma com um botão "+ alerta" de um clique](/agenteye/images/errors.png)
+*A página de Erros: um histograma de falhas ao longo do tempo, com falhas repetidas agrupadas em uma única linha por incidente.*
+
+## Todas as falhas, já coletadas para você
+
+Quando um agente quebra, você não deveria precisar rolar um stream de eventos ao vivo esperando capturar as linhas vermelhas antes que desapareçam. A página **Errors** faz a coleta por você. Ela reúne tudo o que o dashboard pintaria de vermelho em uma única superfície de triagem, para que a primeira coisa que você veja seja o que está falhando, não onde procurar.
+
+E ela captura mais do que as falhas óbvias. Além dos eventos explícitos de `error`, o Failproof AI Observability também exibe as falhas silenciosas: qualquer `tool_result`, `hook_completed` ou `agent_end` cujo payload indique uma falha aparece aqui. Uma ferramenta que retornou um erro ou um hook que terminou com problema não passa mais despercebido só porque nenhuma exceção barulhenta foi lançada.
+
+No topo, um histograma plota os erros ao longo do tempo. Uma olhada já diz se é um gotejamento constante de fundo ou um pico que começou há alguns minutos, para que você saiba imediatamente se deve largar o que está fazendo.
+
+Como toda superfície de observação, a página de Errors é limitada à sua organização e filtra por intervalo de datas, ambiente, agente e sessão. Isso significa que você pode pegar uma lista de toda a frota e reduzi-la ao único agente ou ambiente que realmente importa.
+
+## Um incidente, não cem linhas idênticas
+
+Uma única dependência quebrada pode disparar o mesmo erro centenas de vezes por minuto. Sem tratamento, isso é uma parede de linhas quase idênticas que enterra exatamente o que você precisa ver.
+
+O Failproof AI Observability agrupa falhas repetidas que compartilham a mesma sessão e tipo de erro em uma única linha. Uma enxurrada aparece como um único incidente. Você acaba contando problemas, não linhas de log, e o sinal que importa permanece no topo em vez de ser afogado pelo seu próprio volume.
+
+## De "algo está vermelho" ao evento exato
+
+Clique em qualquer linha para ir direto para a sessão daquela execução, posicionado no evento exato que falhou. Sem copiar IDs de sessão, sem rolar para encontrar o momento em que deu errado: você chega direto nele, com o gráfico de execução completo a uma olhada de distância para ver o que o agente fez nos momentos antes de quebrar.
+
+Se você tiver `alerts:write`, cada linha também traz um botão **+ alert**. Clique nele e o Observability abre uma nova regra de alerta já preenchida para capturar essa mesma falha novamente. O incidente que você acabou de triar se torna o que vai te notificar na próxima vez, em vez de te surpreender duas vezes.
+
+**Onde encontrar:** a página **Errors** fica na seção de observação do dashboard, em `/<org-slug>/errors`.
+
+## Relacionados
+
+- [Alertas](/pt-br/agenteye/alerts): transforme qualquer falha em uma regra de notificação.
+- [Incidentes](/pt-br/agenteye/incidents): acompanhe um alerta ativo do início à resolução.
+- [Sessões](/pt-br/agenteye/sessions): abra a execução completa por trás de qualquer erro.
+- [Auditorias](/pt-br/agenteye/audits): deixe o Observability encontrar padrões de falha nas suas execuções para você.