failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,436 @@
+---
+title: "Python SDK"
+description: "Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição ao modelo, hook e intervenção humana."
+---
+
+
+Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição ao modelo, hook e intervenção humana. O SDK Python de Observabilidade do Failproof AI registra esse rastro de dentro do seu código de agente para que você possa depurar, auditar e avaliar o que aconteceu. Use-o sempre que quiser que a Observabilidade do Failproof AI monitore seus agentes.
+
+Por baixo dos panos, o SDK grava eventos estruturados em arquivos JSONL locais, e o daemon coletor os busca e os envia para a plataforma automaticamente. Você não gerencia esses arquivos diretamente.
+
+> **Dica:** Novo na Observabilidade do Failproof AI? Esta página é a referência completa de eventos do SDK.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+---
+
+## Instalação
+
+O SDK é distribuído aos clientes como um wheel privado, e não a partir de um índice público de pacotes. O processo de onboarding cobre como obtê-lo, instalá-lo e fixar sua versão — fale com seu contato na Failproof AI se precisar de acesso.
+
+Após a instalação, confirme que está disponível:
+
+```bash
+python -c "import agenteye; print(agenteye.__version__)"
+```
+
+Prefere deixar um agente de código fazer toda a integração? A [Python SDK Agent Skill](/pt-br/agenteye/python-sdk-skill) conhece o caminho de instalação, planeja os pontos de instrumentação, os implementa e verifica se os eventos chegam corretamente.
+
+---
+
+## Início Rápido
+
+```python
+import agenteye
+
+agenteye.configure(environment="production")
+
+agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")
+
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    input={"query": "latest AI research"},
+)
+
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    output={"results": ["..."]},
+)
+
+agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
+```
+
+### Instrumentando uma chamada real
+
+Na prática, você envolve o código do seu agente existente. Envolva uma chamada ao modelo com `model_request` antes e `model_response` depois, para que os dois eventos abranjam a requisição real e a Observabilidade do Failproof AI possa associá-los:
+
+```python
+import anthropic
+import agenteye
+
+agenteye.configure(environment="production")
+client = anthropic.Anthropic()
+
+messages = [{"role": "user", "content": "Summarise today's incidents."}]
+
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6",
+    messages=messages,
+)
+
+reply = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=messages,
+)
+
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model=reply.model,
+    stop_reason=reply.stop_reason,
+    input_tokens=reply.usage.input_tokens,
+    output_tokens=reply.usage.output_tokens,
+    content=[block.model_dump() for block in reply.content],
+)
+```
+
+Envolva as chamadas de ferramenta da mesma forma com `tool_use` e `tool_result`, reutilizando um mesmo `tool_call_id` no par.
+
+Veja como esses eventos aparecem no dashboard, com código de cores por tipo e filtráveis por ambiente, agente e sessão:
+
+![O stream de Eventos ao vivo, com código de cores por tipo de evento e filtrável por ambiente, agente e sessão](/agenteye/images/events-stream.png)
+
+---
+
+## configure()
+
+```python
+agenteye.configure(
+    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
+    flush_interval=0.5,      # float, seconds between flush cycles
+    environment=None,        # str | None. Deployment environment label
+)
+```
+
+Chame uma vez antes de qualquer chamada a `event.*`. Pode ser omitido com segurança; os valores padrão funcionam imediatamente. Todos os argumentos são somente por palavra-chave; passe-os pelo nome conforme mostrado acima.
+
+Quando `base_dir` é `None` (o padrão), o SDK lê `$AGENTEYE_HOME` se estiver definido,
+caso contrário, utiliza `~/.agenteye`. Isso corresponde à resolução do próprio coletor,
+então uma única variável de ambiente `AGENTEYE_HOME` configura o spool de eventos
+compartilhado tanto para o SDK quanto para o coletor.
+
+---
+
+## Ambiente
+
+Identifique cada evento com um ambiente de implantação (`production`, `staging`, `qa`, `canary`, etc.). Defina uma vez; o SDK o anexa a cada evento automaticamente.
+
+**Opção 1: via `configure()`:**
+
+```python
+agenteye.configure(environment="production")
+```
+
+**Opção 2: via variável de ambiente:**
+
+```bash
+export AGENTEYE_ENVIRONMENT=production
+```
+
+**Prioridade:** `configure(environment=...)` prevalece sobre a variável de ambiente. Se nenhum dos dois estiver definido, o padrão é `"dev"`.
+
+O valor do ambiente aparece como um filtro de primeira classe no dashboard e é armazenado no servidor para consultas rápidas.
+
+> **Aviso:** Os valores de ambiente não devem conter uma vírgula `,` literal. Os filtros do dashboard utilizam múltipla seleção separada por vírgula na requisição (`?environment=prod,staging`), então um ambiente chamado `prod,blue` seria dividido em dois valores. Eventos com ambientes contendo vírgulas são rejeitados no momento da ingestão.
+
+---
+
+## Dados e privacidade
+
+O SDK registra apenas os campos que você passa explicitamente. Prompts, mensagens, entradas e saídas de ferramentas e conteúdo do modelo são capturados somente porque você os fornece a uma chamada `event.*`. Nada é lido do seu processo ou capturado implicitamente. Qualquer campo que você deixar sem definir é omitido do evento por completo; não é gravado em disco.
+
+Isso torna a redação uma escolha e responsabilidade sua. Se um prompt ou payload de ferramenta contiver PII ou segredos que você prefere não armazenar, remova ou mascare-os antes de passá-los ao método de evento.
+
+---
+
+## Referência de Eventos
+
+A maioria dos eventos vem em pares início/fim que compartilham um ID de correlação: `tool_use` e `tool_result` compartilham um `tool_call_id`, `hook_triggered` e `hook_completed` compartilham um `hook_id`, e `human_wait` e `human_input` compartilham um `input_id`. Emita o evento de início, execute o trabalho e, em seguida, emita o evento de fim com o mesmo ID. A Observabilidade do Failproof AI associa o par e calcula o `duration_ms` para você, portanto, você nunca passa `duration_ms` diretamente.
+
+![O gráfico de execução no estilo git de uma sessão ao lado de sua linha do tempo de eventos, reconstruído a partir dos eventos pareados, com o painel de detalhamento de ferramenta/modelo/hook](/agenteye/images/session-detail.png)
+
+Todos os métodos de evento exigem estes dois campos:
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `session_id` | `str` | Identifica a execução de agente de nível superior |
+| `agent_id` | `str` | Identifica qual agente dentro da sessão emitiu o evento |
+
+Todos os métodos também aceitam `**kwargs` arbitrários para metadados personalizados (veja [Campos Personalizados](#custom-fields)).
+
+---
+
+### `event.agent_start()`
+
+Emitido quando um agente inicia o trabalho.
+
+```python
+agenteye.event.agent_start(
+    session_id="run-001",
+    agent_id="planner",
+    goal="answer user query",   # str | None
+    parent_id=None,             # str | None - parent agent_id for nested agents
+)
+```
+
+---
+
+### `event.agent_end()`
+
+Emitido quando um agente conclui o trabalho.
+
+```python
+agenteye.event.agent_end(
+    session_id="run-001",
+    agent_id="planner",
+    outcome="success",          # str | None
+    summary="Answered query",   # str | None
+)
+```
+
+---
+
+### `event.tool_use()`
+
+Emitido quando um agente invoca uma ferramenta. Emparelhe com `tool_result`; o SDK calcula `duration_ms` automaticamente.
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",     # str, required
+    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
+    input={"query": "..."},     # dict | None
+)
+```
+
+---
+
+### `event.tool_result()`
+
+Emitido quando uma ferramenta retorna. Correlaciona com `tool_use` via `tool_call_id`.
+
+```python
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",        # must match the prior tool_use
+    output={"results": ["..."]},    # Any | None
+    error=None,                     # str | None - set if the tool raised
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.model_request()`
+
+Emitido imediatamente antes de enviar um prompt a um LLM.
+
+```python
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    messages=[                   # list[dict] | None - conversation turns
+        {"role": "user", "content": "..."},
+    ],
+    system="You are helpful.",   # Any | None - str or list of content blocks
+    tools=[                      # list[dict] | None - tool schemas offered to the model
+        {"name": "search", "input_schema": {"type": "object"}},
+    ],
+)
+```
+
+As entradas de `messages` aceitam tanto uma string simples `content` quanto `content` no estilo Anthropic com lista de blocos. Parâmetros de amostragem (`temperature`, `max_tokens`, etc.) podem ser passados como kwargs extras.
+
+---
+
+### `event.model_response()`
+
+Emitido quando o LLM retorna uma resposta.
+
+```python
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    stop_reason="end_turn",     # str | None
+    input_tokens=1024,          # int | None
+    output_tokens=256,          # int | None
+    content=[                    # Any | None - str, or list of content blocks
+        {"type": "text", "text": "..."},
+    ],
+    role="assistant",            # str | None
+)
+```
+
+`content` aceita tanto uma string simples (provedores genéricos) quanto uma lista de blocos de conteúdo no estilo Anthropic. As chamadas de ferramenta ficam dentro de `content` como blocos `{"type": "tool_use", ...}`, sem campo `tool_calls` separado.
+
+---
+
+### `event.hook_triggered()`
+
+Emitido quando um hook é acionado. Emparelhe com `hook_completed`; o SDK calcula `duration_ms` automaticamente.
+
+```python
+agenteye.event.hook_triggered(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",   # str, required
+    hook_id="hook-abc",         # str, required - correlation key
+    trigger_event="tool_use",   # str | None
+    input={"tool": "search"},   # Any | None
+)
+```
+
+---
+
+### `event.hook_completed()`
+
+Emitido quando um hook é concluído. Correlaciona com `hook_triggered` via `hook_id`.
+
+```python
+agenteye.event.hook_completed(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",
+    hook_id="hook-abc",         # must match the prior hook_triggered
+    outcome="allow",            # str | None
+    output=None,                # Any | None
+    error=None,                 # str | None
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.error()`
+
+Emitido quando ocorre um erro não tratado.
+
+```python
+agenteye.event.error(
+    session_id="run-001",
+    agent_id="planner",
+    error_type="TimeoutError",  # str, required
+    message="timed out",        # str, required
+    traceback="Traceback...",   # str | None
+)
+```
+
+---
+
+## Eventos de Humano no Processo
+
+Os eventos de humano no processo (human-in-the-loop) oferecem visibilidade sobre os momentos em que uma pessoa intervém na execução do agente (aguardando aprovação, fornecendo entrada, pausando ou parando o agente). Eles permitem medir quanto tempo os humanos levam para responder (o SDK calcula `duration_ms` automaticamente nos eventos pareados), auditar quem pausou ou interrompeu um agente, e construir fluxos de trabalho de aprovação e supervisão que aparecem no dashboard.
+
+### `event.human_wait()`
+
+Emitido quando o agente pausa a execução para aguardar que um humano forneça entrada. Emparelhe com `human_input`; o SDK calcula `duration_ms` automaticamente (quanto tempo o humano levou para responder).
+
+```python
+agenteye.event.human_wait(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
+    prompt="Do you approve this action?",        # str | None - the question shown to the human
+    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
+    reason="approval_required",                  # str | None - why the agent is waiting
+)
+```
+
+### `event.human_input()`
+
+Emitido quando um humano fornece entrada e o agente retoma a execução. Correlaciona com `human_wait` via `input_id`. O `duration_ms` é calculado automaticamente e não deve ser passado pelo chamador.
+
+```python
+agenteye.event.human_input(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",    # str, required - must match the prior human_wait
+    response="approve",    # str | None - the human's answer (free text or selected option)
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+### `event.human_pause()`
+
+Emitido quando um humano pausa ativamente o agente (por exemplo, via um controle no dashboard). O agente é suspenso, mas não encerrado.
+
+```python
+agenteye.event.human_pause(
+    session_id="run-001",
+    agent_id="planner",
+    reason="user_requested",  # str | None
+    user_id="usr_42",         # str | None - who paused the agent
+)
+```
+
+### `event.human_interrupt()`
+
+Emitido quando um humano para ativamente o agente no meio da execução. Diferentemente de `human_pause`, o trabalho do agente é encerrado em vez de suspenso.
+
+```python
+agenteye.event.human_interrupt(
+    session_id="run-001",
+    agent_id="planner",
+    reason="output_incorrect",       # str | None
+    user_id="usr_42",                # str | None - who interrupted the agent
+    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
+)
+```
+
+---
+
+## Campos Personalizados
+
+Quaisquer argumentos de palavra-chave extras são anexados ao evento após os campos padrão:
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="db_query",
+    tool_call_id="toolu_02",
+    tenant_id="acme",           # custom field
+    region="us-east-1",         # custom field
+)
+```
+
+`timestamp`, `type` e `environment` são reservados e lançam `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passados como campos personalizados. `session_id` e `agent_id` são parâmetros obrigatórios em todos os métodos de evento e não podem ser fornecidos uma segunda vez; o Python lança `TypeError` se você fizer isso. Defina o ambiente com `configure(environment=...)` (ou a variável `AGENTEYE_ENVIRONMENT`).
+
+Mantenha os payloads como JSON estruturado quando quiser consultar seus campos. Valores que o JSON não suporta nativamente — como datetimes, UUIDs, decimais, conjuntos, bytes ou objetos de modelo — são convertidos para strings para que o registro continue com segurança.
+
+---
+
+## Como os Eventos São Gravados
+
+Os eventos são armazenados em buffer no processo e descarregados em disco a cada `flush_interval` segundos (padrão: 500 ms). Cada descarga grava um arquivo JSONL:
+
+```text
+~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl
+```
+
+O coletor monitora esse diretório e faz upload dos arquivos automaticamente. Você não precisa gerenciar esses arquivos diretamente.
+
+Cada arquivo é gravado atomicamente: o SDK grava em um arquivo temporário e então o renomeia para o lugar final, de modo que o coletor nunca veja um arquivo gravado pela metade. Uma descarga final também é executada quando seu processo encerra, de forma que eventos armazenados em buffer no último intervalo não sejam perdidos. Se o coletor estiver offline, os eventos simplesmente se acumulam como arquivos em disco e são enviados assim que ele voltar.
+
+---
+
+## Próximos passos
+
+- [Stream de eventos](/pt-br/agenteye/event-stream): acompanhe esses eventos chegando ao vivo, com código de cores e filtráveis por ambiente, agente e sessão.
+- [Sessões](/pt-br/agenteye/sessions): veja como os eventos pareados reconstroem cada execução de agente como um gráfico de execução e uma linha do tempo.

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

@@ -0,0 +1,56 @@
+---
+title: "Consultas"
+description: "Faça qualquer pergunta sobre os dados do seu agente e obtenha uma resposta em segundos."
+---
+
+
+Faça qualquer pergunta sobre os dados do seu agente e obtenha uma resposta em segundos. A Observabilidade do Failproof AI oferece uma biblioteca de consultas salvas, prontas para execução, sobre seus eventos e avaliações — assim você começa a partir de um exemplo funcional em vez de um editor SQL em branco.
+
+![A biblioteca de consultas salvas: uma grade de consultas reutilizáveis, incluindo predefinições integradas e personalizadas](/agenteye/images/queries.png)
+
+*Sua biblioteca de consultas salvas em `/<org-slug>/queries`: predefinições integradas ao lado das consultas que sua equipe salvou.*
+
+## Comece por uma predefinição, não por uma página em branco
+
+Você não precisa lembrar nomes de tabelas nem escrever SQL do zero. A biblioteca abre com predefinições integradas para as perguntas mais frequentes das equipes, dispostas ao lado das consultas que sua própria equipe salvou e nomeou. Escolha uma que se aproxime do que você precisa e você já estará na maior parte do caminho até a resposta.
+
+Cada consulta salva tem escopo por organização e é compartilhada — então as consultas úteis que seus colegas criam também ficam disponíveis para você. Dê um nome e uma descrição a uma consulta uma única vez, e qualquer pessoa da sua organização poderá encontrá-la, executá-la ou fixar seus resultados em um dashboard posteriormente.
+
+Acesse em `/<org-slug>/queries`.
+
+## Ajuste e execute no compositor SQL
+
+Abra qualquer consulta e ela será carregada no compositor SQL, onde você pode ajustá-la e ver a resposta imediatamente: sem exportação, sem idas e vindas, sem esperar por outra pessoa.
+
+![O compositor de consultas SQL executando uma consulta salva, com uma barra lateral de esquema e uma grade de resultados ao vivo](/agenteye/images/query-lab.png)
+
+*O compositor SQL: sua consulta à esquerda, uma barra lateral de esquema para que você nunca precise adivinhar o nome de uma coluna, e uma grade de resultados ao vivo abaixo.*
+
+- **Uma barra lateral de esquema** exibe as tabelas analíticas e suas colunas, para que você possa moldar uma consulta sem precisar caçar nomes de campos.
+- **Uma grade de resultados ao vivo** retorna as linhas assim que você executa, permitindo que você itere em segundos em vez de ficar tentando adivinhar.
+- **Somente leitura por design.** As consultas são executadas contra seu armazenamento de eventos e validadas no servidor: apenas instruções `SELECT` e `WITH` são permitidas, com um tempo limite de execução e um limite de linhas. Uma consulta exploratória nunca pode modificar seus dados, e uma consulta fora de controle é interrompida automaticamente para você.
+
+Gostou do resultado? Salve-o de volta na biblioteca para que toda a equipe herde, ou fixe a saída em um dashboard como um tile de linha, barra, área ou pizza.
+
+## Execute a partir do terminal ou deixe o assistente escrevê-las
+
+As mesmas consultas salvas acompanham você onde quer que trabalhe:
+
+- **Pelo terminal.** O CLI `agenteye` lista, executa e salva as mesmas consultas, para que você possa inserir um resultado em um script, integrá-lo ao CI ou passá-lo para um agente de código.
+
+```bash
+agenteye query list                 # as mesmas consultas salvas, pelo seu terminal
+agenteye query run errs --arg prod  # execute uma e imprima as linhas (adicione --json para redirecionar)
+```
+
+  Consulte [CLI e agentes](/pt-br/agenteye/cli-and-agents) para o conjunto completo de comandos.
+
+- **Pelo assistente de IA.** Não tem certeza de como formular o SQL? Pergunte ao [assistente de IA](/pt-br/agenteye/assistant) no dashboard em linguagem natural e ele rascunhará a consulta e a salvará na sua biblioteca.
+
+A execução de uma consulta salva é controlada pela permissão `queries:run`, separada das permissões para criar ou excluir consultas — assim você pode conceder acesso de leitura sem permitir que todos reescrevam a biblioteca.
+
+## Relacionados
+
+- [Dashboards](/pt-br/agenteye/dashboards): fixe resultados de consultas em gráficos compartilhados para toda a organização.
+- [Assistente de IA](/pt-br/agenteye/assistant): faça perguntas em linguagem natural e obtenha uma consulta como resposta.
+- [CLI e agentes](/pt-br/agenteye/cli-and-agents): execute e salve as mesmas consultas pelo seu terminal.

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

@@ -0,0 +1,68 @@
+---
+title: "Segurança"
+description: "O Failproof AI Observability foi projetado para ficar próximo aos seus agentes em produção, o que significa que ele vê seus prompts, entradas de ferramentas e saídas."
+---
+
+
+O Failproof AI Observability foi projetado para ficar próximo aos seus agentes em produção, o que significa que ele vê seus prompts, entradas de ferramentas e saídas. Esta página explica como esses dados são mantidos isolados, controlados e nas suas mãos. Se você está avaliando o Failproof AI Observability para uma revisão de segurança, comece por aqui.
+
+---
+
+## Seus dados ficam no seu ambiente
+
+O Failproof AI Observability é auto-hospedado. Eventos, prompts, respostas do modelo e análises são armazenados nos seus próprios bancos de dados, no seu próprio ambiente. Nada é enviado para um SaaS de terceiros para armazenamento, e seus dados permanecem na sua própria conta de nuvem.
+
+---
+
+## Isolamento de tenant
+
+Uma instância do Failproof AI Observability pode hospedar várias organizações, e cada uma é isolada na camada de armazenamento — aplicado pelo banco de dados, não apenas pela interface:
+
+- Os dados operacionais de uma organização (usuários, chaves, dashboards, consultas salvas) são restritos àquela org, e leituras entre organizações são bloqueadas pelo próprio banco de dados.
+- Todo evento ingerido é marcado com a organização proprietária, de modo que os eventos de uma organização nunca podem ser lidos por outra.
+
+Cada rota de dashboard é delimitada por um slug de org (`/<org-slug>/…`).
+
+---
+
+## Login
+
+O Failproof AI Observability utiliza login sem senha, baseado em e-mail. Não há senha para ser furtada ou vazada. Um usuário solicita um código de uso único (ou um magic link de clique único), que é enviado por e-mail e expira rapidamente. O login é controlado por uma **lista de permissões**: somente endereços de e-mail (ou domínios) que você autorizar podem se autenticar.
+
+![A tela de login do Failproof AI Observability, que envia um código de uso único para seu e-mail](/agenteye/images/login.png)
+
+---
+
+## Acesso restrito com chaves de API
+
+Cada cliente se autentica com uma chave de API que carrega permissões granulares e de menor privilégio. Um coletor precisa apenas de `events:add`; uma chave de dashboard ou assistente pode ser somente leitura; ações destrutivas (exclusão, regeneração) são concessões separadas que você escolhe incluir.
+
+![A página de chaves de API: as permissões de cada chave, com código de cores por escopo de leitura, escrita e destrutivo](/agenteye/images/api-keys.png)
+
+Mantenha a chave de bootstrap de administrador para a configuração inicial e emita chaves restritas para todo o resto. Consulte [Chaves de API](/pt-br/agenteye/api-keys).
+
+---
+
+## Um assistente somente leitura com aprovação obrigatória
+
+O [assistente de IA](/pt-br/agenteye/assistant) integrado ao dashboard responde perguntas sobre seus dados, mas é restrito por design:
+
+- É **somente leitura por padrão**: o SQL que ele executa passa por um guard que permite apenas consultas `SELECT`/`WITH`, instrução única, com limite de linhas.
+- Tudo que ele cria (uma consulta salva, um dashboard) **requer aprovação**: você revisa e aprova cada escrita antes que ela aconteça.
+- Ele **nunca pode excluir**.
+
+Assim, um colega de equipe pode perguntar "quais agentes tiveram mais erros esta semana?" e agir com base na resposta, sem que o assistente consiga alterar ou remover seus dados por conta própria.
+
+---
+
+## Em trânsito
+
+Todo o tráfego é transmitido via HTTPS. Você encerra o TLS com seus próprios certificados, de modo que o tráfego do coletor para o servidor e do navegador para o servidor é criptografado em trânsito.
+
+---
+
+## Próximos passos
+
+- [Visão geral](/pt-br/agenteye/overview): como o Failproof AI Observability se encaixa.
+- [Chaves de API](/pt-br/agenteye/api-keys): restrinja o acesso para o coletor, dashboard e assistente.
+- [Observabilidade](/pt-br/agenteye/observability): o que o Failproof AI Observability captura dos seus agentes.

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

@@ -0,0 +1,56 @@
+---
+title: "Sessões e Grafo de Execução"
+description: "Todos os eventos de uma execução consolidados em uma linha legível e exibidos como um grafo de execução no estilo git, que você lê em segundos."
+---
+
+Chega de adivinhar por que uma execução falhou. A Observabilidade do Failproof AI consolida todos os eventos de uma execução em uma única linha legível e, em seguida, desenha toda a execução como uma imagem no estilo git que você pode interpretar em segundos — assim você vê exatamente o que seu agente fez, passo a passo.
+
+![A lista de Sessões: uma linha por execução, entre ambientes e agentes, com indicadores de status e emblemas de pontuação de avaliação](/agenteye/images/sessions-list.png)
+
+*Uma linha por execução: o indicador de status mostra como a execução terminou de relance, e um emblema de pontuação aparece assim que um avaliador é conectado.*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Rastreamento de agentes: acompanhe uma única execução passo a passo, do objetivo às ferramentas até a resposta final.*
+
+---
+
+## Veja todas as execuções de relance
+
+O rastro bruto de eventos é a fonte da verdade de cada etapa, mas quando você tem milhares de etapas distribuídas em dezenas de execuções, o que você precisa é da execução, não da etapa. A página de Sessões consolida todos os eventos de uma execução em uma única linha, transformando um dia inteiro de atividade em uma lista fácil de percorrer, em vez de um fluxo interminável de dados.
+
+Cada linha carrega um indicador de status, de modo que uma execução com falha se destaca de uma saudável antes mesmo de você clicar em qualquer coisa. Filtre por intervalo de datas, ambiente, agente ou sessão para ir de "tudo" até "a execução que me interessa" em alguns cliques.
+
+Quando você conectar um avaliador, cada execução concluída recebe uma pontuação automaticamente, e a pontuação mais recente aparece na linha como um emblema. Você pode filtrar por qualquer faixa de pontuação — então "mostre-me todas as execuções de produção com pontuação baixa desta semana" vira um filtro, não uma revisão manual. Enquanto você não configurar um avaliador, as sessões continuam capturando a execução completa; elas simplesmente ainda não exibem uma pontuação.
+
+---
+
+## Leia toda a execução como uma imagem
+
+![O grafo de execução no estilo git de uma sessão ao lado da linha do tempo de eventos, com o painel de detalhamento de ferramentas, modelos e hooks](/agenteye/images/session-detail.png)
+
+*O grafo de execução (à esquerda) fica ao lado da linha do tempo de eventos; o painel direito detalha as ferramentas, modelos, hooks e o consumo de tokens da execução.*
+
+Clique em qualquer sessão para abrir o grafo de execução: uma visualização no estilo git de como agentes, ferramentas, hooks e chamadas de modelo se desenrolaram ao longo do tempo. Sub-agentes paralelos se ramificam em suas próprias trilhas, então você consegue ver quais trabalhos rodaram simultaneamente, qual sub-agente travou e onde a execução saiu dos trilhos — sem precisar remontar a cena mentalmente a partir de um muro de logs.
+
+O painel direito oferece o detalhamento por execução: quais ferramentas e modelos rodaram, quais hooks foram disparados e quanto a execução consumiu em tokens. É a resposta para "por que essa execução custou tanto?" ou "qual ferramenta está lenta?" — ali mesmo, ao lado do grafo que a gerou.
+
+Eventos individuais são endereçáveis, então você pode passar para alguém um link para um momento específico em vez de dizer "a sessão, lá pelo terço final". Copie o link de qualquer evento, ou siga um link de uma descoberta de [auditoria](/pt-br/agenteye/audits) ou de um erro, e a sessão abre com aquele evento selecionado e na posição certa. Isso funciona mesmo em execuções muito longas: a linha do tempo carrega uma janela delimitada para poupar seu navegador, e um link que aponta para além dessa janela ainda encontra o evento em vez de te jogar no início. Se o evento tiver ultrapassado o período de retenção, a página informa isso em vez de silenciosamente não selecionar nada.
+
+---
+
+## Onde encontrar
+
+Cada página do dashboard é escopada à sua organização (`/<org-slug>/…`). Sessões fica em **Observe** na barra lateral esquerda, ao lado de Eventos, com os filtros de intervalo de datas, ambiente, agente e sessão no topo da lista. Cada linha está a um clique do seu grafo de execução completo.
+
+Para ativar os emblemas de pontuação e a filtragem por faixa de pontuação, conecte um avaliador: consulte [Avaliações](/pt-br/agenteye/evaluations).
+
+---
+
+## Relacionados
+
+- [Fluxo de eventos](/pt-br/agenteye/event-stream): o rastro bruto por etapa a partir do qual cada sessão é consolidada.
+- [Avaliações](/pt-br/agenteye/evaluations): conecte um avaliador para que cada execução receba um emblema de pontuação pelo qual você pode filtrar.
+- [Telemetria](/pt-br/agenteye/telemetry): como as execuções chegam do seu agente até essas sessões.