@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/pt-BR/agent-mentions.md

@@ -0,0 +1,164 @@
+---
+title: "Menções de agente"
+description: "Etiquete agentes personalizados, agentes conectados e arquivos no bate-papo com @menções."
+---
+
+# Menções de agente
+
+Digite `@` no compositor do chat para mencionar agentes personalizados, agentes conectados, arquivos e recursos.
+
+## Visão geral {#overview}
+
+O sistema de menção `@` conecta o compositor de bate-papo ao ecossistema mais amplo de agentes. Quando você digita `@`, um popover aparece listando agentes personalizados, agentes conectados, arquivos de base de código e recursos disponíveis.
+
+É assim que você orquestra fluxos de trabalho multiagentes a partir de um único chat. Peça ao seu agente `@design` local para avaliar um layout, ao `@analytics` para obter os números mais recentes de outro aplicativo, e o agente principal pode incorporar ambos em uma conversa.
+
+## Mencionando agentes {#mentioning-agents}
+
+Para mencionar um agente no compositor do chat:
+
+1. Digite `@` para abrir o popover de menção
+2. Navegue ou pesquise a lista de agentes disponíveis
+3. Selecione um agente — ele aparece como uma tag na sua mensagem
+4. Envie a mensagem — o servidor resolve a menção e inclui a resposta do agente no contexto da conversa
+
+Existem dois caminhos de agente:
+
+- **Agentes personalizados** — perfis de agente do espaço de trabalho local em `agents/*.md`. Eles são executados dentro do aplicativo/tempo de execução atual usando as instruções do perfil do agente e a substituição opcional do modelo.
+- **Agentes conectados** — pares A2A remotos. Eles são chamados pelo [A2A protocol](/docs/a2a-protocol).
+
+Em ambos os casos, seu agente principal vê a resposta e pode referenciá-la ou aproveitá-la.
+
+```an-diagram title="Where an @-mention routes" summary="The server splits each mention by type: custom agents run locally, connected agents go over A2A — both responses fold back into the main agent's context."
+{
+  "html": "<div class=\"diagram-mention\"><div class=\"diagram-node\">@-mention<br><small class=\"diagram-muted\">in the composer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Server resolves</span><small class=\"diagram-muted\">extract refs by type</small></div><div class=\"diagram-col\"><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">Custom agent<br><small class=\"diagram-muted\">agents/*.md &middot; runs local</small></div></div><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">Connected agent<br><small class=\"diagram-muted\">A2A peer &middot; remote call</small></div></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box diagram-accent\">&lt;agent-response&gt;<br><small class=\"diagram-muted\">injected into main agent</small></div></div>",
+  "css": ".diagram-mention{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-mention .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-mention .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-mention .row{display:flex;align-items:center;gap:8px}.diagram-mention .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Como funciona {#how-it-works}
+
+Quando uma mensagem contendo uma menção `@` é enviada, acontece o seguinte no servidor:
+
+1. O servidor extrai referências de menção da mensagem
+2. Para cada agente mencionado:
+   - agentes personalizados são executados localmente com instruções de perfil
+   - agentes conectados são chamados via A2A
+3. A resposta do agente é encapsulada em um bloco `<agent-response>` XML e injetada no contexto da conversa
+4. O agente principal processa a mensagem enriquecida, vendo tanto o texto do usuário quanto a resposta do agente mencionado
+
+O que o agente principal vê em seu contexto:
+
+```text
+User: Draft an email with the latest signup numbers. @analytics
+
+<agent-response agent="analytics">
+Last week's signups: 1,247 total
+  - Organic: 623
+  - Paid: 412
+  - Referral: 212
+</agent-response>
+```
+
+O agente principal pode então usar esses dados naturalmente em sua resposta – por exemplo, incorporando os números em um rascunho de e-mail.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Mentioned-agent output arrives as an `<agent-response agent=\"…\">` block in the **main agent's** context — not as separate chat bubbles. The main agent decides how to weave it into the reply."
+}
+```
+
+## Adicionando agentes {#adding-agents}
+
+Os agentes ficam disponíveis para menção por meio de vários mecanismos:
+
+- **Agentes de espaço de trabalho personalizados** — crie perfis de agente na guia Espaço de trabalho como `agents/*.md`
+- **Descoberta automática** — a estrutura descobre automaticamente agentes conectados em execução em portas conhecidas ou URLs configurados
+- **Manifestos remotos** — adicione manifestos de agente conectado como `remote-agents/*.json`
+
+### Agentes de espaço de trabalho personalizados
+
+Agentes personalizados são arquivos Markdown armazenados no espaço de trabalho:
+
+```markdown
+---
+name: Design
+description: Reviews layouts, product UX, and visual direction.
+model: inherit
+---
+
+You are a focused design agent.
+```
+
+Consulte [Workspace — Custom Agents](/docs/workspace#custom-agents) para obter o formato completo (incluindo `tools`, `delegate-default` e substituições de modelo).
+
+Você pode criá-los na guia Espaço de trabalho usando:
+
+- `Create Agent` -> `Describe It`
+- `Create Agent` -> `Fill Form`
+
+### Manifestos do agente conectado
+
+Agentes A2A remotos ainda usam manifestos JSON:
+
+```json
+// remote-agents/analytics.json
+{
+  "name": "Analytics Agent",
+  "url": "https://analytics.example.com",
+  "apiKey": "env:ANALYTICS_A2A_KEY",
+  "description": "Runs analytics queries and returns data",
+  "skills": ["run-query", "generate-chart"]
+}
+```
+
+---
+
+## Para desenvolvedores: ampliando as menções {#extending-mentions}
+
+Os modelos podem registrar provedores de menções personalizadas para adicionar itens mencionáveis específicos do domínio, além de agentes e arquivos. Um provedor de menções implementa a interface `MentionProvider`:
+
+```an-annotated-code title="A custom MentionProvider"
+{
+  "filename": "server/mentions/contacts.ts",
+  "language": "ts",
+  "code": "import type { MentionProvider } from \"@agent-native/core/server\";\n\nconst contactsProvider: MentionProvider = {\n  id: \"contacts\",\n  label: \"Contacts\",\n\n  // Search for mentionable items\n  async search(query: string) {\n    const contacts = await db.query.contacts.findMany({\n      where: like(contacts.name, `%${query}%`),\n      limit: 10,\n    });\n    return contacts.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      type: \"contact\",\n    }));\n  },\n\n  // Resolve a mention into context for the agent\n  async resolve(id: string) {\n    const contact = await db.query.contacts.findFirst({\n      where: eq(contacts.id, id),\n    });\n    return {\n      type: \"context\",\n      text: `Contact: ${contact.name} (${contact.email})`,\n    };\n  },\n};",
+  "annotations": [
+    { "lines": "4-5", "label": "Identity", "note": "`id` namespaces the provider; `label` is the section heading shown in the `@` popover." },
+    { "lines": "8-9", "label": "search", "note": "Runs as the user types after `@`. Return up to a handful of matches as `{ id, label, description, type }`." },
+    { "lines": "23-24", "label": "resolve", "note": "Called when the message is sent. Turns a picked id into `{ type: \"context\", text }` that is injected into the agent's context." }
+  ]
+}
+```
+
+Registre provedores na configuração do plugin Agent-Chat:
+
+```ts
+// server/plugins/agent-chat.ts
+import { createAgentChatPlugin } from "@agent-native/core/server";
+
+export default createAgentChatPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  mentionProviders: { contacts: contactsProvider },
+});
+```
+
+Os provedores de menção personalizados aparecem junto com o agente integrado e os provedores de arquivo no popover de menção.
+
+## Referenciando arquivos {#referencing-files}
+
+O popover `@` não está limitado aos agentes. Você também pode consultar:
+
+- **Arquivos Codebase** — digite `@` e procure um nome de arquivo. O conteúdo do arquivo é incluído no contexto do agente para que ele possa ler, analisar ou modificar o arquivo.
+- **Recursos do espaço de trabalho** — arquivos de referência definidos na guia Espaço de trabalho. Podem ser arquivos de dados, configuração ou qualquer outro conteúdo estruturado.
+- **Skills** — digite `/` para referenciar uma habilidade. Skills fornece instruções estruturadas que orientam como o agente aborda uma tarefa.
+
+Todos os tipos de referência seguem o mesmo padrão: selecione no popover e o conteúdo referenciado é resolvido e injetado no contexto do agente quando a mensagem é enviada.
+
+## Seleção de subagente {#sub-agent-selection}
+
+O agente principal também pode usar agentes personalizados ao gerar subagentes com `agent-teams` (ação: "spawn").
+
+Passe o parâmetro `agent` para escolher um perfil de `agents/*.md`. As instruções desse perfil são adicionadas à execução delegada e seu frontmatter `model` pode substituir o modelo padrão para esse subagente.

package/docs/content/locales/pt-BR/agent-surfaces.md

@@ -0,0 +1,397 @@
+---
+title: "Superfícies do agente"
+description: "Use Agent-Native sem controle, como bate-papo avançado, dentro de um aplicativo existente ou como um aplicativo completo nativo do agente."
+search: "aplicativo completo de bate-papo rico com agente sem cabeça BYO tempo de execução do agente AgentChatRuntime incorporado actions MCP A2A HTTP CLI"
+---
+
+# Superfícies do agente
+
+Agent-Native é deliberadamente combinável. Você pode usar o agente sem muito UI,
+use o UI sem o tempo de execução do agente integrado ou use os dois juntos como um pacote completo
+aplicativo.
+
+A maneira útil de escolher não é primeiro por protocolo. Escolha a superfície do produto
+você deseja, então use a primitiva correspondente.
+
+| Superfície                            | Use quando                                                                                                                               | Comece com                                                                                  |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **Agente sem cabeça**                 | Código, tarefas, scripts, outro aplicativo ou outro agente devem chamar o trabalho diretamente.                                          | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **Bate-papo rico em Agent-Native**    | Você deseja um bate-papo independente ou incorporado, apoiado pelo loop de agente integrado.                                             | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
+| **Bate-papo avançado com seu agente** | Você criou o agente em outro lugar e deseja o compositor, a transcrição, os cartões de ferramentas e os widgets nativos do Agent-Native. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
+| **Carro lateral incorporado**         | Você já tem um aplicativo SaaS e deseja um agente ao lado dele com contexto de página e comandos de host.                                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
+| **Aplicativo completo**               | Humanos e agentes devem compartilhar telas, dados, navegação e colaboração duráveis.                                                     | Modelos, actions, estado SQL, reconhecimento de contexto                                    |
+
+São etapas, não produtos separados. Um fluxo de trabalho pode começar sem interface
+agente com uma ação, aparece no chat como uma tabela ou gráfico e depois se torna um
+tela inteira em um aplicativo sem alterar a operação que o agente chama.
+
+```an-diagram title="The surface spectrum" summary="One action surface, four product shapes — each adds UI without changing the operation underneath."
+{
+  "html": "<div class=\"diagram-spectrum\"><div class=\"diagram-card\"><strong>Headless</strong><small class=\"diagram-muted\">actions, jobs, scripts, other agents</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Rich chat</strong><small class=\"diagram-muted\">composer, transcript, tool cards</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embedded sidecar</strong><small class=\"diagram-muted\">agent beside an existing app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">most UI</span><strong>Full application</strong><small class=\"diagram-muted\">durable screens, data, collaboration</small></div></div><div class=\"diagram-base\" data-rough><span class=\"diagram-muted\">same actions · same SQL · same agent loop</span></div>",
+  "css": ".diagram-spectrum{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-spectrum .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px;flex:1}.diagram-spectrum .diagram-arrow{align-self:center;font-size:22px;line-height:1}.diagram-base{margin-top:12px;padding:10px 14px;text-align:center}"
+}
+```
+
+## Agente sem cabeça {#headless}
+
+Use o caminho sem cabeça quando ninguém precisar olhar para a tela de um aplicativo personalizado enquanto
+o trabalho é executado: jobs agendados, integrações, fluxos de trabalho de back-end, loops CLI,
+outro agente ou um produto existente ligando para Agent-Native.
+
+Essa também é a forma a ser alcançada quando **o agente _é_ o produto** — o
+o loop do agente de aplicativo é a porta de entrada, não um painel. Você envia uma solicitação do
+terminal, Slack, e-mail, um trabalho agendado, outro agente ou Chat — "resuma meu
+e-mails não lidos", "postar as métricas diárias em Slack", "encontrar os candidatos que
+respondeu na semana passada" — e o agente age e retorna o resultado onde quer que esteja
+pertence. Ainda é um aplicativo real, não um prompt sem estado: actions, sessões de autenticação,
+estado do aplicativo, histórico de thread/execução, configurações, credenciais e registros de compartilhamento, tudo ao vivo
+em SQL.
+
+Escolha este padrão quando:
+
+- **O trabalho acontece em segundo plano.** A maior parte do valor é criada enquanto o usuário não está olhando: agentes de triagem, agentes de relatórios diários, atendentes de plantão.
+- **A saída sai do aplicativo.** O agente posta no Slack, envia e-mail ou atualiza um sistema de terceiros; não há nada para navegar no aplicativo.
+- **O domínio é único.** Bot de pesquisa, gerador de resumo, redator de relatórios — nenhum objeto persistente que precise de uma visualização de lista.
+- **Você está criando um protótipo.** Envie o agente agora; adicione UI mais rico posteriormente se os usuários desejarem.
+
+Se o seu produto for construído em torno de objetos persistentes, os usuários navegam, dinamizam e
+compartilhe — e-mails, eventos, documentos, gráficos — escolha um [full application](#full-application)
+ou um [template](/docs/cloneable-saas); eles adicionam um UI completo _mais_ o agente.
+
+### O que vem na caixa {#in-the-box}
+
+Um aplicativo headless pula semanas de trabalho no painel e é independente de canal durante o dia
+um — o mesmo agente é executado na web, Slack, Telegram, e-mail e outros agentes
+porque tudo passa pelo agente e não pelo UI. A desvantagem é que existe
+sem visualização "navegar tudo de relance"; se os usuários precisarem disso, misture padrões e
+adicione uma pequena página de status ou visualização de lista.
+
+Quando você adiciona o shell de bate-papo integrado, a estrutura fornece cinco gerenciamentos
+superfícies que você não precisa criar: **Chat** (a entrada principal), **Workspace**
+(skills, memória, instruções, subagentes, servidores MCP conectados, agendados
+trabalhos), **Histórico de trabalhos**, **Histórico de threads** e **Configurações**. Geralmente são
+basta — converse com ele, veja o que ele faz, configure como ele se comporta. Alcance
+[Chat](/docs/template-chat) quando estiver pronto para adicionar o navegador UI ou o
+[Dispatch template](/docs/template-dispatch) para uma inicialização estilo espaço de trabalho
+ponto com Slack/Telegram, trabalhos agendados e segredos compartilhados prontos para uso.
+
+O menor caminho local é um andaime de agente sem cabeça mais uma ação:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
+pnpm install
+```
+
+Em seguida, defina a operação durável:
+
+```ts
+// actions/summarize-week.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Summarize this week's submissions.",
+  readOnly: true,
+  schema: z.object({ formId: z.string() }),
+  run: async ({ formId }) => {
+    return { formId, summary: "34 submissions, up 18% from last week." };
+  },
+});
+```
+
+Uma ação pode ser chamada como:
+
+- **HTTP** — `POST /_agent-native/actions/summarize-week`
+- **CLI** — `pnpm action summarize-week --formId form_123`
+- **Agente de aplicativo CLI** — `pnpm agent "Summarize form_123"`
+- **MCP** — de Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot e outros hosts MCP
+- **A2A** — de outro aplicativo nativo do agente ou peer de agente
+- **UI** — por meio de `useActionQuery`, `useActionMutation` ou `callAction`
+- **Ferramenta de agente** — no loop de bate-papo integrado
+
+```an-api title="Calling an action over HTTP"
+{
+  "method": "POST",
+  "path": "/_agent-native/actions/summarize-week",
+  "summary": "Invoke any action by name over HTTP",
+  "description": "Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes.",
+  "request": {
+    "contentType": "application/json",
+    "example": "{ \"formId\": \"form_123\" }"
+  },
+  "responses": [
+    { "status": "200", "description": "The action's return value as JSON", "example": "{ \"formId\": \"form_123\", \"summary\": \"34 submissions, up 18% from last week.\" }" },
+    { "status": "400", "description": "Input failed schema validation" }
+  ]
+}
+```
+
+Este não é um modo sem banco de dados ou sem estado. O loop app-agent armazena sessões,
+threads, execuções, configurações, credenciais, estado do aplicativo e registros de compartilhamento em
+SQL. O padrão de desenvolvimento local é SQLite; aplicativos headless hospedados devem usar um
+banco de dados SQL persistente.
+
+Se você precisar de todo o loop do agente sem cabeça na pasta do projeto, use:
+
+```bash
+pnpm agent "Summarize this week's forms."
+```
+
+Se outro aplicativo ou script precisar chamar todo o agente, use
+`agentNative.invoke("analytics", "...")` ou `agent-native invoke` CLI. Isso
+mantém o trabalho entre aplicativos no caminho A2A enquanto o trabalho local permanece em actions.
+
+Workers, jobs, integração webhooks e hosts personalizados podem conduzir o loop do agente
+diretamente através do servidor API. Este é um nível inferior ao actions — você fornece
+o mecanismo, o modelo, as mensagens, o actions e o coletor de eventos:
+
+```ts
+import { runAgentLoop } from "@agent-native/core/server";
+
+await runAgentLoop({ engine, model, systemPrompt, actions, messages, send });
+```
+
+Para a maioria dos aplicativos, os prompts programados e a integração webhooks já chamam esse loop
+para você. Alcance-o diretamente apenas ao criar um host headless personalizado, eval
+executor ou superfície de orquestração do lado do servidor — consulte [Servidor — Agente de produção
+handler](/docs/server#agent-handler) para obter a assinatura completa.
+
+### Executando em uma pasta {#folder-loop}
+
+Se seu objetivo é "executar um agente nesta pasta", comece com o app-agent
+fazer um loop nessa pasta: criar o scaffold do aplicativo headless, adicionar actions/instructions, executar
+`pnpm agent "..."`. Isso mantém o trabalho dentro da mesma ação/tempo de execução/estado
+contrato que o aplicativo usará na produção.
+
+Os chicotes de codificação externos são uma superfície de produto separada para incorporar Claude
+Código, Codex, Pi, Cursor, Mastra ou tempos de execução semelhantes dentro de um aplicativo Agent-Native.
+Use-os ao criar um produto de agente de codificação, não como a forma padrão de fazer
+iniciar um fluxo de trabalho nativo do agente local.
+
+### Acesso ao repositório na nuvem {#cloud-repo-access}
+
+Para aplicativos headless em nuvem que precisam de acesso ao repositório, use o conector GitHub
+modelo plus token CRUD: listar repositórios, pesquisar arquivos, ler arquivos, criar ou
+editar arquivos, excluir arquivos e revogar acesso por meio do escopo do provedor
+credenciais. No desenvolvimento local, defina explicitamente o repositório de destino:
+
+```bash
+GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
+```
+
+Não trate um clone de VM ou uma verificação de sandbox de longa duração como a nuvem primária
+modelo de acesso ao repositório. Sandboxes ainda são importantes para execução isolada de código, mas
+o acesso ao repositório deve ser explícito, autorizado, auditável e revogável
+pela camada do conector.
+
+### Compartilhamento de sessões e execuções {#sharing-runs}
+
+Sessões e execuções headless são objetos duráveis. A partilha deve ser faseada:
+leia/compartilhe links primeiro, para que os colegas de equipe possam inspecionar prompts e saídas higienizados
+e status de execução; colaboração gravável com permissão posteriormente, continuando a execução,
+aprovação de actions, edição de cronogramas ou alteração de configurações
+verificações de acesso explícito.
+
+## Bate-papo rico em Agent-Native {#rich-chat}
+
+Use o chat integrado quando o usuário precisar falar com o agente, veja chamadas de ferramentas,
+aprove trabalhos, inspecione resultados nativos e mantenha um histórico de conversas duradouro.
+
+Para um ponto de partida completo do aplicativo, use [Chat template](/docs/template-chat):
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+```
+
+O chat de página inteira mais simples:
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+Quando um aplicativo tiver uma guia de bate-papo de página inteira e um `AgentSidebar`, use o mesmo
+`storageKey` em ambas as superfícies, habilite `chatViewTransition` e instale o
+ajudantes de transferência chat-home no layout. Links comuns no aplicativo fora do bate-papo
+a página pode então transformar o bate-papo completo na barra lateral enquanto mantém o ativo
+tópico:
+
+```tsx
+import {
+  AgentChatSurface,
+  AgentSidebar,
+  useAgentChatHomeHandoff,
+  useAgentChatHomeHandoffLinks,
+} from "@agent-native/core/client/chat";
+import { useLocation } from "react-router";
+
+function ChatRoute() {
+  return (
+    <AgentChatSurface mode="page" storageKey="my-app" chatViewTransition />
+  );
+}
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  const location = useLocation();
+  const handoffActive = useAgentChatHomeHandoff({
+    storageKey: "my-app",
+    activePath: location.pathname,
+    enabled: location.pathname !== "/chat",
+  });
+  useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" });
+
+  return (
+    <AgentSidebar
+      storageKey="my-app"
+      chatViewTransition
+      openOnChatRunning={handoffActive}
+    >
+      {children}
+    </AgentSidebar>
+  );
+}
+```
+
+O bate-papo incorporado mais simples com seu próprio Chrome:
+
+```tsx
+import { AssistantChat } from "@agent-native/core/client/chat";
+
+export function ProjectChat({ threadId }: { threadId: string }) {
+  return <AssistantChat threadId={threadId} />;
+}
+```
+
+Actions pode retornar resultados de widget nativos explícitos para que a saída do chat não seja apenas
+texto. Tabelas, gráficos e cartões de produtos digitados são renderizados como React primários
+componentes no chat, sem iframes. Consulte [Native Chat UI](/docs/native-chat-ui).
+
+## Bate-papo avançado com seu agente {#byo-agent}
+
+Use este caminho quando seu agente já estiver construído com outra estrutura ou
+tempo de execução e você deseja o bate-papo do Agent-Native UI em torno dele. `AgentChatRuntime` é o
+limite: seu tempo de execução transmite eventos normalizados e Agent-Native renderiza o
+compositor, transcrição, chamadas de ferramentas, aprovações, widgets nativos e layout do aplicativo.
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  endpoint: "/api/support-agent/chat",
+});
+
+export function SupportAgentChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+Existem auxiliares de tempo de execução prontos para agentes OpenAI, respostas OpenAI e Claude
+Agente SDK, Vercel AI SDK e AG-UI, além do tempo de execução HTTP normalizado acima
+para qualquer outro agente (Mastra, Flue, Eve, LangGraph ou um serviço personalizado). ACP é
+não é o bate-papo do aplicativo do usuário final ou o transporte A2A, e Agent-Native atualmente não
+reivindicar suporte A2UI. ACP é compatível com um local específico: dirigindo um local
+agente de codificação (Gemini CLI, Claude Code, …) através do
+[harness layer](/docs/harness-agents#acp), não como o tempo de execução do chat aqui.
+
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+é o local canônico para os formatos de evento, os auxiliares de tempo de execução e `chatUI`
+metadados de resultados da ferramenta. Comece por aí ao conectar um agente externo ao chat.
+
+## Carrinho lateral incorporado {#embedded-sidecar}
+
+Use o arquivo secundário incorporado quando o produto principal já existir e você quiser um
+agente ao lado.
+
+O plug-in do servidor monta rotas Agent-Native em seu aplicativo host e resolve
+identidade do host no lado do servidor:
+
+```ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+O sidecar React passa o contexto da página e comandos de host:
+
+```tsx
+import { AgentNativeEmbedded } from "@agent-native/core/client";
+
+export function AppShell({ children }) {
+  return (
+    <AgentNativeEmbedded
+      getContext={() => ({
+        route: { pathname: window.location.pathname },
+        selection: { text: window.getSelection()?.toString() || undefined },
+      })}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRefresh={() => queryClient.invalidateQueries()}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+```an-diagram title="How the sidecar bridges to a host app" summary="The plugin mounts Agent-Native routes server-side; the React sidecar streams page context in and host commands out."
+{
+  "html": "<div class=\"diagram-sidecar\"><div class=\"diagram-panel\"><strong>Host app</strong><small class=\"diagram-muted\">your existing SaaS</small><div class=\"diagram-node\">getContext()<br><small class=\"diagram-muted\">route · selection</small></div><div class=\"diagram-node\">onNavigate / onRefresh<br><small class=\"diagram-muted\">host commands</small></div></div><div class=\"diagram-col-arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div></div><div class=\"diagram-panel accent-panel\"><span class=\"diagram-pill accent\">AgentNativeEmbedded</span><small class=\"diagram-muted\">agent + workspace</small><div class=\"diagram-box\" data-rough>Agent-Native routes<br><small class=\"diagram-muted\">mounted by the server plugin</small></div></div></div>",
+  "css": ".diagram-sidecar{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sidecar .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 16px;min-width:200px}.diagram-sidecar .diagram-col-arrows{display:flex;flex-direction:column;gap:6px}.diagram-sidecar .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Consulte [Embedding SDK](/docs/embedding-sdk) para autenticação de host e isolamento de banco de dados
+modo iframe/seletor e ponte de nível inferior APIs.
+
+## Aplicativo completo {#full-application}
+
+Use o caminho completo do aplicativo quando os usuários precisarem de objetos e fluxos de trabalho duráveis: formulários,
+painéis, calendários, caixas de entrada, editores, documentos, ativos ou relatórios.
+
+Aplicativos completos adicionam o produto UI em torno da mesma ação e contrato de agente:
+
+- **Estado SQL** — dados do aplicativo, navegação, configurações e histórico de bate-papo são duráveis.
+- **Reconhecimento de contexto** — o agente conhece a rota atual, a seleção e o objeto em foco.
+- **Sincronização ao vivo** — as alterações do agente atualizam o UI e as alterações do UI atualizam o contexto do agente.
+- **Links diretos** — os resultados da ação podem abrir a visualização correta do aplicativo.
+- **Widgets de bate-papo nativos** — tabelas, gráficos, cartões, aprovações e resultados digitados aparecem inline.
+
+Comece pelo [Chat template](/docs/template-chat) quando quiser um aplicativo mínimo
+em torno de seu actions ou de um domínio [template](/docs/cloneable-saas) quando você
+quer um formato de produto completo.
+
+## Como escolher {#how-to-choose}
+
+| Se você está pensando...                                                   | Escolher                          |
+| -------------------------------------------------------------------------- | --------------------------------- |
+| "Só preciso de uma ferramenta ou fluxo de trabalho que possa ser chamado." | Agente sem cabeça                 |
+| "Quero o agente do framework, mas o chat deve ser o principal UI."         | Bate-papo rico em Agent-Native    |
+| "Já tenho um agente; preciso de um chat sofisticado UI para isso."         | Bate-papo avançado com seu agente |
+| "Já tenho um aplicativo SaaS; adicione um agente ao lado dele."            | Carrinho lateral incorporado      |
+| "O agente e UI devem evoluir juntos como o produto."                       | Aplicativo completo               |
+
+Mantenha o contrato pequeno: defina operações duráveis como actions, retorne explícito
+resultados de widget quando o bate-papo precisa de UI rico e adicionar telas inteiras somente quando os usuários
+precisa navegar, comparar, configurar ou colaborar em objetos persistentes.
+
+## Documentos relacionados {#related-docs}
+
+- [Actions](/docs/actions) — defina a operação sem comando uma vez.
+- [Native Chat UI](/docs/native-chat-ui) — renderiza os resultados da ação digitada no bate-papo.
+- [Drop-in Agent](/docs/drop-in-agent) — monte bate-papo, barra lateral ou superfícies de painel.
+- [Component API](/docs/components) — peças de bate-papo/compositor React de nível inferior.
+- [Embedding SDK](/docs/embedding-sdk) — adicione Agent-Native a um aplicativo existente.
+- [External Agents](/docs/external-agents) — conecta hosts compatíveis com MCP a um aplicativo.
+- [A2A Protocol](/docs/a2a-protocol) — liga para agentes de outros agentes.