failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,179 @@
+---
+title: "Receitas de CLI para agentes"
+description: "Padrões de consulta prontos para copiar e receitas jq que transformam dados de sessão, evento e avaliação em algo que um script ou agente de codificação pode automatizar."
+---
+
+
+Extraia dados de sessão, evento e avaliação (e dispare reavaliações) diretamente de um script ou agente de codificação, com JSON limpo no stdout que pode ser redirecionado diretamente para `jq`. Essas receitas transformam os dados da Failproof AI Observability em algo que um usuário de terminal ou um agente de codificação com IA (Claude Code, Cursor) pode consultar e automatizar, sem precisar clicar no dashboard.
+
+Os padrões abaixo estão prontos para copiar e usar com a CLI da Failproof AI Observability (`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 a ajuda integrada.
+
+## Regras de ouro
+
+1. **As opções globais vão *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. **Passe `--json` sempre que for parsear a saída.** Os dados vão para o **stdout** como JSON; mensagens de status e erros para humanos vão para o **stderr**, mantendo o stdout limpo para redirecionar ao `jq`.
+3. **Ramifique pelo código de saída**, não pelo texto do stderr: `0` ok · `1` erro inesperado · `2` argumentos inválidos · `3` não foi possível alcançar o dashboard · `4` não autenticado ou sessão expirada · `5` permissão ausente · `6` recurso não encontrado.
+4. **Explore com `-h`.** Cada comando documenta seus filtros, formatos de valores e estrutura JSON.
+
+## Configuração inicial
+
+```bash
+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 executar tarefas
+
+`whoami` nunca retorna erro em caso de sessão ausente ou expirada; ele reporta `logged_in:false` em vez disso, para que um 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.)
+
+```bash
+if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
+  echo "Não autenticado. Execute: agenteye login" >&2; exit 1
+fi
+```
+
+## Encontre sessões com falha ou pontuação baixa
+
+```bash
+# 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}'
+```
+
+A filtragem por pontuação fica no **`evals`**, não em `sessions`. `--score KEY:MIN..MAX` é repetível 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 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 do início ao fim
+
+Não existe um único comando `session show`. Combine o histórico de eventos com a avaliação da sessão:
+
+```bash
+# 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 uma varredura completa)
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+
+# apenas as chamadas de ferramenta em uma sessão (--full é obrigatório para obter o payload bruto)
+agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
+  | jq '.events[].payload'
+```
+
+> **Nota:** Por padrão, `events` lê um feed rápido sem payload. Cada evento carrega um `summary` de uma linha calculado pelo servidor, além de flags como `is_error` e contagens de tokens, mas `payload` retorna como `{}`. Para obter o payload bruto, adicione `--full` (ou `--fields payload`). O feed completo é mais lento em grande escala, então mantenha-o delimitado: combine `--full` com um único `--session-id`.
+
+## Busque tudo (paginação)
+
+Os resultados são os mais recentes primeiro e paginados por cursor.
+
+```bash
+# de uma vez: busca até 500 linhas 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 em `--json`) para diminuir o que um agente precisa ler.
+
+```bash
+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 campos válidos — uma forma simples de descobri-los.
+
+## Descubra valores de filtro válidos
+
+```bash
+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 login (ele é salvo):
+
+```bash
+agenteye login --org acme --email you@corp.com   # define o tenant na mesma etapa do login
+agenteye --json orgs list | jq -r '.orgs[].org_slug'
+agenteye --org globex --json sessions --since 24h   # sobrescreve para um único comando
+```
+
+Um login em múltiplas organizações sem `--org` sai com código diferente de zero e exibe as organizações disponíveis para escolha.
+
+## Provisione uma chave de API para o SDK/coletor
+
+```bash
+# 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    # rotacionar; agenteye keys disable ci-bot --yes para revogar
+```
+
+## Execute uma consulta salva ou ad-hoc
+
+```bash
+agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
+agenteye --json query run errs --arg prod | jq '.rows'   # uma consulta salva + um argumento posicional $1
+```
+
+## Faça a triagem de um incidente sem interação
+
+```bash
+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
+```
+
+> **Nota:** Mutações pulam automaticamente a confirmação interativa quando `--json` está ativo ou quando o stdin não é um TTY, para que agentes nunca fiquem travados; passe `--yes`/`-y` para pulá-la explicitamente em outros contextos.
+
+## Tratamento de código de saída em um script
+
+```bash
+out=$(agenteye --json sessions --since 1h) || code=$?
+case "${code:-0}" in
+  0) echo "$out" | jq '.sessions | length' ;;
+  4) echo "Sessão expirada - execute 'agenteye login'." >&2 ;;
+  5) echo "Permissão ausente (peça ao administrador a permissão evaluations:read)." >&2 ;;
+  3) echo "Dashboard inacessível - verifique a URL." >&2 ;;
+  *) echo "Erro inesperado (saída ${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` exibido 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, summary, is_error, error_type, output_tokens, context_window, context_fill`. Observe que `payload` é `{}` a menos que você solicite o feed completo com `--full` (ou `--fields payload`).
+- 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`, então um nome válido para um pode ser rejeitado pelo outro.
+
+## Próximos passos
+
+- [CLI](/pt-br/agenteye/cli): instalação, autenticação e a referência completa de opções para cada comando.
+- [Skill de agente CLI](/pt-br/agenteye/cli-skill): empacote essas receitas como uma skill que seu agente de codificação pode carregar.
+- [Chaves de API](/pt-br/agenteye/api-keys): crie e delimite as chaves com as quais a CLI, o SDK e o coletor se autenticam.
+- [Python SDK](/pt-br/agenteye/python-sdk): envie eventos para a Failproof AI Observability para que haja dados que essas receitas possam consultar.

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

@@ -0,0 +1,159 @@
+---
+title: "Skill de Agente CLI de Observabilidade do Failproof AI"
+description: "Pergunte ao seu agente de codificação 'tem algo quebrado hoje?' e deixe-o responder com dados ao vivo do Failproof AI Observability, sem precisar memorizar nenhum comando."
+---
+
+
+Pergunte ao seu agente de codificação *"tem algo quebrado hoje?"* e deixe-o responder com seus dados ao vivo do Failproof AI Observability, sem precisar memorizar nenhum comando. A **skill de CLI do Failproof AI Observability** (`agenteye-cli`) é uma *Agent Skill*: uma pequena pasta de instruções que um agente de codificação como Claude Code ou Codex carrega sob demanda. Ela ensina o agente a operar seu deployment de Observability por meio do [`agenteye` CLI](/pt-br/agenteye/cli) a partir de pedidos em linguagem natural como *"dê ao CI uma chave que só pode enviar eventos"* ou *"confirme o incidente ativo e atribua a mim."*
+
+Ela **não** é um serviço nem um binário separado; não há nada para implantar. Ela funciona sobre o CLI que você já tem instalado: o agente executa `agenteye --json …`, analisa o JSON limpo e responde em texto. Tudo o que ela pode fazer, você mesmo poderia fazer digitando os mesmos comandos.
+
+---
+
+## Como ela se relaciona com as outras interfaces do Failproof AI Observability
+
+O Failproof AI Observability oferece quatro formas de acessar os mesmos dados e controles. Elas se complementam:
+
+| Interface | O que é | Onde roda | Use quando |
+|---|---|---|---|
+| **[CLI](/pt-br/agenteye/cli)** | Referência de comandos e flags para `agenteye` | Seu terminal | Você quer executar ou automatizar um comando específico |
+| **[Receitas de CLI](/pt-br/agenteye/cli-recipes)** | Padrões de `jq`/pipeline para copiar e colar | Seu terminal / scripts | Você está integrando o CLI em automações |
+| **CLI skill** (este doc) | Uma interface em linguagem natural sobre o CLI | Seu agente de codificação, na sua estação de trabalho | Você quer *simplesmente perguntar* e deixar o agente escolher o comando |
+| **[Evaluator skill](/pt-br/agenteye/evaluator-skill)** | Uma skill irmã que projeta e constrói seu serviço de pontuação | Seu agente de codificação, na sua estação de trabalho | Você quer *produzir* pontuações de avaliação em vez de lê-las |
+| **[Python SDK skill](/pt-br/agenteye/python-sdk-skill)** | Uma skill irmã que instrumenta seu agente para emitir telemetria | Seu agente de codificação, na sua estação de trabalho | Você quer que seu agente *produza* os eventos que esta skill lê |
+| **[Assistente de IA no dashboard](/pt-br/agenteye/assistant)** | Um chat embutido no dashboard | No servidor (dentro do dashboard) | Você quer Q&A dentro do dashboard sobre seus dados |
+
+A skill em si não tem privilégios próprios; ela apenas transforma suas palavras em chamadas de CLI que rodam como você:
+
+```mermaid
+flowchart TD
+    YOU["você: 'confirme o incidente ativo'"] --> AGENT["agente de codificação (Claude Code / Codex)<br/>carrega a skill agenteye-cli"]
+    AGENT --> CLI["agenteye --json incidents ack ..."]
+    CLI -->|sua sessão de CLI autenticada| API["API do dashboard de Observabilidade"]
+```
+
+### vs. o assistente de IA no dashboard: uma distinção importante
+
+Essas são duas ferramentas diferentes com alcances de ação muito distintos:
+
+- O **assistente de IA no dashboard** ([AI assistant](/pt-br/agenteye/assistant)) é um chat embutido no dashboard, com suporte do serviço de agente. Ele é **somente leitura mais criação com aprovação**: pode rascunhar queries salvas e dashboards, mas toda escrita pausa para sua aprovação explícita com um clique, e ele nunca exclui nada. É restrito pela permissão `agent:use` e só enxerga dados da organização que você está visualizando.
+- A **CLI skill** roda na *sua* estação de trabalho dentro do *seu* agente de codificação e aciona o `agenteye` CLI **como você**. Ela pode executar toda a **superfície do CLI, incluindo mutações** (criar/rotacionar/desativar chaves de API, alterar configurações da org, resolver incidentes, excluir queries salvas), limitada apenas pelas permissões do seu login no CLI. Trate-a com exatamente o mesmo cuidado com que trataria executar esses comandos manualmente.
+
+---
+
+## Pré-requisitos
+
+1. O **`agenteye` CLI instalado** e no `PATH` (veja a referência do [CLI](/pt-br/agenteye/cli): `pipx install agenteye`).
+2. Sua **URL do dashboard** configurada (`AGENTEYE_DASHBOARD_URL`, ou o agente passa `--base-url`).
+3. Uma **sessão autenticada**: execute `agenteye login` você mesmo primeiro. A skill **não consegue** completar o login por código enviado por e-mail para você; ela dirá para executar `agenteye login` se a sessão estiver ausente ou expirada (código de saída do CLI `4`).
+
+---
+
+## Onde obter
+
+A skill está publicada na coleção pública de skills do Failproof AI:
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli)
+
+Não há nenhuma restrição de acesso — o repositório é público e a skill não precisa de nenhuma credencial própria, pois ela apenas aciona o `agenteye` CLI **público** contra o *seu* dashboard, usando a sessão com a qual *você* fez login. Você não precisa pedir permissão a ninguém.
+
+Observe que ela é publicada como sua própria pasta e **não** está dentro do pacote `pipx install agenteye`, portanto não procure por ela lá.
+
+## Instalando a skill
+
+O caminho mais rápido é o CLI [`skills`](https://skills.sh), que busca a pasta e a coloca onde seu agente procura:
+
+```bash
+# Claude Code, somente este projeto
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code
+
+# todos os projetos (instala em ~/.claude/skills/)
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy
+
+# Codex em vez disso
+npx skills add FailproofAI/skills --skill agenteye-cli -a codex
+```
+
+Depois gerencie como qualquer outra skill:
+
+```bash
+npx skills list -a claude-code      # o que está instalado
+npx skills update agenteye-cli      # baixar a versão mais recente
+npx skills remove agenteye-cli      # remover
+```
+
+Prefere instalar manualmente? Uma Agent Skill é apenas uma pasta contendo um `SKILL.md` (mais referências opcionais), então copiá-la também funciona:
+
+- **Claude Code**: coloque a pasta `agenteye-cli/` em `~/.claude/skills/` (todos os projetos) ou `<seu-repositório>/.claude/skills/` (somente aquele repositório). Claude Code a descobre automaticamente — verifique com a lista `/skills`, ou simplesmente faça uma pergunta que corresponda à sua descrição.
+- **Codex (OpenAI)**: o Codex lê o mesmo `SKILL.md`. O `agents/openai.yaml` incluído define `allow_implicit_invocation: true`, então o Codex seleciona a skill automaticamente quando uma tarefa combina; caso contrário, invoque-a explicitamente como `$agenteye-cli`.
+
+---
+
+## Segurança: mutações NÃO solicitam confirmação quando um agente executa o CLI
+
+> **Aviso:** Leia isso antes de permitir que um agente faça alterações.
+
+O `agenteye` CLI normalmente pergunta *"tem certeza?"* antes de uma ação destrutiva. Ele **pula automaticamente essa confirmação sempre que não está conectado a um terminal (que é exatamente como um agente de codificação o executa), e `--json` também a pula.** Portanto, o aviso de segurança **não** será acionado para o agente.
+
+A skill foi escrita para compensar isso: ela é instruída a declarar o comando exato que irá executar e obter seu **OK explícito antes de qualquer alteração de estado**. Mantenha essa disciplina. Quando você aciona o Failproof AI Observability por meio de um agente, *você* é a etapa de confirmação. Os comandos que alteram estado para ficar atento:
+
+- `keys create` / `update` / `disable` / `regenerate`
+- `users create` / `update` / `disable` / `enable`
+- `settings set`
+- `alerts create` / `update` / `delete` / `test`
+- os subcomandos de escrita de `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe`
+- `query create` / `update` / `delete`
+- `agent rename` / `delete`
+- `orgs switch`
+
+Tudo em **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) é somente leitura e não altera nada.
+
+Como o agente age **como você**, ele só pode fazer o que seu login tem permissão para fazer; as permissões são resolvidas **por org** (veja [API keys](/pt-br/agenteye/api-keys)). Um comando para o qual você não tem permissão retorna o código de saída `5` com o nome exato da permissão faltante, para que o agente possa informar precisamente o que pedir a um administrador em vez de falhar de forma opaca.
+
+---
+
+## O que você pode perguntar
+
+Veja como é uma interação real — uma leitura, depois uma alteração que aguarda sua confirmação:
+
+```text
+você  ▸ Tem algo quebrado no último dia?
+
+agente▸ Executando: agenteye --json errors --since 24h --aggregate
+        3 tipos de erro nas últimas 24h. O maior é TimeoutError
+        (18 ocorrências, todas no checkout-agent), depois RateLimited (5).
+        Quer ver as sessões com falha de TimeoutError?
+
+você  ▸ Dê ao CI uma chave que só pode enviar eventos.
+
+agente▸ Isso cria uma chave de API. Vou executar:
+          agenteye keys create ci --add events:add
+        Pode prosseguir?
+
+você  ▸ sim
+
+agente▸ Concluído. Chave "ci" criada com events:add apenas.
+        O segredo é exibido apenas uma vez, então guarde agora. Não consigo reexibi-lo.
+```
+
+A skill mapeia cada intenção em linguagem natural para o comando `agenteye` correto, descobrindo valores válidos primeiro (`list <kind>`, `whoami`) para não adivinhar, e declarando o comando exato antes de qualquer alteração. Mais exemplos:
+
+- *"Tem algo quebrado / falhando nas últimas 24 horas?"* → `errors --since 24h --aggregate`, depois um resumo.
+- *"Por que a sessão `run-001` falhou?"* → `events --session-id run-001 --all` + `evals --session-id run-001`.
+- *"Como está a qualidade esta semana?"* → `evals --aggregate --since 7d`, depois detalhes das execuções com baixa pontuação.
+- *"Dê ao CI uma chave que só pode enviar eventos."* → `keys create ci --add events:add` (declara o comando, depois cria e captura o segredo único).
+- *"Quem tem acesso? Torne a Dana somente leitura."* → `users list` → `users update dana@… --permission-set read-only` (após confirmar com você).
+- *"Confirme o incidente ativo e atribua a mim."* → `incidents list --state firing` → `incidents ack <id>` / `incidents assign <id> você@…`.
+
+Para os comandos exatos, flags e estruturas JSON por trás dessas interações, veja a referência do [CLI](/pt-br/agenteye/cli) e as [receitas de CLI para agentes](/pt-br/agenteye/cli-recipes).
+
+---
+
+## Próximos passos
+
+- **[CLI](/pt-br/agenteye/cli)**: referência completa de comandos e flags para `agenteye`.
+- **[Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes)**: padrões de `jq` para copiar e colar e tratamento de códigos de saída.
+- **[Evaluator agent skill](/pt-br/agenteye/evaluator-skill)**: a skill irmã, para construir o avaliador cujas pontuações `agenteye evals` lê.
+- **[Python SDK agent skill](/pt-br/agenteye/python-sdk-skill)**: a skill irmã, para instrumentar um agente para que ele emita a telemetria que `agenteye` lê.
+- **[AI assistant](/pt-br/agenteye/assistant)**: o assistente no dashboard (não confundir com esta skill de terminal).
+- **[API keys](/pt-br/agenteye/api-keys)**: o modelo de permissões por org que delimita o que a skill pode fazer.