failproofai 1.0.1-beta.1 → 1.0.2-beta.0

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

@@ -0,0 +1,401 @@
+---
+title: "Suite de Avaliação"
+description: "O Failproof AI Observability pode pontuar automaticamente cada execução de agente concluída em termos de qualidade: você fornece um pequeno serviço de pontuação e o Observability cuida do restante."
+---
+
+
+O Failproof AI Observability pode pontuar automaticamente cada execução de agente concluída em termos de qualidade: você fornece um pequeno serviço de pontuação e o Observability cuida do restante. Use-o para acompanhar as dimensões que importam para você (utilidade, eficiência de ferramentas, veracidade, segurança — você escolhe), identificar regressões cedo e comparar agentes ou ambientes de forma rápida. A pontuação é opcional: o pipeline não faz nada até que você defina `EVALUATOR_ENDPOINT` no servidor.
+
+> **Nota:** Você define as dimensões de pontuação. Seu avaliador pode retornar quaisquer chaves numéricas que desejar; o Observability armazena, acompanha tendências e exibe tudo o que você enviar.
+
+## Resumo
+
+1. **Escreva um avaliador.** Suba um pequeno serviço HTTP que leia a transcrição de uma sessão e retorne pontuações. O Observability inclui um exemplo funcional que você pode copiar. Veja [Escrevendo um avaliador com o SDK](#writing-an-evaluator-with-the-sdk).
+2. **Aponte o Observability para ele.** Defina `EVALUATOR_ENDPOINT` (e um `EVALUATOR_TOKEN` compartilhado) no processo do servidor.
+3. **Acompanhe as pontuações.** Cada sessão concluída é pontuada automaticamente; os resultados aparecem na página de detalhes da sessão, na grade de sessões e nos dashboards salvos.
+
+![Uma visualização de detalhes da sessão com o resumo da avaliação, barras de pontuação por dimensão e texto de raciocínio no painel direito](/agenteye/images/session-detail.png)
+
+*Após configurar um avaliador, cada execução concluída é pontuada e os resultados aparecem no painel direito da sessão: o resumo no topo, seguido pelas barras de pontuação por dimensão com o raciocínio correspondente.*
+
+---
+
+## Como funciona
+
+```mermaid
+flowchart LR
+    ING["ingest /events<br/>agent_end"] --> SRV["Observability server"]
+    SRV -->|"POST /evaluate"| EV["Evaluator service"]
+    EV -->|"done or pending"| SRV
+    SRV -->|"poll GET /evaluate/{job_id}"| EV
+    EV -->|"done"| SRV
+    SRV --> RES["evaluations<br/>terminal results"]
+```
+
+Quando o SDK do Observability emite um evento `agent_end` para uma sessão, o servidor
+agenda uma avaliação. Em seguida, ele envia via POST a transcrição completa de eventos para o
+seu serviço avaliador, que pode:
+
+- **Retornar o resultado inline** com `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. O
+  resultado é anexado à linha do tempo de avaliações da sessão. `reasoning` e
+  `summary` são opcionais.
+- **Adiar** com `{"status":"pending", "job_id":"abc-123"}`. O Observability então
+  chama `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` até que seu avaliador
+  retorne `{"status":"done", ...}` ou `{"status":"error", "error":"..."}`.
+
+  O intervalo de polling é por job: uma resposta `pending` pode incluir
+  `next_poll_secs` para sobrescrever o valor padrão; caso contrário, o Observability usa o
+  valor `default_poll_interval_secs` de `GET /config`; caso contrário, o servidor
+  recorre a `EVALUATOR_POLLING_INTERVAL_SECS` (padrão: 10s). Todos os valores
+  são limitados ao intervalo [1s, 1h].
+
+Sessões que nunca emitem `agent_end` (por exemplo, um processo de agente que travou)
+também podem ser processadas: o `GET /config` do avaliador pode retornar
+`{"inactivity_timeout_secs": 1800}`, e o Observability avaliará qualquer sessão
+que estiver inativa por esse tempo. Defina o campo como `null` ou omita-o para
+desabilitar esse fallback.
+
+O pipeline é completamente inativo quando `EVALUATOR_ENDPOINT` não está definido.
+
+Uma sessão pode acumular **múltiplas avaliações terminais ao longo do tempo**: cada
+evento `agent_end` (e cada re-avaliação manual pelo dashboard) acrescenta uma
+nova linha de avaliação. Esta é a forma recomendada de avaliar uma conversa retomada:
+um usuário encerra um agente, volta mais tarde, envia mais eventos,
+encerra o agente novamente, e uma segunda avaliação é executada contra a transcrição
+completa atualizada. O dashboard exibe a avaliação mais recente como título
+e as avaliações anteriores como uma linha do tempo recolhível. Enquanto uma
+avaliação está em andamento para uma sessão, eventos `agent_end` adicionais para essa
+sessão são ignorados; o próximo evento após a conclusão da avaliação em andamento
+enfileirará uma nova avaliação normalmente.
+
+O fallback por inatividade também se aplica a sessões retomadas: se novos eventos
+chegarem após uma avaliação terminal anterior e a sessão ficar inativa
+além de `inactivity_timeout_secs`, uma nova avaliação é enfileirada.
+
+Falhas transitórias (5xx, 429, timeouts, erros de rede) são repetidas com
+backoff exponencial até `EVALUATOR_MAX_ATTEMPTS`; respostas 4xx são
+terminais. O Observability pode ser executado com múltiplas instâncias de servidor
+com escalonamento horizontal; o trabalho é particionado para que a mesma sessão nunca seja
+despachada duas vezes simultaneamente.
+
+---
+
+## Contrato HTTP
+
+Todas as rotas autenticadas usam **autenticação por bearer token**. O mesmo valor deve ser
+configurado nos dois lados:
+
+- Servidor do Observability: variável de ambiente `EVALUATOR_TOKEN`
+- Serviço avaliador: configurado da mesma forma (o SDK `agenteye-evaluator`
+  lê `EVALUATOR_TOKEN` por convenção)
+
+Se `EVALUATOR_TOKEN` não estiver definido, o servidor não envia o cabeçalho `Authorization`; o
+avaliador pode então aceitar requisições anônimas, o que é aceitável para uma
+rede interna, mas não é recomendado na internet pública.
+
+### Rotas que o avaliador deve servir
+
+| Rota | Corpo / parâmetros | Resposta |
+|---|---|---|
+| `GET /health` | nenhum | `{"status":"ok"}` (aberta, sem autenticação) |
+| `GET /config` | nenhum | `{"inactivity_timeout_secs": <int> \| null, "default_poll_interval_secs": <int> \| omitted}` |
+| `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` ou `{"status":"pending", "job_id":"..."}` |
+| `GET /evaluate/{id}` | nenhum | mesmo formato de resposta que `/evaluate` |
+
+### Corpo `EvalRequest` enviado pelo servidor
+
+```json
+{
+  "schema_version": "1",
+  "session_id":     "session-abc123",
+  "agent_id":       "planner",
+  "environment":    "production",
+  "started_at":     "2026-05-10T12:00:00Z",
+  "ended_at":       "2026-05-10T12:05:00Z",
+  "events": [
+    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
+    ...
+  ]
+}
+```
+
+### Formatos de resposta
+
+**Síncrono (done):**
+
+```json
+{
+  "status": "done",
+  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
+  "reasoning": {
+    "helpfulness": "answered the question directly with citations",
+    "tool_efficiency": "called list_files three times when one would have done"
+  },
+  "summary": "strong answer quality, weak tool selection"
+}
+```
+
+`reasoning` (um mapa de justificativa por pontuação) e `summary` (uma narrativa
+geral em um parágrafo) são ambos opcionais. As chaves em `reasoning` devem
+espelhar as chaves em `scores`; o dashboard renderiza cada entrada inline abaixo
+da barra de pontuação correspondente. Avaliadores mais antigos que retornam apenas `scores` continuam
+funcionando sem alterações; `reasoning` e `summary` simplesmente são lidos como null e
+os elementos visuais correspondentes na interface são omitidos.
+
+**Assíncrono (adiado):**
+
+```json
+{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }
+```
+
+`next_poll_secs` é opcional; se omitido, o servidor recorre ao
+`default_poll_interval_secs` do avaliador em `/config` e, em seguida, à sua própria
+variável de ambiente `EVALUATOR_POLLING_INTERVAL_SECS`.
+
+**Erro terminal no lado do avaliador:**
+
+```json
+{ "status": "error", "error": "model service unavailable" }
+```
+
+O servidor trata qualquer outro corpo 2xx como um erro de protocolo e registra um
+`error` terminal para a sessão.
+
+---
+
+## Escrevendo um avaliador com o SDK
+
+Você não precisa implementar o contrato HTTP manualmente. O pacote Python `agenteye-evaluator`
+fornece um wrapper FastAPI tipado que cuida da autenticação, roteamento e
+dos formatos de requisição/resposta por você.
+
+O Failproof AI Observability também inclui um **avaliador de referência funcional** que
+pontua `helpfulness`, `tool_efficiency` e `factuality` a partir do formato da
+transcrição. Copie-o como ponto de partida e substitua pela sua própria lógica: um
+juiz LLM, um motor de regras, o que melhor se adequar ao seu padrão de qualidade.
+
+Avaliador mínimo viável:
+
+```python
+import os
+from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse
+
+app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])
+
+@app.evaluator
+def run(req: EvalRequest) -> EvalResponse:
+    # Inspect req.events (the full session transcript) and return scores.
+    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
+    return EvalResponse(
+        scores={"tool_calls": float(tool_calls)},
+        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
+        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
+    )
+```
+
+A instância `app` roda sob qualquer servidor ASGI, portanto `uvicorn module:app` a inicializa.
+
+Para avaliadores que precisam adiar trabalho pesado, retorne `JobPending`
+em vez disso e registre um handler `@app.job_lookup`; o servidor do Observability
+faz polling em `GET /evaluate/{job_id}` até que você retorne um status terminal ou o
+limite `EVALUATOR_MAX_POLL_DURATION_SECS` (padrão: 1 h) seja atingido.
+
+A referência completa da API, o padrão assíncrono e o esquema de eventos estão documentados no
+README do SDK `agenteye-evaluator`.
+
+---
+
+## Executando seu avaliador
+
+O avaliador é **seu serviço** — o Failproof AI Observability não inclui um
+avaliador padrão, então você o constrói e executa onde preferir.
+Ele roda sob qualquer servidor ASGI (por exemplo, `uvicorn my_evaluator:app`); sirva
+as rotas `/health`, `/config` e `/evaluate` conforme o
+[contrato HTTP](#http-contract) e então aponte o servidor para ele (veja
+[Configurando o servidor](#configuring-the-server)).
+
+Quando o avaliador estiver acessível, `GET /health` retorna `{"status":"ok"}`. Após
+uma execução completa do agente, `GET /evaluations` no servidor retorna uma linha com
+`status: "done"` e as pontuações produzidas pelo seu avaliador.
+
+---
+
+## Configurando o servidor
+
+Defina no processo do servidor:
+
+| Variável de ambiente | Significado |
+|---|---|
+| `EVALUATOR_ENDPOINT` | URL base do seu avaliador (`http://evaluator:9000`). Sem definição = pipeline desabilitado. |
+| `EVALUATOR_TOKEN` | Bearer token. Deve ser igual ao valor configurado no serviço avaliador. |
+| `EVALUATOR_WORKERS` | Tarefas de worker por instância do servidor (padrão: 2). |
+| `EVALUATOR_CLAIM_BATCH` | Linhas processadas por tick do worker (padrão: 4). Os lotes são processados **de forma concorrente**; a concorrência efetiva no endpoint do avaliador é `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. |
+| `EVALUATOR_POLL_IDLE_SECS` | Quanto tempo um worker dorme entre tentativas de despacho quando nenhuma avaliação está pendente (padrão: 2s). |
+| `EVALUATOR_POLLING_INTERVAL_SECS` | Fallback final para o intervalo de `GET /evaluate/{id}` quando nem `next_poll_secs` por resposta nem `default_poll_interval_secs` do avaliador estão definidos (padrão: 10s). |
+| `EVALUATOR_REQUEST_TIMEOUT_MS` | Timeout por requisição (padrão: 30000). |
+| `EVALUATOR_MAX_ATTEMPTS` | Após esse número de falhas transitórias, o resultado é registrado como `error` terminal (padrão: 5). |
+| `EVALUATOR_CONFIG_REFRESH_SECS` | Intervalo de `GET /config` (padrão: 300). |
+| `EVALUATOR_MAX_POLL_DURATION_SECS` | Tempo máximo de relógio que uma sessão pode permanecer na fila de polling antes de ser encerrada como `timeout` (padrão: 3600s). Protege contra avaliadores que ficam retornando `pending` indefinidamente. |
+
+Para ativar a pontuação automática, defina tanto `EVALUATOR_ENDPOINT` quanto
+`EVALUATOR_TOKEN` no servidor e, em seguida, reinicie-o para aplicar a mudança. Com
+`EVALUATOR_ENDPOINT` não definido, o pipeline permanece inativo.
+
+Os ajustes acima são opcionais; defina as variáveis de ambiente correspondentes
+no servidor somente se precisar sobrescrever os valores padrão.
+
+---
+
+## Referência da API
+
+| Método | Caminho | Permissão necessária | Finalidade |
+|---|---|---|---|
+| `GET` | `/evaluations` | `evaluations:read` | Consultar resultados terminais. Suporta `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` tem padrão 50 e máximo 200 (diferente de `/events`, que tem máximo 1000). `environment` aceita uma lista separada por vírgula (ex.: `environment=prod,staging`); valores únicos também funcionam. Com `latest_per_session=true`, a resposta contém no máximo uma linha por `session_id` (a mais recente por `completed_at`), usada pela página de lista de sessões para condensar a linha do tempo de avaliações de uma sessão ao seu título atual. O padrão é false (retorna o histórico completo). |
+| `GET` | `/evaluations/aggregate` | `evaluations:read` | Métricas consolidadas de saúde de avaliação para um subconjunto filtrado: contagem total, breakdown de done/error/timeout, estatísticas por chave de pontuação (contagem/média/mín/máx/p50 sobre as chaves arbitrárias de `scores`) e uma linha do tempo por intervalos de tempo. Aceita os **mesmos parâmetros de filtro que `/evaluations`** mais `featured_keys` (CSV de chaves de pontuação para tendências) e `latest_per_session`. Alimenta o recurso de Dashboards; as métricas são exatas sobre todo o conjunto correspondente, sem amostragem. |
+| `GET` | `/evaluations/environments` | `evaluations:read` | Valores distintos de environment da tabela `evaluations`. Usado para preencher dropdowns de filtro com escopo de dados legíveis por avaliação. |
+| `GET` | `/evaluation-jobs` | `evaluations:read` | Visibilidade sobre avaliações em andamento. Filtre por `status` (`pending`/`polling`). |
+| `GET` | `/events` | `events:read` | Transmitir os eventos brutos de uma sessão. Suporta `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` e `order`. `order` é `desc` (mais recente primeiro, padrão) ou `asc` (mais antigo primeiro); um valor não reconhecido recorre a `desc`. Pagine via cursor usando o `next_cursor` da resposta (um id de evento): passe-o de volta como `cursor` para obter a próxima página; com `asc` a próxima página contém eventos após esse id, com `desc` os eventos antes dele. `limit` tem padrão 50 e máximo 1000. |
+| `GET` | `/sessions/:session_id/export` | `events:read` | Retorna o corpo JSON exato que o avaliador receberia para esta sessão, servido como um anexo para download chamado `session-<id>.json`. Útil para reproduzir sessões de produção pelo `agenteye-evaluator` em testes offline. Os bytes são idênticos ao que o pipeline do avaliador envia. |
+| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Enfileirar uma nova avaliação para uma sessão; executa independentemente de uma avaliação anterior existir. O novo resultado é **anexado** à linha do tempo de avaliações da sessão em vez de sobrescrever o anterior, para que as pontuações anteriores permaneçam visíveis como histórico. Retorna `202` ao enfileirar, `404` para uma sessão desconhecida, `409` se uma avaliação já estiver em andamento. Use isso após implantar um novo avaliador ou para sessões que nunca emitiram `agent_end`. |
+
+### Filtragem por intervalo de pontuação: `score_filters`
+
+`GET /evaluations` aceita um parâmetro opcional `score_filters` que
+restringe resultados por valores numéricos dentro do objeto `scores`. O
+parâmetro é uma lista separada por vírgula de entradas `chave:mín..máx`; qualquer
+um dos limites pode ser omitido. Múltiplas entradas são combinadas com AND lógico. Linhas
+onde a chave nomeada está ausente ou não é numérica são excluídas. Uma requisição pode
+ter no máximo 20 entradas de filtro; exceder isso retorna HTTP 400.
+
+Exemplos:
+```text
+# helpfulness em [0.5, 0.8]
+GET /evaluations?score_filters=helpfulness:0.5..0.8
+
+# tool_efficiency no máximo 0.3 (sem limite inferior)
+GET /evaluations?score_filters=tool_efficiency:..0.3
+
+# helpfulness >= 0.5 E factuality >= 0.9
+GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..
+```
+
+Cada objeto de resposta de `/evaluations` tem os seguintes campos:
+
+| Campo | Tipo | Notas |
+|---|---|---|
+| `evaluation_id` | string (UUID) | O identificador canônico desta avaliação terminal. Cada avaliação terminal recebe um novo UUID; uma única sessão pode ter múltiplas. |
+| `id` | string (UUID) | Alias de compatibilidade retroativa com o mesmo valor que `evaluation_id`. |
+| `session_id` | string | A sessão contra a qual esta avaliação foi executada. Uma sessão pode ter múltiplas avaliações na linha do tempo. |
+| `agent_id` | string | Identifica o agente que produziu a sessão. |
+| `environment` | string | Rótulo de ambiente copiado da sessão. |
+| `status` | enum | Um de `"done"`, `"error"`, `"timeout"`. |
+| `scores` | object \| null | Pontuações retornadas pelo seu avaliador. |
+| `reasoning` | object \| null | Mapa opcional de justificativa por pontuação retornado pelo seu avaliador. As chaves geralmente espelham as de `scores`. O dashboard renderiza cada entrada abaixo da barra de pontuação correspondente. |
+| `summary` | string \| null | Narrativa geral opcional em um parágrafo retornada pelo seu avaliador. O dashboard a renderiza acima do detalhamento por pontuação como título da avaliação. |
+| `error` | string \| null | Preenchido somente em `"error"` / `"timeout"`. |
+| `attempt_count` | integer | Número de tentativas de despacho (≥ 1). |
+| `duration_ms` | integer \| null | Duração da tentativa final. |
+| `completed_at` | string (ISO 8601 UTC) | Quando o resultado terminal foi registrado. Os resultados são ordenados por `completed_at` (mais recente primeiro). |
+| `created_at` | string (ISO 8601 UTC) | Carrega o mesmo timestamp que `completed_at` (semântica de escrita única). |
+
+---
+
+## Permissões
+
+| Permissão | Concede |
+|---|---|
+| `evaluations:read` | Listar resultados de avaliação, visualizar pontuações no dashboard e carregar métricas de saúde do dashboard. |
+| `evaluations:trigger` | Enfileirar manualmente uma avaliação para uma sessão via `POST /sessions/:session_id/re-evaluate` ou pelo botão de re-avaliação no dashboard. |
+| `dashboards:read` | Visualizar dashboards salvos (também requer `evaluations:read` para carregar suas métricas). |
+| `dashboards:write` | Criar e editar dashboards. |
+| `dashboards:delete` | Excluir dashboards. |
+
+O admin bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) recebe todas essas permissões automaticamente.
+
+---
+
+## Visualizando resultados
+
+- **`/sessions/<id>`**: linha do tempo de eventos + painel direito exibindo as pontuações
+  da sessão e qualquer erro da tentativa de despacho. Se sua chave tiver
+  `evaluations:trigger`, um botão de **re-avaliar** aparece ao lado do botão de exportar,
+  útil para sessões que nunca emitiram `agent_end` ou para atualizar
+  pontuações após implantar um novo avaliador. O dashboard faz polling pelo
+  novo resultado e atualiza o painel direito quando ele chegar.
+- **`/sessions`**: grade de sessões filtráveis; a coluna de pontuação exibe o
+  status de avaliação e as pontuações de cada sessão de forma rápida.
+- **`/dashboards`**: visualizações salvas de saúde de avaliação (veja [Dashboards](#dashboards) abaixo).
+
+![A grade de Sessões com pílulas de status de avaliação por sessão e emblemas de pontuação codificados por cor (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png)
+
+*A grade de sessões exibe o status de avaliação e as pontuações de cada execução de forma rápida; emblemas em vermelho/âmbar/verde destacam pontuações baixas.*
+
+---
+
+## Dashboards
+
+A página **Dashboards** (`/dashboards`) permite salvar uma combinação de
+filtros de avaliação como uma visualização nomeada e reutilizável, e acompanhar como esse
+subconjunto de avaliações está se saindo de forma rápida. Os dashboards são **compartilhados em toda a sua organização**;
+todos com `dashboards:read` veem o mesmo conjunto.
+
+Cada dashboard fixa:
+
+- **Filtros**: os mesmos controles da página de sessões: ambiente, status,
+  agente, uma janela de tempo rolante e filtros de intervalo de pontuação (`chave:mín..máx`).
+- **Uma configuração de exibição**: quais chaves de pontuação destacar, os limites de saúde
+  verde/âmbar/vermelho, quais painéis exibir e se deve condensar à avaliação mais recente
+  por sessão.
+
+Cada card exibe o número de sessões correspondentes, um breakdown de done/error/timeout,
+a média de cada pontuação destacada e um pequeno sparkline de tendência. Ao abrir um
+dashboard, os painéis são exibidos em tamanho completo; **"abrir em sessões"** leva você à
+página de sessões pré-filtrada exatamente para aquele subconjunto. As métricas são calculadas
+no servidor sobre todo o conjunto correspondente (via `GET /evaluations/aggregate`), portanto
+os números são exatos em vez de amostrados.
+
+![Um dashboard de saúde de avaliação com barras de pontuação média por dimensão do avaliador, um breakdown de ferramenta ok vs. erro, principais ferramentas e uma tendência de eventos por hora](/agenteye/images/dashboard-quality.png)
+
+**Permissões:** visualizar requer tanto `dashboards:read` quanto `evaluations:read`;
+criar e editar requer `dashboards:write`; excluir requer `dashboards:delete`.
+O admin bootstrap recebe todas essas permissões automaticamente.
+
+---
+
+## Solução de problemas
+
+**Sessões existem, mas nenhuma avaliação é criada.** Confirme que `EVALUATOR_ENDPOINT`
+está definido no processo do servidor, que o servidor e o avaliador compartilham o mesmo
+valor de `EVALUATOR_TOKEN` e que o endpoint `/health` do avaliador está
+acessível a partir do servidor. Com `EVALUATOR_ENDPOINT` não definido, o pipeline é inativo.
+
+**Avaliações em andamento se acumulam.** Consulte `GET /evaluation-jobs` para ver a
+fila em andamento. Inspecione `attempt_count`, `next_attempt_at` e `last_error`
+em cada linha. Causas comuns: serviço avaliador inacessível ou retornando 5xx
+(repetido com backoff), `EVALUATOR_TOKEN` incorreto (401 é terminal) ou um
+avaliador assíncrono que retorna `pending` indefinidamente (veja abaixo).
+
+**Sessões concluídas, mas sem avaliação terminal.** Consulte
+`GET /evaluation-jobs?status=polling`; o resultado pode ainda estar em andamento.
+Se um job estiver preso em `pending`, o servidor está tendo dificuldade para alcançar o
+avaliador; verifique se o avaliador está em execução e se `EVALUATOR_TOKEN` corresponde.
+
+**`HTTP 401 from evaluator: invalid bearer token`.** O `EVALUATOR_TOKEN`
+no servidor não corresponde ao valor configurado no serviço avaliador.
+Eles devem ser idênticos.
+
+**O avaliador assíncrono retorna `pending` indefinidamente.** O servidor faz polling em
+`GET /evaluate/{job_id}` até que o avaliador retorne `done` ou `error`, ou
+até que `EVALUATOR_MAX_POLL_DURATION_SECS` (padrão: 1 h) expire. Após o limite,
+a avaliação é registrada como `timeout` e removida da fila em andamento.
+Aumente `EVALUATOR_MAX_POLL_DURATION_SECS` se seu avaliador legitimamente precisar
+de mais tempo do que o padrão.
+
+---
+
+## Próximos passos
+
+- [Habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill): tenha um agente de código projetando suas dimensões a partir de sessões reais e construindo este serviço para você.
+- [SDK Python](/pt-br/agenteye/python-sdk): emita os eventos `agent_end` que acionam a pontuação.
+- [Chaves de API](/pt-br/agenteye/api-keys): as permissões `evaluations:read` e `evaluations:trigger`.
+- [Auditorias](/pt-br/agenteye/audits): o outro recurso de qualidade automatizado do Observability, para revisão baseada em políticas.

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

@@ -0,0 +1,51 @@
+---
+title: "Avaliações"
+description: "Problemas de qualidade chegam até você antes de virar reclamação de usuário."
+---
+
+
+Problemas de qualidade chegam até você antes de virar reclamação de usuário. Conecte seu próprio serviço de pontuação uma única vez e a Observabilidade do Failproof AI avalia automaticamente cada execução concluída — assim, uma queda na utilidade ou um pico de alucinações aparece sozinho, antes que qualquer cliente sinta.
+
+![A grade de Sessões com uma coluna de pontuação: cada execução exibe um indicador de status de avaliação e badges com código de cores para utilidade, factualidade e eficiência de ferramentas](/agenteye/images/sessions-list.png)
+
+*Cada execução na grade de sessões carrega suas pontuações; badges vermelhos, âmbar e verdes destacam as execuções problemáticas sem que você precise abrir uma única transcrição.*
+
+## Pare de amostrar execuções manualmente
+
+Antes, você verificava algumas execuções aleatoriamente e torcia para que o restante estivesse bem. Agora, toda sessão concluída é pontuada no momento em que termina, nas dimensões que importam para você: utilidade, eficiência de ferramentas, factualidade, segurança — qualquer que seja o seu critério de qualidade. Você define as chaves de pontuação; a Observabilidade do Failproof AI armazena, analisa tendências e exibe tudo que o seu avaliador retornar. Nenhuma execução fica sem pontuação, e você para de descobrir regressões por meio de tickets de suporte.
+
+As pontuações aparecem na grade de sessões em **`/<org-slug>/sessions`** (barra lateral → *observe* → *sessions*), com um cluster de badges por linha. Quer ver apenas as execuções que ficaram abaixo do esperado? Filtre a grade por intervalo de pontuação — por exemplo, utilidade abaixo de 0,5 — e acesse exatamente as execuções que valem a pena examinar. Para visualizar pontuações, é necessária a permissão `evaluations:read`.
+
+## Entenda por que uma execução teve pontuação baixa
+
+Um número te diz que uma execução foi fraca; a página da sessão te diz o porquê. Abra qualquer execução e o painel lateral começa com o resumo geral, depois exibe uma barra por dimensão com o próprio raciocínio do avaliador abaixo de cada uma — assim você vai de "essa execução tirou 0,4 em factualidade" até a afirmação exata que deu errado, em segundos.
+
+![O painel lateral de uma sessão: o resumo da avaliação no topo, depois barras de pontuação por dimensão cada uma com uma linha de raciocínio, ao lado da linha do tempo completa de eventos](/agenteye/images/session-detail.png)
+
+*A visualização de detalhe da sessão: resumo, barras de pontuação por dimensão e o raciocínio por trás de cada pontuação, bem ao lado da linha do tempo de eventos da execução.*
+
+Implantou um avaliador mais preciso, ou está olhando para uma execução que travou antes de ser pontuada? Um botão **re-evaluate** (bloqueado por `evaluations:trigger`) reponua a sessão no lugar e adiciona o novo resultado à sua linha do tempo, preservando as pontuações anteriores como histórico. Você o encontrará em **`/<org-slug>/sessions/<session-id>`**.
+
+## Acompanhe a tendência de qualidade em toda a frota
+
+Uma execução com pontuação baixa é ruído; uma coorte inteira caindo é um sinal. Dashboards salvos transformam suas pontuações em uma tendência que você pode acompanhar de relance: média de utilidade desta semana versus a semana passada, por agente, por ambiente.
+
+![Um dashboard de qualidade: barras de pontuação média por dimensão do avaliador ao lado de uma tendência ao longo do tempo](/agenteye/images/dashboard-quality.png)
+
+*Um dashboard de qualidade salvo mostra a tendência das chaves de pontuação que você destaca, tornando uma deriva lenta óbvia muito antes de se tornar um incidente.*
+
+Os dashboards ficam em **`/<org-slug>/dashboards`** (barra lateral → *analyze* → *dashboards*), são compartilhados com toda a sua organização, e cada card consolida as sessões correspondentes: quantas houve, a média de cada pontuação destacada e um sparkline de tendência. "Open in sessions" leva você diretamente às execuções pré-filtradas por trás de qualquer número. Para visualizar, são necessárias as permissões `dashboards:read` e `evaluations:read`.
+
+## Conecte um avaliador uma única vez
+
+A pontuação é opt-in e fica completamente desativada até que você aponte a Observabilidade do Failproof AI para um avaliador. Você sobe um pequeno serviço HTTP (a Observabilidade inclui uma referência funcional que você pode copiar), define dois valores no seu servidor, e a partir daí toda execução é pontuada automaticamente. O guia completo, o contrato de pontuação e o SDK estão no guia detalhado.
+
+Não tem certeza de quais dimensões valem a pena pontuar? A [habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill) faz com que seu agente de código descubra isso com base nas suas próprias sessões, depois cria e implanta o serviço.
+
+## Relacionados
+
+- [Suite de avaliação](/pt-br/agenteye/evaluation-suite): conecte seu avaliador, o contrato de pontuação e o SDK.
+- [Habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill): deixe um agente de código escolher suas dimensões de pontuação e construir o avaliador.
+- [Sessões](/pt-br/agenteye/sessions): a grade execução por execução onde as pontuações aparecem.
+- [Dashboards](/pt-br/agenteye/dashboards): salve e compartilhe tendências de qualidade em toda a sua organização.
+- [Auditorias](/pt-br/agenteye/audits): outro recurso automático de qualidade da Observabilidade, para investigações entre sessões.

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

@@ -0,0 +1,167 @@
+---
+title: "Habilidade de Agente Avaliador de Observabilidade Failproof AI"
+description: "Vá de 'acho que nosso agente às vezes falha' a um serviço de pontuação implantado, com seu agente de codificação tanto decidindo quanto construindo."
+---
+
+
+Vá de *"acho que nosso agente às vezes falha"* a um serviço de pontuação implantado, com seu agente de codificação tanto decidindo quanto construindo. A **habilidade de avaliador de Observabilidade Failproof AI** (`agenteye-evaluator`) é 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 determinar quais dimensões de qualidade valem a pena rastrear para o *seu* agente, e então escrever, testar e implantar o [serviço avaliador](/pt-br/agenteye/evaluation-suite) que os pontua.
+
+Ela **não** é um pontuador hospedado, um registro para o qual você faz upload, ou um sistema de plugins. Seu avaliador permanece sendo seu próprio serviço HTTP na sua própria infraestrutura, exatamente como descrito no guia [Evaluation suite](/pt-br/agenteye/evaluation-suite). A habilidade apenas ensina seu agente a construí-lo bem, de modo que tudo o que ela faz, você poderia fazer escrevendo o mesmo código.
+
+---
+
+## A parte difícil é decidir o que pontuar
+
+A superfície do SDK é pequena — um decorator e dois modelos — e um agente pode escrever isso apenas com o [contrato](/pt-br/agenteye/evaluation-suite#http-contract). Não é aí que os avaliadores falham. Eles falham porque pontuam a coisa errada, e um avaliador que pontua a coisa errada é pior do que nenhum: ele produz um dashboard que todos aprendem a ignorar.
+
+Por isso, a maior parte da habilidade é a etapa anterior a qualquer código. Ela faz o agente entrevistá-lo (*"descreva uma execução que correu bem; agora uma que correu mal"*), depois puxa suas sessões reais pelo [`agenteye` CLI](/pt-br/agenteye/cli) e as lê do início ao fim. Essas duas metades geralmente discordam, e a lacuna é exatamente o ponto: o que você pretende medir versus o que suas transcrições podem realmente suportar. Uma dimensão só sobrevive se for **computável** a partir dos eventos e **discriminatória** — se pontua 0,9 tanto na sua boa execução quanto na ruim, não ensina nada e é cortada.
+
+O resultado é uma proposta de 2 a 4 dimensões com o raciocínio anexado, para você aprovar antes que uma linha seja escrita.
+
+```mermaid
+flowchart TD
+    YOU["você: 'quero avaliações para meu bot de suporte'"] --> AGENT["agente de codificação (Claude Code / Codex)<br/>carrega a habilidade agenteye-evaluator"]
+    AGENT -->|"entrevista: como é bom vs ruim?"| YOU
+    AGENT -->|"agenteye --json sessions / events"| DATA["suas sessões reais<br/>o que realmente acontece"]
+    DATA --> DIMS["2-4 dimensões, você aprova"]
+    DIMS --> SVC["seu serviço avaliador<br/>SDK agenteye-evaluator"]
+    SVC --> SCORES["pontuações chegam no dashboard<br/>e em agenteye evals"]
+```
+
+---
+
+## Como ela se relaciona com as outras partes de avaliação
+
+Quatro documentos cobrem pontuação, e eles se encadeiam em ordem:
+
+| Página | O que é | Consulte quando |
+|---|---|---|
+| **[Evaluations](/pt-br/agenteye/evaluations)** | O recurso: pontuações na grade de sessões, dashboards, reavaliar | Você quer saber o que a pontuação automática oferece |
+| **[Evaluation suite](/pt-br/agenteye/evaluation-suite)** | O contrato HTTP, o SDK, as variáveis de ambiente do servidor | Você está implementando ou depurando o avaliador por conta própria |
+| **Habilidade de avaliador** (este documento) | Uma porta de entrada em linguagem natural para projetar *e* construir o pontuador | Você quer ir de "quero avaliações" a um serviço em execução |
+| **[CLI skill](/pt-br/agenteye/cli-skill)** | Uma porta de entrada em linguagem natural para o `agenteye` CLI | Você quer *ler* as pontuações que já possui |
+| **[Python SDK skill](/pt-br/agenteye/python-sdk-skill)** | Uma porta de entrada em linguagem natural para instrumentar seu agente | Seu agente ainda não está emitindo sessões — não há nada para pontuar |
+
+### vs. a CLI skill: construir versus ler
+
+As duas habilidades são deliberadamente não sobrepostas, e instalar ambas é a configuração normal — o agente escolhe entre elas com base no que você pede:
+
+- **`agenteye-evaluator`** (este documento) constrói a coisa que *produz* pontuações. Seu trabalho termina quando as pontuações chegam pela primeira vez.
+- **[`agenteye-cli`](/pt-br/agenteye/cli-skill)** lê pontuações que já existem (`agenteye evals`). *"A qualidade caiu esta semana?"* é a pergunta dela, não desta habilidade.
+
+---
+
+## Pré-requisitos
+
+1. O **`agenteye` CLI instalado e com login efetuado** (`pipx install agenteye`, depois `agenteye login`). A habilidade depende dele duas vezes: para puxar as sessões reais com as quais projeta, e para confirmar que suas pontuações chegaram ao final. Seu login precisa de `events:read`, mais `evaluations:read` para essa verificação final. Como acontece com a CLI skill, ela **não pode** completar o login com código único enviado por e-mail por você.
+2. **Um lugar para o avaliador residir.** Ele é construído em uma imagem e executado como um serviço de longa duração, portanto precisa de um repositório real, não de um arquivo temporário. Avaliadores geralmente vivem em seu próprio repositório, separado do agente sendo pontuado — a habilidade procura um existente e pergunta antes de criar um novo.
+3. **O wheel do SDK `agenteye-evaluator`** — leia a próxima seção antes de deixar seu agente começar a digitar comandos `pip`.
+
+---
+
+## Onde obtê-la
+
+A habilidade está publicada na coleção pública de habilidades da Failproof AI:
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator)
+
+O repositório é público e a habilidade não precisa de nenhuma credencial própria — ela apenas aciona o `agenteye` CLI com a sessão com a qual *você* fez login, e escreve código no *seu* repositório. Observe que ela é distribuída como sua própria pasta e **não** está dentro do pacote `pipx install agenteye`, portanto não a procure lá.
+
+## Instalando a habilidade
+
+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-evaluator -a claude-code
+
+# todos os projetos (instala em ~/.claude/skills/)
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy
+
+# Codex em vez disso
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex
+```
+
+Depois gerencie como qualquer outra habilidade:
+
+```bash
+npx skills list -a claude-code           # o que está instalado
+npx skills update agenteye-evaluator     # baixar a versão mais recente
+npx skills remove agenteye-evaluator     # 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-evaluator/` 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 peça avaliações.
+- **Codex (OpenAI)**: Codex lê o mesmo `SKILL.md`. O arquivo `agents/openai.yaml` incluído define `allow_implicit_invocation: true`, então o Codex seleciona automaticamente a habilidade quando uma tarefa combina; caso contrário, invoque-a explicitamente como `$agenteye-evaluator`.
+
+---
+
+## O SDK não está no PyPI público
+
+> **Aviso:** Leia isso antes de deixar um agente instalar o SDK.
+
+A habilidade é pública; o SDK que ela aciona não é. O `agenteye-evaluator` é distribuído apenas como um artefato de release privado e, ao contrário do `agenteye`, o nome está **sem registro no PyPI público** — então um simples `pip install agenteye-evaluator` poderia puxar o pacote de um desconhecido para o serviço que lê suas transcrições de produção. Isso é um problema de cadeia de suprimentos, não um erro de digitação.
+
+A habilidade sabe disso e percorre uma escada de instalação em vez disso, parando no primeiro degrau que se aplica: o código-fonte do monorepo se você estiver dentro do repositório AgentEye, caso contrário o wheel de release privado do GitHub Releases (requer acesso), e se nenhum estiver acessível ela **para e diz para você perguntar ao seu contato na Failproof AI pelo wheel** em vez de improvisar.
+
+Portanto, se seu agente propõe um simples `pip install agenteye-evaluator` do PyPI público, isso é o sinal de que a habilidade nunca foi carregada. Pare aí e verifique se ela está instalada.
+
+---
+
+## O que você pode pedir a ela
+
+Uma rodada completa começa com uma solicitação vaga e termina com um design aprovado, não com código:
+
+```text
+você  ▸ Quero avaliações para nosso bot de suporte. Acho que às vezes ele falha.
+
+agente▸ Antes de escrever qualquer coisa: descreva uma execução que correu bem,
+        e uma que correu mal.
+
+você  ▸ Boa: ele responde pela documentação. Ruim: ele inventa coisas,
+        ou desiste e diz "entre em contato com o suporte".
+
+agente▸ Executando: agenteye --json sessions --status error --since 7d
+        Lendo 5 sessões, incluindo duas que você consideraria ruins.
+
+        Suas palavras dizem factualidade e desvio. As transcrições
+        concordam com desvio (2 de 5 terminam com encaminhamento ao suporte,
+        e está claro em model_response.content), mas factualidade
+        precisa de uma resposta de referência que seus eventos não carregam.
+
+        Então eu pontuaria três coisas:
+          - deflection      regras, barato, separa suas duas execuções
+          - tool_efficiency regras, captura o loop de retentativa em run-004
+          - groundedness    juiz LLM: cada afirmação está nos documentos recuperados?
+
+        "factuality" precisaria de resposta de referência que não temos; groundedness
+        é o mais próximo que suas transcrições podem realmente suportar.
+        OK com esses três nomes? Renomear depois divide o histórico.
+
+você  ▸ sim
+
+agente▸ Nenhum avaliador neste repositório. Devo criar um aqui, ou você
+        tem um em outro lugar?
+```
+
+A partir daí ele escreve primeiro as dimensões baseadas em regras (gratuitas, instantâneas, determinísticas), testa-as contra uma sessão real capturada, incluindo as vazias e as nunca concluídas que travam avaliadores ingênuos, e só recorre a um juiz LLM na dimensão subjetiva. Ele conhece os [limites do dispatcher](/pt-br/agenteye/evaluation-suite#configuring-the-server) — um timeout de requisição de 30s e 8 chamadas concorrentes em todo o deployment — portanto, se o juiz não couber de forma confiável, ele vai assíncrono com `JobPending` em vez de deixar seu juiz ser cancelado e repetido cinco vezes ao custo de cinco vezes mais.
+
+Depois implanta, configura as duas variáveis de ambiente do servidor e confirma com `agenteye --json evals --session-id <id>` que as pontuações realmente chegaram. As pontuações chegando é a única prova.
+
+---
+
+## O que observar
+
+- **Nomes de dimensões são quase permanentes.** As chaves de pontuação são strings arbitrárias e a plataforma rastreia tendências de tudo o que você envia, o que significa que nada downstream corrige uma escolha ruim. Renomeie depois e o histórico se divide: sessões antigas mantêm a chave antiga e a tendência se quebra. É por isso que a habilidade obtém aprovação explícita antes de escrever código — leve esse prompt a sério.
+- **Fixtures são transcrições reais de produção.** Projetar contra sessões reais significa baixá-las para o disco, e elas podem conter dados de clientes. A habilidade pergunta antes de commitá-las no git; em caso de dúvida, mantenha `fixtures/` fora do repositório e peça a cada desenvolvedor que baixe as suas próprias.
+- **O agente escreve e implanta um serviço que lê todas as transcrições.** Ele age como você, limitado pelas permissões do seu login no CLI, mas revise o avaliador como qualquer outro código que toca dados de produção.
+
+---
+
+## Próximos passos
+
+- **[Evaluation suite](/pt-br/agenteye/evaluation-suite)**: o contrato HTTP, o SDK e as variáveis de ambiente do servidor que a habilidade configura.
+- **[Evaluations](/pt-br/agenteye/evaluations)**: onde as pontuações aparecem assim que chegam.
+- **[CLI skill](/pt-br/agenteye/cli-skill)**: a habilidade irmã, para ler resultados em vez de construir o pontuador.
+- **[CLI](/pt-br/agenteye/cli)**: a referência de comandos por trás dos dados de sessão com os quais a habilidade projeta.