@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/pt-BR/observability.md

@@ -0,0 +1,294 @@
+---
+title: "Observabilidade"
+description: "Rastreamentos de agentes, avaliações, feedback, experimentos A/B e painel integrado, tudo sem configuração."
+---
+
+# Observabilidade do agente
+
+Todo aplicativo nativo do agente obtém capacidade de observação pronta para uso. Traces, avaliações automatizadas, feedback do usuário e experimentos A/B funcionam sem configuração: todos os dados residem no próprio banco de dados SQL do aplicativo.
+
+Esta página aborda métricas de _qualidade do agente_: rastreamentos, custos, avaliações e feedback armazenados em seu banco de dados. Para análises de _produto_ (eventos do seu aplicativo fluindo para PostHog/Mixpanel/Amplitude), consulte [Tracking](/docs/tracking).
+
+## Três coisas chamadas "avaliações"/"observabilidade" — o que eu quero? {#which}
+
+Essas três páginas são fáceis de confundir. Escolha pela pergunta que você está fazendo:
+
+| Página                                                          | A pergunta que ele responde                         | Quando é executado                                   | Preocupação    |
+| --------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------- | -------------- |
+| **Avaliações de observabilidade** (esta página, a guia _Evals_) | "Como foi minha produção real?"                     | Passivo, após cada execução (amostragem do juiz LLM) | Qualidade      |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)                   | "O agente faz a coisa certa nesta entrada fixa?"    | Ativo, determinístico, um CI/deploy gate             | Qualidade      |
+| **[Observational Memory](/docs/observational-memory)**          | "Esse longo tópico está barato e dentro da janela?" | Compactação de fundo em threads longos               | Custo/contexto |
+
+A observabilidade e o CI Eval Gate pontuam _qualidade_, mas de extremos opostos - pontuação post-hoc passiva de tráfego real versus verificações ativas de aprovação/reprovação em entradas fixas. A memória observacional não está relacionada à qualidade; trata-se do custo do token e da pressão da janela de contexto.
+
+## O que é capturado automaticamente {#captured}
+
+Quando um usuário envia uma mensagem, a estrutura registra automaticamente:
+
+- **Uso de token** — entrada, saída, leitura de cache, gravação de cache
+- **Custo** — calculado a partir de contagens de tokens e preços de modelo
+- **Latência** — duração total e tempo por chamada de ferramenta
+- **Chamadas de ferramenta** — quais actions foram invocados, status de sucesso/erro, duração
+- **Avaliações automatizadas** — 5 índices de qualidade calculados após cada execução
+
+Não são necessárias alterações de código. A instrumentação se conecta ao `production-agent.ts` de forma transparente.
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## O painel {#dashboard}
+
+Adicione o painel a qualquer modelo com uma única rota:
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+Todos os dados têm como escopo o usuário conectado; não há visualização de administrador entre usuários hoje.
+
+O painel possui 5 guias:
+
+| Guia             | O que mostra                                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Visão geral**  | Principais métricas: execuções, custo, latência, taxa de sucesso da ferramenta, satisfação, pontuação de avaliação |
+| **Conversas**    | Lista de rastreamento com detalhamento de períodos individuais (agent_run, llm_call, tool_call)                    |
+| **Avaliações**   | Pontuações de avaliação automatizadas por critérios, tendências ao longo do tempo                                  |
+| **Experiências** | Lista de testes A/B com selos de status, resultados de variantes com intervalos de confiança                       |
+| **Comentários**  | Stream de aprovação/rejeição, detalhamento de categorias, pontuações de frustração                                 |
+
+## Feedback do usuário {#feedback}
+
+### Feedback explícito
+
+Os botões de polegar para cima/para baixo são renderizados em linha em cada mensagem do agente no chat UI. O polegar para baixo abre um popover de categoria (impreciso, não útil, ferramenta errada, muito lento). Isso é conectado ao `AssistantChat.tsx` automaticamente.
+
+### Feedback implícito (índice de frustração)
+
+A estrutura calcula um Índice de Frustração (0-100) a partir de sinais de conversa:
+
+| Sinal                    | Peso | O que detecta                           |
+| ------------------------ | ---- | --------------------------------------- |
+| Reformulação             | 30%  | O usuário repete mensagens semelhantes  |
+| Padrões de repetição     | 20%  | "Tente novamente", "não, está errado"   |
+| Abandono                 | 20%  | A sessão termina logo após a resposta   |
+| Sentimento               | 15%  | Padrões de linguagem negativos          |
+| Tendência de comprimento | 15%  | Diminuição do comprimento das mensagens |
+
+Interpretação da pontuação: 0-20 = saudável, 20-40 = atrito, 40-60 = insatisfeito, 60+ = sessão interrompida.
+
+## Avaliações automatizadas {#evals}
+
+Cinco marcadores determinísticos executados após cada execução do agente:
+
+| Critérios           | O que mede                                                              | Intervalo de pontuação |
+| ------------------- | ----------------------------------------------------------------------- | ---------------------- |
+| `tool_success_rate` | % de chamadas de ferramenta sem erros                                   | 0-1                    |
+| `step_efficiency`   | Penaliza iterações LLM excessivas para execuções com uso de ferramentas | 0-1                    |
+| `latency_score`     | Normalizado em relação à linha de base de 10s/ferramenta                | 0-1                    |
+| `cost_efficiency`   | Normalizado em relação à linha de base de custos                        | 0-1                    |
+| `error_recovery`    | O agente se recuperou dos erros da ferramenta?                          | 0 ou 1                 |
+
+### LLM-como juiz (opcional)
+
+Ative a avaliação baseada em amostra de LLM configurando `evalSampleRate`:
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+Os critérios personalizados usam rubricas de linguagem natural:
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## Experimentos A/B {#experiments}
+
+Teste diferentes modelos, temperaturas ou configurações de agentes:
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+Use os identificadores de modelo reais que seu mecanismo aceita no lugar de `<your-model-id>` / `<other-model-id>` (os nomes dos modelos mudam frequentemente - verifique seu fornecedor/mecanismo para obter os IDs atuais). O loop do agente resolve automaticamente a variante do usuário e aplica a substituição de configuração. A atribuição usa hashing consistente – o mesmo usuário sempre obtém a mesma variante.
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Configuração {#config}
+
+Todas as configurações são armazenadas na chave `observability-config`:
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## Extremidades API {#api}
+
+Todos montados automaticamente em `/_agent-native/observability/`:
+
+| Método | Caminho                    | Propósito                                      |
+| ------ | -------------------------- | ---------------------------------------------- |
+| GET    | `/`                        | Estatísticas gerais                            |
+| GET    | `/traces`                  | Listar resumos de rastreamento                 |
+| GET    | `/traces/:runId`           | Detalhes do rastreamento (resumo + intervalos) |
+| GET    | `/traces/:runId/evals`     | Avaliações para uma corrida                    |
+| POST   | `/feedback`                | Enviar comentários                             |
+| GET    | `/feedback`                | Listar comentários                             |
+| GET    | `/feedback/stats`          | Agregação de feedback                          |
+| GET    | `/satisfaction`            | Pontuações de satisfação                       |
+| GET    | `/evals/stats`             | Estatísticas de avaliação                      |
+| POST   | `/experiments`             | Criar experimento                              |
+| GET    | `/experiments`             | Listar experimentos                            |
+| GET    | `/experiments/:id`         | Obter detalhes do experimento                  |
+| PUT    | `/experiments/:id`         | Atualizar experimento                          |
+| POST   | `/experiments/:id/results` | Calcular resultados                            |
+| GET    | `/experiments/:id/results` | Obtenha resultados                             |
+
+Todos os endpoints suportam parâmetros de consulta `?since=N` (carimbo de data/hora ms) e `?limit=N`.
+
+## Exportar para plataformas externas {#export}
+
+Envie rastreamentos para Langfuse, Datadog, Grafana ou qualquer back-end compatível com OTel:
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+A estrutura emite extensões de convenção semântica `gen_ai.*` compatíveis com a especificação OpenTelemetry GenAI.
+
+## Extensões do OpenTelemetry {#otel}
+
+Separado da configuração `exporters` acima (que envia os rastreamentos internos para um endpoint OTLP), o loop do agente também pode emitir **espaços OpenTelemetry ao vivo** para cada execução, chamada de modelo e chamada de ferramenta. Assim, um host que já executa um coletor OTel vê a atividade do agente junto com o restante de seus rastreamentos distribuídos.
+
+Essa camada é **opcional e autônoma por padrão**:
+
+- `@opentelemetry/api` é uma **dependência opcional**. Se não estiver instalado, os ajudantes degradam-se para operações autônomas silenciosas – nada aqui é lançado no loop do agente.
+- Mesmo quando o pacote API _está_ presente, ele envia um rastreador não operacional padrão. Os spans só se tornam reais quando o **host registra um `TracerProvider`** (via `@opentelemetry/sdk-node` ou similar). A estrutura deliberadamente **não** depende dos pacotes pesados SDK/exportador nem registra um provedor em si — a instrumentação é ativada pelo aplicativo de incorporação.
+
+Portanto, o custo quando você não conecta o OTel é algumas leituras de propriedades em cache por chamada. Para ativá-lo, instale o pacote API mais seu SDK e registre um provedor na inicialização do servidor da mesma forma que faria para qualquer outro serviço Node.
+
+O loop do agente emite três tipos de span:
+
+| Período     | Quando                         | Atributos                                                         |
+| ----------- | ------------------------------ | ----------------------------------------------------------------- |
+| `agent.run` | uma vez por execução do agente | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | uma vez por invocação de ação  | `tool.name`, mais status de sucesso/erro                          |
+| `llm.call`  | por chamada de modelo          | tempo + OK/status de erro                                         |
+
+Os trechos são concluídos com o status OK/ERROR e registram a mensagem de erro em caso de falha. Os valores de atributos zero/sentinel são removidos para que os trechos não fiquem cheios de ruído. Essa camada OTel é puramente aditiva às tabelas internas `agent_trace_spans`/`agent_trace_summaries` que alimentam o painel acima — ambas são produzidas a partir dos mesmos eventos de execução.
+
+## Relatório de erros (Sentry) {#sentry}
+
+Erros do lado do servidor que escapam dos manipuladores de rota Nitro são relatados ao Sentry quando um DSN é configurado. Sem ele, o SDK silenciosamente não funciona, então é seguro deixar os env vars indefinidos no dev. Os eventos do navegador e do servidor podem ir para o mesmo projeto Sentry; divida-os em projetos separados somente quando desejar separação operacional para propriedade, volume, cotas ou roteamento de alertas.
+
+| Superfície         | SDK               | Var ambiente                                                  | Notas                                                                          |
+| ------------------ | ----------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Navegador / SPA    | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`, `SENTRY_CLIENT_DSN` ou `SENTRY_DSN` | Captura erros não tratados e trilhas de mudança de rota no cliente.            |
+| Servidor Nitro     | `@sentry/node`    | `SENTRY_SERVER_DSN` ou `SENTRY_DSN`                           | Captura respostas 5xx e erros de ciclo de vida Nitro. Usuário por solicitação. |
+| `agent-native` CLI | `@sentry/node`    | _hardcoded_                                                   | Relatórios de falhas do binário CLI publicado; não configurável pelo usuário.  |
+
+### Configuração do lado do servidor {#sentry-config}
+
+Defina `SENTRY_SERVER_DSN` ou `SENTRY_DSN` compartilhado no ambiente de implantação (painel Netlify, segredos Cloudflare, etc.). A estrutura monta automaticamente um plugin Nitro que:
+
+1. Chama `Sentry.init` uma vez na inicialização (idempotente — seguro para chamar de vários plug-ins).
+2. Resolve o usuário via `getSession(event)` em cada solicitação API/framework e anexa `id`/`email`/`username` mais uma tag `orgId` ao escopo de isolamento por solicitação de Sentry. Os caminhos de ativos estáticos são ignorados para evitar ocorrências extras no banco de dados.
+3. Captura cada rota de estrutura 5xx com tags pesquisáveis `route`, `method` e `userAgent`.
+
+Botões opcionais:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (float `0`–`1`) — ative o rastreamento de desempenho. O padrão é `0` (somente erros). Valores inválidos são fixados em `0`.
+- `AGENT_NATIVE_RELEASE` — substitui a tag `release`. O padrão é `agent-native-server@<core-version>`.
+
+### Modelos
+
+Cada modelo herda isso automaticamente — não há nada para importar. Para aplicativos SSR, o servidor injeta um pequeno script de configuração do navegador quando `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN` ou `SENTRY_DSN` compartilhado está disponível em tempo de execução, portanto, a captura do navegador não está limitada ao ambiente de tempo de construção Vite. Modelos que desejam comportamento personalizado (tags extras, DSN diferente por modelo, Sentry desabilitado) podem ser substituídos exportando seu próprio plugin de `server/plugins/sentry.ts`:
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+O DSN codificado do CLI é intencional - o binário publicado precisa telefonar para falhas iniciais, independentemente do ambiente que o executa. O módulo do servidor nunca codifica um DSN porque ele é executado dentro dos ambientes do cliente, onde os operadores decidem se os erros devem chegar ao Sentry.
+
+### Privacidade e PII {#privacy}
+
+O servidor e o CLI inicializam com `sendDefaultPii: false` e um gancho `beforeSend` que remove:
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (coletado automaticamente sem consentimento)
+- `contexts.runtime_env` (instantâneo do ambiente do processo)
+- Qualquer evento cujo tipo de exceção de nível superior seja `ValidationError` (tratado como rejeição esperada de entrada do usuário, não como um bug).
+
+Os campos de identidade definidos explicitamente por meio de `setUser({ id, email, username })` são preservados.
+
+## O que vem a seguir
+
+- [**Tracking**](/docs/tracking) — análise de produtos (PostHog, Mixpanel, Amplitude) para os eventos do seu aplicativo
+- [**Actions**](/docs/actions) — as operações que aparecem como chamadas de ferramenta em rastreamentos
+- [**Security**](/docs/security) — escopo de dados e manipulação de credenciais

package/docs/content/locales/pt-BR/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "Memória Observacional"
+description: "Compactação de três camadas em segundo plano (brutos recentes → observações → reflexões) que mantém longos threads de agente baratos e estáveis no cache de prompt sem tocar em conversas curtas."
+---
+
+# Memória Observacional
+
+Um thread de agente de longa duração acumula uma enorme transcrição: cada mensagem, cada chamada de ferramenta, cada resultado. Repetir toda a história no modelo em cada turno é caro e eventualmente acaba com a janela de contexto. A **Memória Observacional (OM)** compacta a parte mais antiga de um thread longo em um resumo datado e em camadas para que o modelo ainda saiba o que aconteceu (por apenas uma fração do custo do token), enquanto as curvas mais recentes permanecem textuais.
+
+OM é totalmente automático e com escopo definido pelo proprietário. **Threads curtos não são afetados**: até que um thread ultrapasse o primeiro limite de compactação, o OM é autônomo e o contexto é, byte por byte, o que seria sem ele.
+
+## Os três níveis {#tiers}
+
+OM representa um fio longo em três camadas, do mais destilado ao mais recente:
+
+| Nível                         | O que é                                                                                                                     |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Reflexões**                 | Nível mais alto, condensado do registro de observação quando ele crescer. O resumo do arco longo.                           |
+| **Observações**               | Entradas densas e datadas que reúnem uma série de mensagens brutas em um registro compacto do que aconteceu.                |
+| **Mensagens brutas recentes** | Os últimos N turnos são mantidos **literalmente** — nunca dobrados — para que o agente sempre veja o contexto mais recente. |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+Em cada turno, o lado de leitura os reúne em um único bloco `[Observational Memory]` autodenominado que substitui o prefixo bruto mais antigo, mantém a janela bruta recente intacta e diz ao modelo para tratar o registro compactado como oficial (não refaça o trabalho concluído, confie nas decisões, nomes, datas e status registrados).
+
+## Como a compactação é executada {#compaction}
+
+Duas passagens são executadas como uma etapa de **disparar e esquecer, melhor esforço** _após_ uma curva limpa, para que nunca adicionem latência à resposta visível do usuário e qualquer falha seja engolida:
+
+1. **Observador** — quando as mensagens _não observadas_ de um thread excedem o limite do token de observação, ele as agrupa em uma única entrada de observação densa.
+2. **Refletor** — quando o próprio registro de observação persistente excede o limite do token de reflexão, condensa as observações em uma reflexão de nível superior.
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Ambos passam no modo autônomo abaixo de seus limites, portanto, chamar o compactador após cada curva é barato. Como o OM substitui o prefixo bruto volátil por texto compactado estável, ele também mantém o prompt **cache-stable** em voltas de um thread longo.
+
+Os dados do OM residem no próprio banco de dados SQL do aplicativo, com escopo definido para o proprietário (e organização, quando presente) — o mesmo modelo de escopo do restante da estrutura. Ele nunca é compartilhado entre os usuários.
+
+## Configuração {#config}
+
+Os padrões são conservadores. Um operador pode discar a compactação no momento da implantação com variáveis ​​de ambiente `AGENT_NATIVE_OM_*` (não é necessária a reimplantação do código do aplicativo); um valor inválido ou ausente sempre retorna ao padrão nomeado.
+
+| Var ambiente                                  | Padrão  | O que ele controla                                                                               |
+| --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000` | Tokens de mensagens não observadas que acionam o Observador para agrupá-los em uma observação.   |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000` | Tokens de registro de observação que fazem com que o Refletor se condense em um reflexo.         |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`    | Quantas das mensagens mais recentes permanecem textuais (nunca transformadas em uma observação). |
+
+Os limites de saída do Observador e do Refletor (4.000/2.000 tokens) evitam que uma única passagem de compactação estoure o orçamento; eles podem ser ajustados no código via `resolveObservationalMemoryConfig({ ... })`, mas não expostos ao ambiente.
+
+> [!TIP]
+> Reduza os limites para compactar mais cedo (threads longos mais baratos, um pouco mais de resumo); eleve-os para manter mais histórico bruto no contexto antes de compactar. Defina `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` mais alto se seus fluxos de trabalho precisarem de uma cauda literal mais longa.
+
+## Quando entra em ação {#when}
+
+OM apenas altera o comportamento de threads longos o suficiente para produzir pelo menos uma observação ou reflexão. Concretamente:
+
+- Um tópico novo ou curto: nenhuma entrada OM ainda → o contexto é a transcrição simples, inalterada.
+- Um thread longo que ultrapassou o limite de observação: o prefixo mais antigo é substituído pelo bloco compactado `[Observational Memory]`, a cauda bruta recente permanece literal e o uso de token cai substancialmente.
+
+A injeção é de melhor esforço e segura nos limites - se um ponto de corte seguro não puder ser encontrado (por exemplo, um par de uso/resultado de ferramenta pendente fica na borda da janela), o OM injeta o bloco de memória _aditivamente_ sem cortar, em vez de correr o risco de descartar um resultado de ferramenta pendente.
+
+## Relacionado
+
+- [**Using Your Agent**](/docs/using-your-agent) — o ciclo diário de trabalho com o agente acoplado ao seu aplicativo.
+- [**Observability**](/docs/observability) — métricas de token e custo por execução, onde as economias do OM aparecem.
+- [**Custom Agents & Teams**](/docs/agent-teams) — longas execuções de subagentes se beneficiam da mesma compactação.

package/docs/content/locales/pt-BR/onboarding.md

@@ -0,0 +1,216 @@
+---
+title: "Integração e chaves API"
+description: "Lista de verificação de configuração para configuração inicial — chaves API, OAuth e conexões de provedor"
+---
+
+# Integração
+
+Ao abrir pela primeira vez um aplicativo criado na estrutura nativa do agente, você verá um
+**Lista de verificação de configuração** na barra lateral do agente. Ele mantém a configuração da primeira execução próxima
+para o chat do agente: conecte um mecanismo de IA, opcionalmente aponte o aplicativo para compartilhado
+infraestrutura e adicione provedores somente quando precisar deles.
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## Para usuários finais
+
+### O que você verá
+
+- Um painel de **Configuração** acima do chat do agente com uma lista de verificação como "Conectar uma IA
+  mecanismo", "Entrega de e-mail", etc.
+- Um contador na parte superior (por exemplo, "1 de 4") mostra quantas etapas estão prontas.
+- A etapa atual é expandida; as etapas concluídas mostram uma marca verde e permanecem
+  legíveis se você abri-los.
+- As etapas obrigatórias mostram uma pequena pílula vermelha **obrigatória**. O painel permanece visível
+  até que todas as etapas necessárias sejam concluídas.
+- Depois que tudo o que for necessário for feito, o painel se ocultará automaticamente.
+- O painel inteiro pode ser recolhido com a divisa no canto superior direito ou
+  oculto totalmente com **Ocultar configuração** na parte inferior.
+
+### Como concluir cada etapa
+
+As etapas oferecem um ou mais **métodos** — diferentes maneiras de satisfazer o mesmo
+requisito. O caminho principal é mostrado primeiro; caminhos secundários são mantidos compactos
+por trás de um seletor ou divulgação quando uma etapa tem vários provedores equivalentes.
+
+- **Conecte um serviço (um clique)** — por exemplo, _Conecte Builder_ para o gerenciado
+  Portal de IA. Clique no botão, uma janela se abre, você faz login, a janela fecha,
+  e a etapa será marcada como concluída. Não há chaves para copiar.
+- **Cole uma chave API ou preencha um formulário** — por exemplo, escolha um provedor LLM, banco de dados,
+  Provedor OAuth ou provedor de e-mail, cole os valores e clique em **Salvar**.
+  Os campos secretos usam uma entrada de senha para que o valor não seja mostrado na tela. Salvo
+  os valores vão para seu `.env` local (ou configurações do espaço de trabalho) — consulte
+  [Security](/docs/security) para onde moram.
+- **Abra um link** — algumas etapas apontam para uma página de login ou documentos. Clique
+  **Continue** e finalize o fluxo na nova guia.
+- **Pergunte ao agente** — algumas etapas oferecem a opção "Deixe o agente configurar".
+  Clique nele e o agente atende no chat, orientando você em qualquer
+  configuração externa (criação de credenciais OAuth, etc.).
+
+### As etapas integradas que você normalmente verá
+
+- **Conecte um mecanismo de IA** (obrigatório) — a única etapa obrigatória. Conectar
+  Builder para um gateway gerenciado com um clique ou abra a chave do provedor secundário
+  selecione e cole sua própria chave LLM.
+- **Banco de dados** (opcional) — defina `DATABASE_URL` quando quiser usar um
+  Sequência de conexão do banco de dados SQL.
+- **Autenticação** (opcional) — contas de e-mail/senha integradas funcionam por
+  padrão. Adicione OAuth ou login com token de acesso somente quando desejar esses caminhos.
+- **Entrega de e-mail** (opcional) — útil antes da implantação para redefinições de senha,
+  convites de equipe e notificações de compartilhamento. Use o provedor que você já usa;
+  o desenvolvimento local pode funcionar sem ele.
+
+Os modelos podem adicionar suas próprias etapas acima delas - por exemplo, um modelo CRM pode
+adicionar "Conectar Gmail", um modelo de documentos pode adicionar "Escolha um espaço de trabalho padrão". Veja
+[Authentication](/docs/authentication) para detalhes de configuração de login.
+
+### Voltando à lista de verificação
+
+Se você clicar em **Ocultar configuração**, o painel desaparecerá dessa sessão do navegador.
+As etapas necessárias que ainda não foram concluídas aparecerão novamente no próximo carregamento. Uma vez
+tudo o que é necessário é feito, o painel é ocultado automaticamente para sempre — não há nada
+falta fazer.
+
+## Para desenvolvedores
+
+Se você estiver criando um modelo, registre as etapas de integração para que elas apareçam
+lista de verificação da barra lateral do usuário. A estrutura lida com renderização, conclusão
+rastreamento e demissão — basta declarar qual é a etapa e como ela é
+satisfeito.
+
+O sistema é **montado automaticamente**. Os modelos não precisam conectar nada para serem obtidos
+as quatro etapas integradas (LLM, banco de dados, autenticação, e-mail). Para adicionar aplicativos específicos
+etapas (Gmail, Slack, Notion, etc.), chame `registerOnboardingStep()` de um
+plug-in do servidor.
+
+### Rotas montadas automaticamente
+
+Todas as rotas estão sob `/_agent-native/onboarding/`:
+
+| Rota                                                | Propósito                              |
+| --------------------------------------------------- | -------------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | Listar etapas com status de conclusão  |
+| `POST /_agent-native/onboarding/steps/:id/complete` | Marcar etapa concluída (substituir)    |
+| `POST /_agent-native/onboarding/dismiss`            | Dispensar o banner de integração       |
+| `POST /_agent-native/onboarding/reopen`             | Limpar dispensa (reexibir painel)      |
+| `GET /_agent-native/onboarding/dismissed`           | Ler dispensa + sinalizador allComplete |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### Adicionando uma etapa de um modelo
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### Verificando conexões do espaço de trabalho na integração
+
+Ao criar modelos que interagem com serviços externos (como Slack, Google Workspace, GitHub ou HubSpot), verifique se o workspace já se conectou e concedeu a conexão desse provedor ao seu aplicativo. Isso evita que os usuários tenham que duplicar credenciais (como chaves API ou tokens de atualização) em suas variáveis de ambiente locais quando existe uma conexão gerenciada central.
+
+Você pode verificar a disponibilidade da conexão no retorno de chamada `isComplete` usando o catálogo de conexão APIs:
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+Consulte a documentação do [Workspace Connections](/docs/workspace-connections) para obter a lista completa de métodos de catálogo do provedor de conexão.
+
+### Tipos de métodos
+
+| Gentil             | Carga útil                                            | Usar para                                                    |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------ |
+| `link`             | `{ url, external? }`                                  | Enviar o usuário para um fluxo OAuth ou página de documentos |
+| `form`             | `{ fields, writeScope? }`                             | Colete variáveis de ambiente (chaves, segredos, URLs)        |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra)                       |
+| `agent-task`       | `{ prompt }`                                          | Envie uma solicitação ao chat do agente para tratar          |
+
+O sinalizador `primary: true` marca um método como o grande CTA para sua etapa.
+Use `badge: "soon"` mais `disabled: true` quando um caminho de configuração estiver visível
+antes de estar disponível.
+
+### Etapas integradas
+
+| ID         | Obrigatório | Descrição                                            |
+| ---------- | ----------- | ---------------------------------------------------- |
+| `llm`      | sim         | Conexão Builder ou chave LLM do provedor             |
+| `database` | não         | Banco de dados padrão ou qualquer SQL `DATABASE_URL` |
+| `auth`     | não         | Contas integradas, OAuth opcional ou token de acesso |
+| `email`    | não         | Reenviar ou SendGrid para e-mail transacional        |
+
+Qualquer um deles pode ser substituído registrando-se novamente com o mesmo `id` após
+carregamento padrão.
+
+### Uso do cliente
+
+O painel já está dentro do `<AgentPanel>`. Para criar um layout personalizado:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+Para saber onde os valores das etapas são armazenados e como os segredos são tratados,
+veja [Security](/docs/security). Para pontos de contato de mensagens do usuário final (convites,
+redefinições de senha) que dependem da etapa **Entrega de e-mail**, consulte
+[Messaging](/docs/messaging).