@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/pt-BR/tracking.md

@@ -0,0 +1,236 @@
+---
+title: "Acompanhamento e análise"
+description: "Análise do lado do servidor com provedores conectáveis — PostHog, Mixpanel, Amplitude ou webhook personalizado"
+---
+
+# Acompanhamento do Google Analytics
+
+Uma função, vários destinos. Chame `track()` a partir de qualquer código do lado do servidor – actions, plug-ins, rotas de servidor – e o evento se espalhará para todos os provedores de análise registrados. Sem dependências SDK, sem scripts do lado do cliente, sem bloqueio. O mesmo `track()` também está disponível em [browser/app code](#client) e é roteado para os mesmos provedores.
+
+Esta é a análise de _produto_ - os eventos do seu aplicativo fluindo para PostHog/Mixpanel/Amplitude. Para métricas de _qualidade do agente_ (rastreamentos, custos, avaliações, feedback) armazenadas em seu próprio banco de dados, consulte [Observability](/docs/observability).
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "order.completed",
+  { total: 49.99, items: 3 },
+  { userId: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One track() call, every provider" summary="Server and client callers hit the same registry, which fans every event out to all active providers in parallel."
+{
+  "html": "<div class=\"trk\"><div class=\"diagram-col\"><div class=\"diagram-node\">Server code<br><small class=\"diagram-muted\">actions &middot; plugins &middot; routes</small></div><div class=\"diagram-node\">Browser code<br><small class=\"diagram-muted\">POST /_agent-native/track</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Provider registry</span><small class=\"diagram-muted\">fan-out, fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">PostHog</div><div class=\"diagram-box\">Mixpanel</div><div class=\"diagram-box\">Amplitude</div><div class=\"diagram-box\">Webhook</div></div></div>",
+  "css": ".trk{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.trk .diagram-col{display:flex;flex-direction:column;gap:8px}.trk .diagram-arrow{font-size:22px;line-height:1}.trk .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Provedores integrados {#built-in}
+
+Defina um env var e o provedor será registrado automaticamente na inicialização do servidor. Não são necessárias alterações de código.
+
+| Provedor          | Vars ambientes                                                                                     |
+| ----------------- | -------------------------------------------------------------------------------------------------- |
+| PostHog           | `POSTHOG_API_KEY` (obrigatório), `POSTHOG_HOST` (opcional, o padrão é `https://us.i.posthog.com`)  |
+| Painel de mixagem | `MIXPANEL_TOKEN`                                                                                   |
+| Amplitude         | `AMPLITUDE_API_KEY`                                                                                |
+| Webhook           | `TRACKING_WEBHOOK_URL` (obrigatório), `TRACKING_WEBHOOK_AUTH` (cabeçalho `Authorization` opcional) |
+
+Vários provedores podem estar ativos simultaneamente. Cada evento vai para todos eles.
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+Dispare um evento de análise. Distribua para todos os fornecedores registrados.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+Identifique um usuário com características. Encaminhado para provedores que o suportam (PostHog, Mixpanel, Amplitude, webhook).
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+Precisa de um back-end personalizado, o registro do provedor API ou os componentes internos de lote/singleton? Veja [Advanced: custom providers & internals](#advanced) no final.
+
+## Usando track() em modelos {#templates}
+
+Chame `track()` de manipuladores de ação para registrar a atividade do usuário ou do agente:
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core/action";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+As chamadas de rastreamento são do tipo "dispare e esqueça" — elas retornam imediatamente e nunca bloqueiam a resposta da ação.
+
+## Acompanhamento do lado do cliente {#client}
+
+`track()` também funciona a partir do código do navegador/aplicativo. Importe o cliente gêmeo de `@agent-native/core/client` e chame-o da mesma maneira - ele envia o evento para a rota da estrutura em `POST /_agent-native/track`, que o encaminha para os **mesmos** provedores registrados do lado do servidor (PostHog, Mixpanel, Amplitude, webhook). Nenhuma análise do SDK é enviada para o navegador e nenhuma chave do provedor é exposta no lado do cliente.
+
+```an-api title="The client tracking route"
+{
+  "method": "POST",
+  "path": "/_agent-native/track",
+  "summary": "Forward a browser event to the registered server-side providers",
+  "auth": "Session required + same-origin/CSRF marker (set automatically by the client helper). Not an open analytics relay.",
+  "params": [
+    { "name": "name", "in": "body", "type": "string", "required": true, "description": "Event name. Capped at 200 characters." },
+    { "name": "properties", "in": "body", "type": "object", "description": "Event properties (~16KB cap). `source: \"client\"` and the active `org_id` are added server-side." }
+  ],
+  "description": "Identity is resolved **server-side** from the session — browser code never passes a `userId`. Fire-and-forget: never blocks the UI, never throws, swallows network errors. Oversized or malformed payloads are rejected."
+}
+```
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+Principais diferenças em relação ao [server `track()`](#track):
+
+- **Nenhum argumento de identidade.** O evento é atribuído no lado do servidor ao usuário conectado (e à organização ativa, como `org_id` em `properties`). O código do navegador nunca passa por `userId`.
+- **`source: "client"`** é adicionado às propriedades de cada evento para que você possa diferenciar os eventos originados do cliente dos do servidor.
+- **Dispare e esqueça.** Ele nunca bloqueia o UI, nunca lança e engole erros de rede.
+- **Autenticado, somente primário.** A rota requer uma sessão e um marcador de mesma origem/CSRF (definido automaticamente pelo auxiliar), portanto, não pode ser usada como uma retransmissão de análise aberta. `name` tem um limite de 200 caracteres e `properties` de aproximadamente 16 KB; cargas superdimensionadas ou malformadas são rejeitadas.
+
+Isso é diferente da telemetria interna do navegador da estrutura (`trackEvent()`/visualizações automáticas de página — veja [Browser defaults](#browser-defaults) abaixo), que alimenta a análise de produto do próprio Agent Native. Use `track()` para os eventos de análise do seu aplicativo que devem chegar aos provedores configurados.
+
+## Avançado: provedores personalizados e internos {#advanced}
+
+A maioria dos aplicativos só precisa de `track()`/`identify()` e de um provedor integrado. O resto da superfície – registro de provedores personalizados, a interface `TrackingProvider`, processamento interno de lotes e a telemetria do navegador da própria estrutura – está abaixo.
+
+<details>
+<summary><strong>Registro do provedor API, interface, componentes internos e padrões do navegador</strong></summary>
+
+### `registerTrackingProvider(provider)` {#register}
+
+Registre um provedor personalizado para qualquer back-end de análise.
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+    fetch("https://analytics.example.com/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    }).catch(() => {});
+  },
+  identify(userId, traits) {
+    // Optional — link user identity to future events
+  },
+  flush() {
+    // Optional — called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()` {#flush}
+
+Limpe todos os provedores. Ligue antes da saída do processo para garantir que os eventos pendentes sejam enviados.
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+Remover um provedor pelo nome. Retorna `true` se o provedor foi encontrado e removido.
+
+### `listTrackingProviders()` {#list}
+
+Retorna os nomes de todos os provedores registrados.
+
+### A interface TrackingProvider {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+Somente `name` e `track` são necessários. `identify` e `flush` são opcionais. Implemente-os se seu back-end oferecer suporte à identidade do usuário e entrega em lote.
+
+### Como funciona {#internals}
+
+- **HTTP em lote** — provedores integrados enfileiram eventos e liberam a cada 10 segundos ou quando 50 eventos se acumulam, o que ocorrer primeiro. Isso minimiza as solicitações de saída sem perder dados.
+- **Sem dependências de SDK** — todos os provedores integrados usam `fetch()` bruto. Sem PostHog SDK, sem Mixpanel SDK, sem Amplitude SDK. Mantém a estrutura leve.
+- **Entrega com melhor esforço** — os erros do provedor são detectados e registrados. Uma falha na integração analítica nunca trava o chamador ou bloqueia o tratamento da solicitação.
+- **Singleton global** — o registro usa uma chave `Symbol.for` em `globalThis` para que várias instâncias de gráfico ESM (modo de desenvolvimento Vite + Nitro, links simbólicos) compartilhem um conjunto de provedores.
+
+### Padrões do navegador {#browser-defaults}
+
+Isso cobre a telemetria interna da própria estrutura — principalmente relevante para contribuidores da estrutura e autores de modelos avançados.
+
+As raízes do modelo chamam `configureTracking()` uma vez na inicialização. Os eventos do navegador enviados com `trackEvent()` incluem automaticamente o contexto do aplicativo/modelo mais a conexão LLM atual quando o aplicativo pode resolvê-lo:
+
+- `llm_connection` — rótulo de provedor normalizado, como `builder`, `anthropic`, `openai`, `google` ou `none`
+- `llm_engine` — o ID do motor, por exemplo `builder` ou `ai-sdk:openai`
+- `llm_model` — o modelo selecionado/padrão quando conhecido
+- `llm_connection_source` — `app_secrets`, `settings` ou `env`
+- `llm_connection_configured` — se uma conexão LLM está disponível
+
+A estrutura também rastreia `builder connect clicked` de CTAs do Connect Builder, e as rotas de conexão Builder do lado do servidor rastreiam eventos de ciclo de vida iniciados/bem-sucedidos/com falha. `configureTracking()` é chamado automaticamente pelo framework; você não precisa chamá-lo em seu próprio código de modelo.
+
+</details>
+
+## O que vem a seguir
+
+- [**Actions**](/docs/actions) — onde se origina a maioria das chamadas de rastreamento
+- [**Server Plugins**](/docs/server) — `registerBuiltinProviders()` é executado no plugin core-routes na inicialização
+- [**Secrets**](/docs/security) — gerencie chaves API para provedores de rastreamento

package/corpus/core/docs/content/locales/pt-BR/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "Usando seu agente"
+description: "O ciclo diário de trabalho com o agente: ele vê o que você está vendo, você direciona, incorpora, torna-se UI-light e coedita junto com ele."
+---
+
+# Usando seu agente
+
+A ideia definidora por trás do agente nativo é que o agente e o UI são **parceiros iguais** — consulte [What Is Agent-Native?](/docs/what-is-agent-native) para saber o porquê. Esta seção trata da outra metade dessa promessa: como é realmente trabalhar com o agente quando ele está acoplado ao seu aplicativo.
+
+Existe uma linha direta simples. O agente **vê** o que você está vendo, você o **direciona** para o que deseja, pode **incorporá-lo** em qualquer lugar, pode usar totalmente **UI-light** quando for mais adequado e pode **coeditar** os mesmos documentos ao mesmo tempo. Cada uma delas é uma página nesta seção.
+
+```an-diagram title="The day-to-day loop" summary="Five ways of working with a docked agent — each is a page in this section."
+{
+  "html": "<div class=\"diagram-loop\"><div class=\"diagram-card\"><strong>Sees</strong><small class=\"diagram-muted\">your view &amp; selection</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Direct</strong><small class=\"diagram-muted\">@-mentions &amp; voice</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embed</strong><small class=\"diagram-muted\">drop into any app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>UI-light</strong><small class=\"diagram-muted\">chat is the product</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">Co-edit</span><small class=\"diagram-muted\">live, side by side</small></div></div>",
+  "css": ".diagram-loop{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-loop .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px;flex:1}.diagram-loop .diagram-arrow{align-self:center;font-size:22px;line-height:1}"
+}
+```
+
+## Ele vê o que você está vendo {#it-sees}
+
+O agente não fica cego para sua tela. Abra um e-mail e ele saberá qual tópico. Selecione um gráfico e ele saberá qual gráfico. Destaque um parágrafo e ele poderá atuar exatamente nesse intervalo. Essa consciência compartilhada é o que permite dizer "responda a isto" ou "resuma a seleção" sem precisar explicar o contexto todas as vezes.
+
+Isso funciona porque a navegação e seleção atuais residem em `application_state` SQL, que o agente lê como parte de seu contexto. O agente também pode retornar esse mesmo estado — abrindo uma visualização, selecionando uma linha — para que você observe o funcionamento no UI real, em vez de em uma transcrição.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Shared awareness is two-way.** You and the agent both read and write `application_state`, so \"reply to this\" or \"summarize the selection\" just works — and when the agent navigates, the real UI moves with it."
+}
+```
+
+→ [**Context Awareness**](/docs/context-awareness) — estado de navegação, visualização da tela, comandos de navegação e como o agente permanece sincronizado com sua tela.
+
+## Você dirige {#you-direct-it}
+
+Na maioria das vezes você orienta o agente digitando no chat. Duas coisas tornam isso mais rápido.
+
+**Menções.** Marque um agente personalizado, um agente conectado ou um arquivo com `@` para incluí-lo na conversa — "deixe `@analytics` extrair os números da semana passada e, em seguida, elabore o resumo." As menções servem para você chegar ao especialista certo ou anexar o contexto certo sem sair do compositor.
+
+**Voz.** O compositor possui um microfone. Dite uma solicitação em vez de digitá-la, com opções de provedor que vão desde a transcrição hospedada do Builder até trazer sua própria chave para um substituto do navegador.
+
+→ [**Agent Mentions**](/docs/agent-mentions) — `@` menciona agentes personalizados, agentes conectados e arquivos no chat.
+→ [**Voice Input**](/docs/voice-input) — ditado no compositor do chat e como a transcrição é encaminhada.
+
+## Você incorpora {#you-embed-it}
+
+O agente não é um aplicativo separado que você acessa. Ele é fornecido como um punhado de componentes React – uma barra lateral, um painel bruto e uma chamada `sendToAgentChat()` – que você coloca em qualquer aplicativo. Renderize `<AgentSidebar>` para dar a cada tela um agente alternável ou conecte um botão para entregar uma tarefa específica ao chat em vez de executar uma chamada LLM única.
+
+→ [**Drop-in Agent**](/docs/drop-in-agent) — monte `<AgentPanel>`, `<AgentSidebar>` e `sendToAgentChat()` em qualquer aplicativo React.
+→ [**Agent Surfaces**](/docs/agent-surfaces) — escolha se o fluxo de trabalho deve ser headless, chat-first, incorporado ou um aplicativo completo.
+
+## Você pode usar UI-light {#ui-light}
+
+Nem todo aplicativo precisa de um painel completo. Quando o agente _é_ o produto, você pode pular a maior parte do UI personalizado: abra o aplicativo, peça o que deseja e deixe o agente fazer o resto. O agente ainda tem sua superfície de gerenciamento (histórico, espaço de trabalho, configurações), mas a interação principal é a conversa, e não os cliques.
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — aplicativos onde o agente é o produto completo.
+
+## Você coedita com ele {#you-co-edit}
+
+Quando você e o agente estão trabalhando no mesmo documento, vocês não se revezam. Com a colaboração em tempo real, as edições do agente são transmitidas junto com as suas — cursores ativos, sem substituições — da mesma forma que um colega de equipe faria. Você pode continuar digitando enquanto ele funciona e ele verá as alterações conforme elas acontecem.
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — edição colaborativa multiusuário com cursores ativos e edições de agente no mesmo documento.
+
+## O que vem a seguir {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) — o agente sabe o que você está vendo
+- [**Agent Mentions**](/docs/agent-mentions) — direcione-o com menções a `@`
+- [**Voice Input**](/docs/voice-input) — direcione falando
+- [**Drop-in Agent**](/docs/drop-in-agent) — incorpore-o em qualquer aplicativo React
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) — vá para UI-light quando o agente for o produto
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — coeditam o mesmo documento juntos

package/corpus/core/docs/content/locales/pt-BR/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "Entrada de voz"
+description: "Ditado de voz no compositor de bate-papo do agente — Builder Gemini, provedores BYOK e substituto de Web Speech do navegador."
+---
+
+# Entrada de voz
+
+Todo aplicativo nativo do agente possui um microfone no compositor de bate-papo. Clique nele, fale e suas palavras serão transcritas no prompt. Útil em dispositivos móveis, útil para solicitações longas, útil quando você está em outra coisa.
+
+A estrutura lida com tudo isso automaticamente. Os usuários conectados ao Builder obtêm o Gemini Flash-Lite hospedado no Builder por padrão; caso contrário, os usuários poderão trazer sua própria chave de provedor ou recorrer ao reconhecimento de fala do navegador.
+
+## Como funciona {#how-it-works}
+
+O botão de voz do compositor grava o áudio no navegador e depois escolhe um provedor:
+
+1. **Builder Gemini Flash-Lite (padrão quando Builder está conectado).** O navegador envia áudio para `/_agent-native/transcribe-voice`, que faz proxy através de Builder.io usando Gemini Flash-Lite. Não é necessária nenhuma chave Google API.
+2. **Provedores de nuvem BYOK.** Os usuários podem escolher Google Gemini, Groq Whisper ou OpenAI Whisper em Configurações. A rota resolve segredos criptografados no escopo do usuário antes das credenciais de implantação compartilhadas.
+3. **Fala da Web do navegador API (substituição).** Se nenhum provedor de servidor estiver disponível, o compositor poderá usar o reconhecimento de fala integrado do navegador. Funciona em navegadores baseados em Chromium (Chrome, Edge, Arc) e Safari. Menos preciso; transmite ao vivo.
+
+A escolha do provedor é armazenada no estado do aplicativo em `voice-transcription-prefs` para que o usuário possa forçar `"auto"` (padrão - escolhe o melhor provedor disponível), `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"` ou `"browser"` nas configurações da barra lateral.
+
+```an-diagram title="Voice transcription provider fallback" summary="The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."
+{
+  "html": "<div class=\"diagram-voice\"><div class=\"diagram-node\">Mic button<br><small class=\"diagram-muted\">records webm/opus</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill accent\">1 &middot; Builder Gemini</div><small class=\"diagram-muted\">default when Builder connected</small><div class=\"diagram-pill\">2 &middot; BYOK cloud</div><small class=\"diagram-muted\">Gemini &middot; Groq &middot; OpenAI Whisper</small></div><div class=\"diagram-arrow diagram-warn\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box diagram-warn\" data-rough>3 &middot; Browser Web Speech<br><small class=\"diagram-muted\">fallback on 400 &middot; streams live</small></div></div>",
+  "css": ".diagram-voice{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-voice .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-voice .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+A rota é **somente da mesma origem** — POSTs entre sites são rejeitados para que um invasor não possa gravar créditos de transcrição de uma página externa.
+
+## Habilitando provedores {#enabling-providers}
+
+Builder é o caminho mais fácil: conecte Builder.io em Configurações e o provedor padrão se tornará Builder Gemini Flash-Lite. Para provedores BYOK, adicione a chave correspondente em Configurações → Chaves API.
+
+### Por usuário (recomendado para SaaS)
+
+O usuário define sua própria chave por meio das configurações da barra lateral do agente UI. Ele é armazenado como um segredo criptografado no escopo do usuário (via `readAppSecret`). Cada usuário paga pela sua própria transcrição; custo zero para o anfitrião.
+
+### Compartilhado (para ferramentas internas)
+
+Defina `GEMINI_API_KEY`, `GROQ_API_KEY` ou `OPENAI_API_KEY` como uma variável de ambiente ou na tabela `settings`. A transcrição de cada usuário atinge a chave compartilhada.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Credential resolution order:** the route checks the user's own encrypted secret first, then the shared deployment key. A power user with their own key always overrides the shared one. If neither exists, the route returns a 400 the composer recognizes and silently falls back to browser Web Speech."
+}
+```
+
+## A rota {#route}
+
+```an-api title="Voice transcription route"
+{
+  "method": "POST",
+  "path": "/_agent-native/transcribe-voice",
+  "summary": "Transcribe a recorded audio clip into prompt text",
+  "auth": "Active session (Better Auth cookie). Same-origin only.",
+  "description": "The composer POSTs the recorded clip here; the route resolves a provider and returns the transcribed text. You should not call this directly.",
+  "params": [
+    { "name": "audio", "in": "body", "type": "file", "required": true, "description": "The recorded clip, webm/opus by default. Max 25 MB." },
+    { "name": "provider", "in": "body", "type": "string", "required": false, "description": "Optional override, e.g. gemini, groq, openai, builder." }
+  ],
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "Transcription succeeded", "example": "{ \"text\": \"reply to Sara that I'll be there by 3\" }" },
+    { "status": "400", "description": "No server provider configured — the composer recognizes this and falls back to Web Speech", "example": "{ \"error\": \"no_provider\" }" }
+  ]
+}
+```
+
+Você não precisa chamar isso diretamente — o compositor precisa. Se você estiver construindo uma superfície de entrada personalizada, primeiro reutilize as peças compartilhadas do compositor/cliente de voz do `@agent-native/core/client`. Trate esta rota como o limite de transporte de baixo nível para auxiliares personalizados que precisam enviar áudio multiparte.
+
+## Personalizando o provedor {#customizing}
+
+O campo do provedor é uma chave simples de estado do aplicativo, portanto o agente pode alterá-la mediante solicitação (`"use the browser speech recognizer instead"`). Se você estiver criando um modelo com requisitos diferentes (por exemplo, uma implantação local do Whisper), troque o manipulador de rota registrando sua própria rota `transcribe-voice` antes que a estrutura monte o padrão.
+
+## O que vem a seguir
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — o compositor que expõe o botão de voz
+- [**Onboarding**](/docs/onboarding) — registrando chaves de provedor como etapas de configuração
+- [**Security & Data Scoping**](/docs/security) — como os segredos criptografados são armazenados por usuário

package/corpus/core/docs/content/locales/pt-BR/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "O que é Agent-Native?"
+description: "Por que a maioria dos aplicativos de IA parece incompleta, o que torna um aplicativo verdadeiramente nativo do agente e como resultado é sua experiência diária."
+---
+
+# O que é Agent-Native?
+
+Agente nativo é uma forma de criar software onde o agente de IA e a superfície do produto ao seu redor são **parceiros iguais**. Essa superfície pode ser um agente sem cabeça com uma ação personalizada, um bate-papo avançado ou um UI completo. A parte importante é que agentes e humanos compartilhem o mesmo actions, banco de dados e estado.
+
+Se você se lembra apenas de uma coisa desta página, lembre-se disto: a maioria dos aplicativos de IA atuais não chega a ser útil, e essa lacuna é o maior erro no espaço no momento.
+
+## Qual é a aparência de um usuário {#what-it-looks-like}
+
+Imagine um trabalhador em segundo plano, uma caixa de entrada, um calendário, um criador de formulários ou um painel de análise. Às vezes, ainda não há uma tela personalizada: você executa uma ação ou um prompt do agente de aplicativo sem comando. Às vezes, a primeira tela é o chat: você pergunta o que deseja, o agente orienta a configuração, mostra uma tabela ou gráfico e abre a visualização correta do aplicativo. Às vezes, o bate-papo fica encaixado no lado direito de um aplicativo completo. Entre essas formas, você pode:
+
+- **Comece com a operação real.** Uma ação durável pode ser executada a partir do CLI, HTTP, MCP, A2A, do loop do agente de aplicativo e, posteriormente, de um UI.
+- **Clique em qualquer coisa que você normalmente clicaria quando houvesse um UI.** Todos os botões, listas, painéis, atalhos de teclado — todos eles chamam as mesmas operações que o agente pode chamar.
+- **Ou apenas pergunte.** Digite "resposta ao e-mail de Sara dizendo que estarei lá às 15h" no agente. Ele abre o tópico certo, rascunha a resposta e mostra-a para aprovação, exatamente como se você tivesse feito isso manualmente.
+- **Veja o que ele vê.** Abra um e-mail e o agente saberá qual. Selecione um gráfico e o agente saberá qual gráfico. Destaque um parágrafo e pressione Cmd+I, e o agente atuará apenas nesse parágrafo.
+- **Veja como funciona.** À medida que o agente faz as coisas — abre visualizações, edita rascunhos, executa relatórios — o UI é atualizado em tempo real. Você pode pará-lo, redirecioná-lo ou assumir o controle com o mouse a qualquer momento.
+- **Direcione-o como um colega de equipe.** Dê feedback, coloque outra tarefa na fila, edite suas instruções, audite o que ele fez ontem. Ele lembra e melhora seus fluxos de trabalho com o tempo.
+
+Essa é a experiência para a qual o agente nativo foi projetado. Veja por que a maioria dos produtos não chega lá.
+
+## Por que a maioria dos "aplicativos de IA" fica aquém (Princípio da escada) {#the-ladder}
+
+Há uma progressão que a maioria das equipes sobe, como uma escada, e a maioria para um degrau muito cedo.
+
+### Lista 1 — uma única chamada LLM (o antipadrão) {#rung-one}
+
+Uma caixa de texto envia um prompt, a IA retorna uma string e você a exibe. Talvez com um spinner. Não há como o usuário corrigir o curso, nem a IA agir, nem como ver o que aconteceu ou por quê.
+
+Você vê isso em todos os lugares: "recursos de IA" que são basicamente um botão "Resumir" fixado em um produto SaaS. Eles parecem impressionantes em demos e quebram no momento em que a realidade fica confusa. Isso não é um produto; isso é um brinquedo.
+
+### Rung 2 — um bate-papo com ferramentas {#rung-two}
+
+Agora a IA pode _fazer coisas_. Possui ferramentas – “rascunhar e-mail”, “pesquisar contatos”, “executar consulta” – e uma interface de bate-papo onde funciona na sua frente, mostrando chamadas de ferramentas e resultados à medida que avança. Esta é a aparência interna de Claude, ChatGPT e Cursor.
+
+Este é um verdadeiro avanço. Mas por si só, ainda é uma janela de bate-papo. Não existe um UI adequado. Sem painéis, sem listas, sem formulários, sem atalhos de teclado, sem colaboração em equipe. Se a IA ficar confusa, você terá que redigitar em vez de apenas clicar com o botão direito. Os não desenvolvedores têm dificuldade para realizar um trabalho real nesse formato.
+
+### Degrau 3 — agente + UI como parceiros iguais {#rung-three}
+
+Isso é nativo do agente. Você adiciona um aplicativo real e completo ao redor do agente – e, o que é mais importante, cada ação que o agente pode realizar também é um botão no UI, e cada botão em que o usuário clica executa a mesma lógica que o agente usa. Uma implementação, duas entradas.
+
+Três coisas mudam quando você chega ao degrau 3:
+
+- **Você parou de adicionar botões a um chatbot. Você adicionou um agente a um aplicativo.** Esse é um produto de qualidade muito superior em ambos os lados.
+- **O agente tem contexto real.** Ele vê o que você está vendo, o que você selecionou, o que acabou de fazer. Ele grava no mesmo banco de dados do qual UI lê, então seu trabalho aparece imediatamente.
+- **Agentes externos também podem usá-lo.** Outros aplicativos nativos do agente podem chamar o actions deste em vez do [A2A protocol](/docs/a2a-protocol). Código Claude, Codex, aplicativos MCP personalizados ChatGPT, Cursor e outros hosts MCP podem conduzi-lo como um [MCP server](/docs/mcp-protocol). Um aplicativo, muitos pontos de entrada.
+
+É a linha 3. É nativo do agente.
+
+```an-diagram title="The Ladder Principle" summary="Most teams stop at rung 1 or 2. Agent-native is rung 3 — a real app and a real agent over one shared action surface."
+{
+  "html": "<div class=\"diagram-ladder\"><div class=\"diagram-card rung rung-3\"><span class=\"diagram-pill accent\">Rung 3 · agent-native</span><strong>Agent + UI as equal partners</strong><small class=\"diagram-muted\">One action surface. Every agent tool is also a button; every button runs the same logic the agent uses.</small></div><div class=\"diagram-card rung rung-2\"><span class=\"diagram-pill\">Rung 2</span><strong>A chat with tools</strong><small class=\"diagram-muted\">The agent can act — but it is still just a chat window. No dashboards, lists, or shortcuts.</small></div><div class=\"diagram-card rung rung-1\"><span class=\"diagram-pill warn\">Rung 1</span><strong>A single LLM call</strong><small class=\"diagram-muted\">Prompt in, string out. Impressive in a demo; breaks the moment reality gets messy.</small></div></div>",
+  "css": ".diagram-ladder{display:flex;flex-direction:column;gap:14px}.diagram-ladder .rung{display:flex;flex-direction:column;gap:6px;padding:16px 18px}.diagram-ladder .rung-2{margin-inline-end:48px}.diagram-ladder .rung-1{margin-inline-end:96px}"
+}
+```
+
+Veja [Key Concepts — Protocols](/docs/key-concepts#protocols) para saber como tudo isso depende da mesma definição de ação.
+
+## Por que todo agente precisa de um UI {#why-every-agent-needs-a-ui}
+
+Mesmo quando o agente faz todo o trabalho pesado, os humanos ainda precisam:
+
+- **Veja o que está fazendo** — progresso, resultados intermediários, o que foi tocado
+- **Direcione** — dê feedback, interrompa, coloque a próxima tarefa na fila
+- **Gerencie-o** — edite suas instruções, skills, memória, trabalhos agendados, contas conectadas
+- **Inspecione seu trabalho** — revise rascunhos, audite o histórico, reverta erros
+- **Compartilhe seus resultados** — painéis, relatórios, formulários, links para enviar aos colegas de equipe
+
+No mínimo, "um UI para o agente" é um painel de observação e gerenciamento. No máximo, é um aplicativo SaaS completo com o agente incorporado como copiloto. Ambas as extremidades contam como nativas do agente, e a superfície pode crescer a partir de uma sem reescrita.
+
+Você não precisa escolher uma forma antecipadamente. O agente pode funcionar sem cabeça, sentar-se atrás de um bate-papo avançado ou viver dentro de um aplicativo completo em torno da mesma superfície de ação. Consulte [Agent Surfaces](/docs/agent-surfaces) para obter formas concretas e APIs.
+
+## Por que todo aplicativo se beneficia de um agente {#why-every-app-benefits-from-an-agent}
+
+O outro lado é igualmente importante. Os produtos SaaS existentes continuam batendo na mesma parede: 80% do que você precisa funciona muito bem e 20% você simplesmente não pode mudar. Adicionar uma barra lateral de bate-papo raramente corrige isso. O bate-papo geralmente não consegue _fazer_ as coisas que o UI pode.
+
+O agente nativo inverte isso. Como cada ação no aplicativo é definida uma vez e exposta tanto como um botão quanto como uma ferramenta do agente, o agente pode fazer tudo o que os botões podem — e muito mais — sem um “mundo de IA” separado para manter. A linguagem natural se torna uma entrada de primeira classe junto com os cliques.
+
+O argumento não é "agentes substituem UI". É "**os agentes pertencem aos aplicativos, com um UI no topo, como parceiros iguais**." Mesmo um aplicativo em que o agente _é_ o produto ainda precisa de um UI para ser supervisionado, configurado e orientado por humanos. Consulte [Agent Surfaces — Headless](/docs/agent-surfaces#headless).
+
+## Paridade Agente + UI {#agent-ui-parity}
+
+Este é o princípio definidor.
+
+> **No UI** — clique em botões, preencha formulários, navegue em visualizações. O UI grava no banco de dados; o agente vê os resultados.
+>
+> **Do agente** — linguagem natural, outros agentes via A2A, Slack, Telegram. O agente grava no banco de dados; o UI é atualizado automaticamente.
+
+```an-diagram title="One system, two ways in" summary="The agent and the UI write to the same actions and the same database. Whatever one does, the other sees."
+{
+  "html": "<div class=\"diagram-parity\"><div class=\"diagram-col\"><div class=\"diagram-node\">Human<br><small class=\"diagram-muted\">clicks, forms, shortcuts</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">natural language · A2A · Slack</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defined once</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL database</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">UI updates live</div></div>",
+  "css": ".diagram-parity{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-parity .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-parity .diagram-arrow{font-size:22px;line-height:1}.diagram-parity .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+Quando o agente cria um rascunho de e-mail, ele aparece no UI. Ao clicar em “Enviar”, o agente sabe que foi enviado. Não existe um “mundo do agente” e um “mundo UI” separados – é um sistema. Consulte [Key Concepts](/docs/key-concepts) para conhecer a arquitetura que faz isso funcionar.
+
+## Personalização geralmente reservada para ferramentas elétricas {#workspace-customization}
+
+O motivo pelo qual ferramentas como o Claude Code parecem tão poderosas não é o modelo, mas a **camada de personalização**: instruções por projeto, skills, memória, subagentes, serviços conectados. Você pode moldar o agente de acordo com sua base de código, suas preferências, sua equipe.
+
+O Agent-native oferece a todos os usuários a mesma camada de personalização, sem nunca sair do aplicativo. Cada aplicativo vem com um **espaço de trabalho** pessoal onde você (ou qualquer pessoa da sua equipe) pode:
+
+- Edite as regras de toda a equipe que todos os agentes lêem
+- Permita que o agente lembre as preferências automaticamente conforme você as corrige
+- Escreva guias de instruções reutilizáveis como comandos `/slash`
+- Mantenha subagentes personalizados para tarefas específicas (invocados com `@mentions`)
+- Programe tarefas para serem executadas em um cron (por exemplo, "todas as segundas-feiras de manhã, resumir a semana passada")
+- Conecte serviços externos (Gmail, Stripe, Slack, APIs internos) por meio de servidores MCP por usuário
+
+A diferença: tudo é armazenado no banco de dados, não no sistema de arquivos. Não há ambiente de desenvolvimento para ativar, nem contêiner por usuário. Cada usuário obtém seu próprio espaço de trabalho completo – memória pessoal, conexões pessoais, skills pessoal – essencialmente de graça, porque são todas as linhas de uma tabela. É isso que torna viável a flexibilidade em nível de código Claude dentro de um produto SaaS real multilocatário.
+
+Veja [Workspace](/docs/workspace) para o conceito completo.
+
+## O que o torna diferente {#what-makes-it-different}
+
+| Abordagem                                     | Descrição                                                                                                                                                   |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Aplicativos tradicionais com IA integrada** | A IA é uma reflexão tardia. Limitado ao preenchimento automático, aos resumos ou a uma barra lateral de bate-papo que não pode fazer nada no aplicativo.    |
+| **Interfaces puras de chat/agente**           | Poderoso, mas inacessível. Sem painéis, sem fluxos de trabalho, sem persistência. Quem não é desenvolvedor não consegue usá-los de maneira eficaz.          |
+| **Código Claude/Codex para SaaS**             | Ótimo para desenvolvedores em suas próprias máquinas. Não se traduz em SaaS multilocatário: uma base de código por usuário em um dev-box não é escalonável. |
+| **Aplicativos nativos do agente**             | O agente é um cidadão de primeira classe. Ele compartilha o mesmo banco de dados, o mesmo estado e pode fazer tudo o que o UI pode fazer — e vice-versa.    |
+
+## Desenvolvimento de toda a equipe {#whole-team-development}
+
+O agente nativo não é apenas para desenvolvedores. Como o agente pode editar o próprio código do aplicativo, a evolução de um aplicativo deixa de ser uma atividade exclusiva do desenvolvedor:
+
+- **Designers** atualizam designs diretamente no aplicativo em execução por meio do agente
+- **Gerentes de produtos** adicionam funcionalidades e atualizam fluxos descrevendo-os
+- **QA** testa o aplicativo e pede ao agente para consertar o que está quebrado
+- **Qualquer pessoa da equipe** contribui por meio de linguagem natural
+
+A visão: menos transferências, uma pessoa fazendo o trabalho de uma equipe pequena.
+
+## Bifurque e personalize {#fork-and-customize}
+
+Os aplicativos nativos do agente seguem um modelo de bifurcação e personalização. Você começa com um **modelo** — Calendário, Conteúdo, Apresentações, Analytics, Mail, Clipes, Design, Formulários, Envio — e personaliza-o. Cada um deles é um produto SaaS completo e funcional que você vende no atacado, e não uma estrutura em branco:
+
+1. Escolha um modelo em [agent-native.com/templates](/templates)
+2. Use-o imediatamente como um aplicativo hospedado (por exemplo, mail.agent-native.com)
+3. Fork quando quiser personalizar — "conectar nossa conta Stripe", "adicionar um gráfico de coorte"
+4. O agente modifica o código para atender às suas necessidades
+5. Implante seu fork em seu próprio domínio — ou permaneça em agent-native.com
+
+Como é _seu_ aplicativo, e não uma infraestrutura compartilhada, o agente pode evoluir o código com segurança. Seu aplicativo continua melhorando à medida que você o usa. Veja [Templates](/docs/cloneable-saas) para a história completa.
+
+Não está pronto para criar um modelo inteiro? Você também pode experimentar o agente nativo adicionando uma **habilidade** a um agente de codificação que você já usa — instale a habilidade Planos com `npx @agent-native/core@latest skills add visual-plan`. Veja o [Skills Guide](/docs/skills-guide#app-backed-skills).
+
+## Agentes que podem ser compostos {#composable-agents}
+
+Aplicativos nativos do agente podem se comunicar entre si. De dentro do aplicativo de e-mail, você pode marcar o agente de análise para consultar dados e incluir o resultado em um rascunho de e-mail. Os agentes descobrem quais outros agentes estão disponíveis, transferem o trabalho entre si e apresentam os resultados no UI em que você já está.
+
+Isso é desenvolvido internamente por [A2A](/docs/a2a-protocol) e [MCP](/docs/mcp-protocol) — mesma definição, múltiplas superfícies — mas como usuário, tudo o que você precisa saber é "Posso pedir ajuda a qualquer um dos meus aplicativos com qualquer coisa que qualquer um deles possa fazer."
+
+## Como isso se parece no código? {#what-does-it-look-like-in-code}
+
+Se você estiver criando ou estendendo um aplicativo nativo do agente, este é o padrão central: cada operação no aplicativo é uma **ação** — definida uma vez, disponível tanto para o agente quanto para o UI.
+
+```an-annotated-code title="One action, defined once"
+{
+  "filename": "actions/reply-to-email.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Reply to an email thread\",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app's server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this as a tool." },
+    { "lines": "6", "label": "Contrato tipado", "note": "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A." },
+    { "lines": "7-10", "label": "One implementation", "note": "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this." }
+  ]
+}
+```
+
+```tsx
+// In any React component — same action, called from a button
+const { mutate } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+```tsx
+// And the agent panel mounted anywhere in your app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
+
+Uma ação, muitas superfícies: o agente o chama como uma ferramenta, o UI o chama como uma mutação typesafe, o [native chat](/docs/native-chat-ui) pode renderizar resultados explícitos do widget, os agentes externos o alcançam através do [A2A](/docs/a2a-protocol) e os hosts MCP o chamam através do [MCP server](/docs/mcp-protocol) do aplicativo, opcionalmente com os recursos do MCP Apps UI e o controle remoto padrão MCP OAuth tratado pela estrutura. Consulte [Actions](/docs/actions) para referência completa.
+
+## O que vem a seguir {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) — comece com uma ação, escolha um modelo ou instale uma habilidade
+- [**Agent Surfaces**](/docs/agent-surfaces) — escolha bate-papo avançado, sem interface, sidecar incorporado ou aplicativo completo
+- [**Key Concepts**](/docs/key-concepts) — a arquitetura: SQL, actions, sincronização de polling, reconhecimento de contexto, portabilidade
+- [**Templates**](/docs/cloneable-saas) — modelos como produtos completos que você possui
+- [**Workspace**](/docs/workspace) — a camada de personalização por usuário (skills, memória, instruções, MCP) apoiada por SQL, não por arquivos
+- [**Dispatch**](/docs/dispatch) — o plano de controle do espaço de trabalho: cofre de segredos, Slack/caixa de entrada de e-mail, delegação entre aplicativos
+- [**Extensions**](/docs/extensions) — miniaplicativos em sandbox que o agente cria instantaneamente sem alterações de código
+- [**Drop-in Agent**](/docs/drop-in-agent) — monte `<AgentPanel>` em qualquer aplicativo React