@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/tracking.md

@@ -0,0 +1,236 @@
+---
+title: "Seguimiento y análisis"
+description: "Análisis del lado del servidor con proveedores conectables: PostHog, Mixpanel, Amplitude o webhook personalizado"
+---
+
+# Seguimiento de análisis
+
+Una función, múltiples destinos. Llame a `track()` desde cualquier código del lado del servidor (actions, complementos, rutas del servidor) y el evento se distribuirá a todos los proveedores de análisis registrados. Sin dependencias de SDK, sin scripts del lado del cliente, sin bloqueos. El mismo `track()` también está disponible en [browser/app code](#client) y enruta a los mismos proveedores.
+
+Esto es análisis de _producto_: los eventos de su aplicación fluyen hacia PostHog/Mixpanel/Amplitude. Para conocer las métricas de _calidad del agente_ (seguimientos, costos, evaluaciones, comentarios) almacenadas en su propia base de datos, 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}"
+}
+```
+
+## Proveedores integrados {#built-in}
+
+Establezca una var de entorno y el proveedor se registre automáticamente al iniciar el servidor. No se requieren cambios de código.
+
+| Proveedor   | Variaciones de entorno                                                                              |
+| ----------- | --------------------------------------------------------------------------------------------------- |
+| Correo      | `POSTHOG_API_KEY` (obligatorio), `POSTHOG_HOST` (opcional, por defecto `https://us.i.posthog.com`)  |
+| Panel mixto | `MIXPANEL_TOKEN`                                                                                    |
+| Amplitud    | `AMPLITUDE_API_KEY`                                                                                 |
+| Webhook     | `TRACKING_WEBHOOK_URL` (obligatorio), `TRACKING_WEBHOOK_AUTH` (encabezado `Authorization` opcional) |
+
+Varios proveedores pueden estar activos simultáneamente. Cada evento es para todos ellos.
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+Activa un evento de análisis. Distribución en abanico para todos los proveedores registrados.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+Identificar un usuario con rasgos. Reenviado a proveedores que lo admiten (PostHog, Mixpanel, Amplitude, webhook).
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+¿Necesita un backend personalizado, el registro de proveedores API o los componentes internos de procesamiento por lotes/singleton? Ver [Advanced: custom providers & internals](#advanced) al final.
+
+## Usar track() en plantillas {#templates}
+
+Llame a `track()` desde los controladores de acciones para registrar la actividad del usuario o 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 };
+  },
+});
+```
+
+Las llamadas de seguimiento son activadas y olvidadas: regresan inmediatamente y nunca bloquean la respuesta a la acción.
+
+## Seguimiento del lado del cliente {#client}
+
+`track()` también funciona desde el código del navegador/aplicación. Importe el cliente gemelo de `@agent-native/core/client` y llámelo de la misma manera: envía el evento a la ruta del marco en `POST /_agent-native/track`, que lo reenvía a los **mismos** proveedores registrados del lado del servidor (PostHog, Mixpanel, Amplitude, webhook). No se envía ningún análisis SDK al navegador y no se exponen claves de proveedor en el lado del 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 });
+```
+
+Diferencias clave con respecto al [server `track()`](#track):
+
+- **Sin argumento de identidad.** El evento se atribuye en el lado del servidor al usuario que inició sesión (y a la organización activa, como `org_id` en `properties`). El código del navegador nunca pasa por un `userId`.
+- **`source: "client"`** se agrega a las propiedades de cada evento para que puedas diferenciar los eventos originados por el cliente de los del servidor.
+- **Dispara y olvida.** Nunca bloquea el UI, nunca lanza ni traga errores de red.
+- **Autenticado, solo de origen.** La ruta requiere una sesión y un marcador del mismo origen/CSRF (establecido automáticamente por el ayudante), por lo que no se puede utilizar como retransmisión de análisis abierta. `name` tiene un límite de 200 caracteres y `properties` de ~16 KB; se rechazan las cargas útiles de gran tamaño o con formato incorrecto.
+
+Esto es distinto de la telemetría interna del navegador del marco (`trackEvent()` / vistas de página automáticas; consulte [Browser defaults](#browser-defaults) a continuación), que impulsa el propio análisis de productos de Agent Native. Utilice `track()` para los eventos de análisis propios de su aplicación que deberían llegar a sus proveedores configurados.
+
+## Avanzado: proveedores personalizados e internos {#advanced}
+
+La mayoría de las aplicaciones solo necesitan `track()` / `identify()` y un proveedor integrado. El resto de la superficie (registro de proveedores personalizados, la interfaz `TrackingProvider`, componentes internos de procesamiento por lotes y la propia telemetría del navegador del marco) se encuentra a continuación.
+
+<details>
+<summary><strong>Registro de proveedor API, interfaz, componentes internos y valores predeterminados del navegador</strong></summary>
+
+### `registerTrackingProvider(provider)` {#register}
+
+Registre un proveedor personalizado para cualquier backend de análisis.
+
+```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}
+
+Elimine a todos los proveedores. Llame antes de salir del proceso para asegurarse de que se envíen los eventos pendientes.
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+Eliminar un proveedor por nombre. Devuelve `true` si el proveedor fue encontrado y eliminado.
+
+### `listTrackingProviders()` {#list}
+
+Devuelve los nombres de todos los proveedores registrados.
+
+### La interfaz de 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;
+}
+```
+
+Solo se requieren `name` y `track`. `identify` y `flush` son opcionales: impleméntelos si su backend admite la identidad del usuario y la entrega por lotes.
+
+### Cómo funciona {#internals}
+
+- **HTTP por lotes**: los proveedores integrados ponen en cola los eventos y los vacían cada 10 segundos o cuando se acumulan 50 eventos, lo que ocurra primero. Esto minimiza las solicitudes salientes sin perder datos.
+- **Sin dependencias de SDK**: todos los proveedores integrados utilizan `fetch()` sin formato. Sin PostHog SDK, sin Mixpanel SDK, sin Amplitude SDK. Mantiene el marco liviano.
+- **Entrega con el mejor esfuerzo**: los errores del proveedor se detectan y registran. Una integración analítica fallida nunca bloquea a la persona que llama ni bloquea el manejo de solicitudes.
+- **Singleton global**: el registro utiliza una clave `Symbol.for` en `globalThis`, por lo que varias instancias de gráficos ESM (modo de desarrollo Vite + Nitro, enlaces simbólicos) comparten un conjunto de proveedores.
+
+### Valores predeterminados del navegador {#browser-defaults}
+
+Esto cubre la propia telemetría interna del marco, principalmente relevante para los contribuyentes del marco y los autores de plantillas avanzadas.
+
+Las raíces de la plantilla llaman a `configureTracking()` una vez al inicio. Los eventos del navegador enviados con `trackEvent()` incluyen automáticamente el contexto de la aplicación/plantilla más la conexión actual de LLM cuando la aplicación puede resolverlo:
+
+- `llm_connection`: etiqueta de proveedor normalizada, como `builder`, `anthropic`, `openai`, `google` o `none`
+- `llm_engine` — la identificación del motor, por ejemplo `builder` o `ai-sdk:openai`
+- `llm_model`: el modelo seleccionado/predeterminado cuando se conoce
+- `llm_connection_source` — `app_secrets`, `settings` o `env`
+- `llm_connection_configured`: si hay una conexión LLM disponible
+
+El marco también rastrea `builder connect clicked` desde los CTA de Connect Builder, y las rutas de conexión Builder del lado del servidor rastrean los eventos del ciclo de vida iniciados, exitosos o fallidos. El marco llama automáticamente a `configureTracking()`; no es necesario que lo llames en tu propio código de plantilla.
+
+</details>
+
+## ¿Qué sigue?
+
+- [**Actions**](/docs/actions): donde se originan la mayoría de las llamadas de seguimiento
+- [**Server Plugins**](/docs/server) — `registerBuiltinProviders()` se ejecuta en el complemento core-routes al inicio
+- [**Secrets**](/docs/security): administra claves API para proveedores de seguimiento

package/docs/content/locales/es-ES/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "Usar su agente"
+description: "El ciclo diario de trabajar con el agente: ve lo que estás mirando, tú lo diriges, lo incrustas, lo hace UI-light y lo coedita."
+---
+
+# Usando a su agente
+
+La idea que define el agente nativo es que el agente y el UI son **socios iguales**; consulte [What Is Agent-Native?](/docs/what-is-agent-native) para conocer el por qué. Esta sección trata sobre la otra mitad de esa promesa: cómo se siente trabajar realmente con el agente una vez que está acoplado junto a su aplicación.
+
+Hay una línea directa simple. El agente **ve** lo que estás viendo, tú lo **diriges** hacia lo que deseas, puedes **incrustarlo** en cualquier lugar, puedes hacerlo completamente **UI-light** cuando sea mejor y puedes **coeditar** los mismos documentos al mismo tiempo. Cada una de ellas es una página en esta sección.
+
+```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}"
+}
+```
+
+## Ve lo que estás mirando {#it-sees}
+
+El agente no está ciego a su pantalla. Abra un correo electrónico y sabrá qué hilo. Seleccione un gráfico y sabrá qué gráfico. Resalte un párrafo y podrá actuar solo en ese rango. Esa conciencia compartida es lo que te permite decir "responder a esto" o "resumir la selección" sin tener que explicar el contexto cada vez.
+
+Esto funciona porque la navegación y selección actuales se encuentran en `application_state` SQL, que el agente lee como parte de su contexto. El agente también puede devolver ese mismo estado (abrir una vista, seleccionar una fila) para que puedas verlo funcionar en el UI real en lugar de en una transcripción.
+
+```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 navegación, visualización de pantalla, comandos de navegación y cómo el agente permanece sincronizado con su pantalla.
+
+## Tú lo diriges {#you-direct-it}
+
+La mayoría de las veces diriges al agente escribiendo en el chat. Hay dos cosas que lo hacen más rápido.
+
+**Menciones.** Etiquete un agente personalizado, un agente conectado o un archivo con `@` para incluirlo en la conversación: "deje que `@analytics` obtenga los números de la semana pasada y luego redacte el resumen". Las menciones permiten llegar al especialista adecuado o adjuntar el contexto adecuado sin abandonar al compositor.
+
+**Voz.** El compositor tiene un micrófono. Dicte una solicitud en lugar de escribirla, con opciones de proveedor que van desde la transcripción alojada de Builder hasta traer su propia clave a un navegador alternativo.
+
+→ [**Agent Mentions**](/docs/agent-mentions) — `@`: mencione agentes personalizados, agentes conectados y archivos en el chat.
+→ [**Voice Input**](/docs/voice-input): dictado en el compositor del chat y cómo se enruta la transcripción.
+
+## Lo incrustas {#you-embed-it}
+
+El agente no es una aplicación independiente a la que puedes acceder. Se envía como un puñado de componentes React (una barra lateral, un panel sin formato y una llamada `sendToAgentChat()`) que se pueden colocar en cualquier aplicación. Renderice `<AgentSidebar>` para darle a cada pantalla un agente alternable, o conecte un botón para transferir una tarea específica al chat en lugar de ejecutar una llamada única a LLM.
+
+→ [**Drop-in Agent**](/docs/drop-in-agent): monta `<AgentPanel>`, `<AgentSidebar>` y `sendToAgentChat()` en cualquier aplicación React.
+→ [**Agent Surfaces**](/docs/agent-surfaces): elija si el flujo de trabajo debe ser headless, chat primero, integrado o una aplicación completa.
+
+## Puedes ir a UI-light {#ui-light}
+
+No todas las aplicaciones necesitan un panel completo. Cuando el agente _es_ el producto, puede omitir la mayor parte del UI personalizado: abra la aplicación, solicite lo que desee y deje que el agente haga el resto. El agente todavía tiene su superficie de administración (historial, espacio de trabajo, configuración), pero la interacción principal es la conversación en lugar de los clics.
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps): aplicaciones donde el agente es el producto completo.
+
+## Coeditas con él {#you-co-edit}
+
+Cuando usted y el agente trabajan en el mismo documento, no se turnan. Con la colaboración en tiempo real, las ediciones del agente se transmiten junto con las suyas (cursores en vivo, sin sobrescrituras) de la misma manera que lo haría un compañero de equipo. Puedes seguir escribiendo mientras funciona y ve los cambios a medida que ocurren.
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration): edición colaborativa multiusuario con cursores en vivo y ediciones de agentes en el mismo documento.
+
+## ¿Qué sigue? {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness): el agente sabe lo que estás mirando
+- [**Agent Mentions**](/docs/agent-mentions): dirígelo con menciones `@`
+- [**Voice Input**](/docs/voice-input): dirígelo hablando
+- [**Drop-in Agent**](/docs/drop-in-agent): incrustarlo en cualquier aplicación React
+- [**Pure-Agent Apps**](/docs/pure-agent-apps): pasa a UI-light cuando el agente es el producto
+- [**Real-Time Collaboration**](/docs/real-time-collaboration): coeditar el mismo documento juntos

package/docs/content/locales/es-ES/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "Entrada de voz"
+description: "Dictado de voz en el compositor de chat del agente: Builder Gemini, proveedores BYOK y reserva de voz web del navegador."
+---
+
+# Entrada de voz
+
+Cada aplicación nativa del agente tiene un micrófono en el compositor de chat. Haga clic en él, hable y sus palabras se transcribirán en el mensaje. Útil en dispositivos móviles, útil para mensajes largos, útil cuando tienes otra cosa entre manos.
+
+El marco maneja todo esto automáticamente. Los usuarios conectados a Builder obtienen Gemini Flash-Lite alojado en Builder de forma predeterminada; de lo contrario, los usuarios pueden traer su propia clave de proveedor o recurrir al reconocimiento de voz del navegador.
+
+## Cómo funciona {#how-it-works}
+
+El botón de voz del compositor graba audio en el navegador y luego elige un proveedor:
+
+1. **Builder Gemini Flash-Lite (predeterminado cuando Builder está conectado).** El navegador envía audio a `/_agent-native/transcribe-voice`, que actúa como proxy a través de Builder.io usando Gemini Flash-Lite. No se requiere ninguna clave API de Google.
+2. **Proveedores de nube BYOK.** Los usuarios pueden elegir Google Gemini, Groq Whisper o OpenAI Whisper en Configuración. La ruta resuelve secretos cifrados de ámbito de usuario antes que las credenciales de implementación compartidas.
+3. **Voz web del navegador API (alternativa).** Si no hay ningún proveedor de servidor disponible, el compositor puede utilizar el reconocimiento de voz integrado del navegador. Funciona en navegadores basados ​​en Chromium (Chrome, Edge, Arc) y Safari. Menos preciso; transmite en vivo.
+
+La elección del proveedor se almacena en el estado de la aplicación en `voice-transcription-prefs` para que el usuario pueda forzar `"auto"` (predeterminado: elige el mejor proveedor disponible), `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"` o `"browser"` en la configuración de la 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}"
+}
+```
+
+La ruta es **solo del mismo origen**: las POST entre sitios se rechazan para que un atacante no pueda grabar créditos de transcripción desde una página externa.
+
+## Habilitación de proveedores {#enabling-providers}
+
+Builder es el camino más fácil: conecte Builder.io desde Configuración y el proveedor predeterminado será Builder Gemini Flash-Lite. Para proveedores BYOK, agregue la clave coincidente en Configuración → Claves API.
+
+### Por usuario (recomendado para SaaS)
+
+El usuario establece su propia clave a través de la configuración de la barra lateral del agente UI. Se almacena como un secreto cifrado exclusivo del usuario (a través de `readAppSecret`). Cada usuario paga por su propia transcripción; coste cero para el anfitrión.
+
+### Compartido (para herramientas internas)
+
+Establezca `GEMINI_API_KEY`, `GROQ_API_KEY` o `OPENAI_API_KEY` como una variable de entorno o en la tabla `settings`. La transcripción de cada usuario llega a la clave compartida.
+
+```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."
+}
+```
+
+## la ruta {#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\" }" }
+  ]
+}
+```
+
+No es necesario llamar a esto directamente: el compositor lo hace. Si está creando una superficie de entrada personalizada, primero reutilice las piezas compartidas del compositor/cliente de voz de `@agent-native/core/client`. Trate esta ruta como el límite de transporte de bajo nivel para los asistentes personalizados que necesitan enviar audio multiparte.
+
+## Personalizar el proveedor {#customizing}
+
+El campo del proveedor es una clave simple de estado de la aplicación, por lo que el agente puede cambiarla si lo solicita (`"use the browser speech recognizer instead"`). Si está creando una plantilla con requisitos diferentes (por ejemplo, una implementación de Whisper local), cambie el controlador de ruta registrando su propia ruta `transcribe-voice` antes de que el marco monte la ruta predeterminada.
+
+## ¿Qué sigue?
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — el compositor que expone el botón de voz
+- [**Onboarding**](/docs/onboarding): registro de claves de proveedor como pasos de configuración
+- [**Security & Data Scoping**](/docs/security): cómo se almacenan los secretos cifrados por usuario

package/docs/content/locales/es-ES/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "¿Qué es Agent-Native?"
+description: "Por qué la mayoría de las aplicaciones de IA parecen estar a medio construir, qué hace que una aplicación sea verdaderamente nativa del agente y cómo se ve tu experiencia diaria como resultado."
+---
+
+# ¿Qué es Agent-Native?
+
+El agente nativo es una forma de crear software en la que el agente de IA y la superficie del producto que lo rodea son **socios iguales**. Esa superficie puede ser un agente sin cabeza con una acción personalizada, un chat enriquecido o un UI completo. Lo importante es que los agentes y los humanos comparten el mismo actions, base de datos y estado.
+
+Si solo recuerdas una cosa de esta página, recuerda esto: la mayoría de las aplicaciones de IA actuales están a un paso de ser útiles, y esa brecha es el mayor error en este espacio en este momento.
+
+## Cómo se ve como usuario {#what-it-looks-like}
+
+Imagínese un trabajador en segundo plano, una bandeja de entrada, un calendario, un creador de formularios o un panel de análisis. A veces todavía no hay una pantalla personalizada: ejecuta una acción o un mensaje de agente de aplicación sin cabeza. A veces, la primera pantalla es el chat: usted pregunta qué quiere, el agente guía la configuración, muestra una tabla o gráfico y abre la vista de aplicación correcta. A veces, el chat se encuentra acoplado en el lado derecho de una aplicación completa. A través de esas formas, puedes:
+
+- **Comience con la operación real.** Se puede ejecutar una acción duradera desde CLI, HTTP, MCP, A2A, el bucle aplicación-agente y, posteriormente, un UI.
+- **Haga clic en cualquier cosa en la que normalmente haría clic cuando hay un UI.** Todos los botones, listas, paneles, atajos de teclado: todos llaman a las mismas operaciones que el agente puede llamar.
+- **O simplemente pregunta.** Escribe "responder al correo electrónico de Sara diciendo que estaré allí a las 3" en el agente. Abre el hilo correcto, redacta la respuesta y se la muestra para su aprobación, exactamente como si lo hubiera hecho a mano.
+- **Mira lo que ve.** Abra un correo electrónico y el agente sabrá cuál. Seleccione un gráfico y el agente sabrá qué gráfico. Resalte un párrafo y presione Cmd+I, y el agente actuará solo en ese párrafo.
+- **Obsérvelo funcionar.** A medida que el agente hace cosas (abre vistas, edita borradores, ejecuta informes), el UI se actualiza en tiempo real. Puedes detenerlo, redirigirlo o tomar el control con el mouse en cualquier momento.
+- **Dirigelo como un compañero de equipo.** Da comentarios, pon en cola otra tarea, edita sus instrucciones, audita lo que hizo ayer. Lo recuerda y mejora sus flujos de trabajo con el tiempo.
+
+Esa es la experiencia para la que está diseñado el agente nativo. He aquí por qué la mayoría de los productos no llegan allí.
+
+## Por qué la mayoría de las "aplicaciones de IA" se quedan cortas (El principio de la escalera) {#the-ladder}
+
+Hay una progresión que la mayoría de los equipos suben, muy parecida a una escalera, y la mayoría se detiene un peldaño antes de tiempo.
+
+### Rung 1: una única llamada LLM (el antipatrón) {#rung-one}
+
+Un cuadro de texto envía un mensaje, la IA devuelve una cadena y usted la muestra. Quizás con una ruleta. No hay forma de que el usuario corrija el rumbo, ni de que la IA actúe, ni de ver qué sucedió o por qué.
+
+Esto se ve en todas partes: "funciones de IA" que son básicamente un botón "Resumir" integrado en un producto SaaS. Se ven impresionantes en las demostraciones y se rompen en el momento en que la realidad se complica. Eso no es un producto; eso es un juguete.
+
+### Rung 2: un chat con herramientas {#rung-two}
+
+Ahora la IA puede _hacer cosas_. Tiene herramientas ("borrador de correo electrónico", "buscar contactos", "ejecutar consulta") y una interfaz de chat donde funciona frente a usted, mostrando llamadas a herramientas y resultados a medida que avanza. Así es como se ven Claude, ChatGPT y Cursor bajo el capó.
+
+Este es un verdadero paso adelante. Pero por sí solo, sigue siendo una ventana de chat. No existe un UI adecuado. Sin paneles, sin listas, sin formularios, sin atajos de teclado, sin colaboración en equipo. Si la IA se confunde, te quedarás atrapado reescribiendo en lugar de simplemente hacer clic en el botón derecho. Los no desarrolladores tienen dificultades para realizar un trabajo real en este formato.
+
+### Rung 3: agente + UI como socios iguales {#rung-three}
+
+Esto es nativo del agente. Agrega una aplicación real con todas las funciones alrededor del agente y, lo que es más importante, cada acción que el agente puede realizar es también un botón en el UI, y cada botón en el que hace clic el usuario ejecuta la misma lógica que usa el agente. Una implementación, dos formas de entrar.
+
+Tres cosas cambian cuando llegas al peldaño 3:
+
+- **Dejaste de agregar botones a un chatbot. Agregaste un agente a una aplicación.** Es un producto de mucha mayor calidad en ambos lados.
+- **El agente tiene contexto real.** Ve lo que estás mirando, lo que has seleccionado, lo que acabas de hacer. Escribe en la misma base de datos desde la que lee el UI, por lo que su trabajo se muestra inmediatamente.
+- **Los agentes externos también pueden usarlo.** Otras aplicaciones nativas del agente pueden llamar a este actions a través del [A2A protocol](/docs/a2a-protocol). El código Claude, las aplicaciones MCP personalizadas, Codex, ChatGPT, el cursor y otros hosts MCP pueden controlarlo como un [MCP server](/docs/mcp-protocol). Una aplicación, muchos puntos de entrada.
+
+Ese es el peldaño 3. Es agente nativo.
+
+```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}"
+}
+```
+
+Consulta [Key Concepts — Protocols](/docs/key-concepts#protocols) para ver cómo todo esto depende de la misma definición de acción.
+
+## Por qué todo agente necesita un UI {#why-every-agent-needs-a-ui}
+
+Incluso cuando el agente hace todo el trabajo pesado, los humanos aún necesitan:
+
+- **Mira lo que está haciendo**: progreso, resultado intermedio, lo que tocó
+- **Dirigelo**: envía comentarios, interrumpe y pon en cola la siguiente tarea
+- **Administrelo**: edite sus instrucciones, skills, memoria, trabajos programados, cuentas conectadas
+- **Inspecciona su trabajo**: revisa borradores, audita el historial y revierte errores
+- **Compartir su resultado**: paneles, informes, formularios y enlaces para enviar a los compañeros de equipo
+
+Como mínimo, "un UI para el agente" es un panel de gestión y observabilidad. Como máximo, es una aplicación SaaS completa con el agente integrado como copiloto. Ambos extremos cuentan como agentes nativos y la superficie puede crecer a partir de uno sin necesidad de reescritura.
+
+No tienes que elegir una forma desde el principio. El agente puede funcionar sin cabeza, sentarse detrás de un chat enriquecido o vivir dentro de una aplicación completa alrededor de la misma superficie de acción; consulte [Agent Surfaces](/docs/agent-surfaces) para conocer las formas concretas y API.
+
+## Por qué cada aplicación se beneficia de un agente {#why-every-app-benefits-from-an-agent}
+
+La otra cara es igualmente importante. Los productos SaaS existentes siguen chocando contra el mismo muro: el 80% de lo que necesita funciona muy bien y el 20% simplemente no se puede cambiar. Agregar una barra lateral de chat rara vez soluciona este problema: el chat generalmente no puede _hacer_ las cosas que el UI puede hacer.
+
+El agente nativo cambia eso. Debido a que cada acción en la aplicación se define una vez y se expone como un botón y una herramienta de agente, el agente puede hacer todo lo que los botones pueden hacer (y más) sin un "mundo de IA" separado que mantener. El lenguaje natural se convierte en un insumo de primera clase junto con los clics.
+
+El argumento no es "los agentes reemplazan a UI". Se trata de "**los agentes pertenecen dentro de las aplicaciones, con un UI en la parte superior, como socios iguales**". Incluso una aplicación en la que el agente _es_ el producto aún necesita un UI para que los humanos lo supervisen, configuren y dirijan; consulte [Agent Surfaces — Headless](/docs/agent-surfaces#headless).
+
+## Agente + paridad UI {#agent-ui-parity}
+
+Este es el principio definitorio.
+
+> **Desde UI**: haga clic en botones, complete formularios, navegue por las vistas. El UI escribe en la base de datos; el agente ve los resultados.
+>
+> **Del agente** — lenguaje natural, otros agentes vía A2A, Slack, Telegram. El agente escribe en la base de datos; el UI se actualiza automáticamente.
+
+```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}"
+}
+```
+
+Cuando el agente crea un borrador de correo electrónico, aparece en UI. Cuando hace clic en "Enviar", el agente sabe que fue enviado. No existe un "mundo de agentes" y un "mundo UI" separados: es un solo sistema. Consulte [Key Concepts](/docs/key-concepts) para conocer la arquitectura que hace que esto funcione.
+
+## Personalización normalmente reservada para herramientas eléctricas {#workspace-customization}
+
+La razón por la que herramientas como Claude Code parecen tan poderosas no es el modelo, sino la **capa de personalización**: instrucciones por proyecto, skills, memoria, subagentes y servicios conectados. Puede configurar el agente según su código base, sus preferencias y su equipo.
+
+El agente nativo ofrece a cada usuario la misma capa de personalización, sin tener que salir de la aplicación. Cada aplicación viene con un **espacio de trabajo** personal donde tú (o cualquier miembro de tu equipo) puedes:
+
+- Editar reglas para todo el equipo que leen todos los agentes
+- Permita que el agente recuerde las preferencias automáticamente a medida que las corrige
+- Escribir guías prácticas reutilizables como comandos `/slash`
+- Mantener subagentes personalizados para tareas específicas (invocadas con `@mentions`)
+- Programar trabajos para que se ejecuten en un cron (por ejemplo, "todos los lunes por la mañana, resumir la semana pasada")
+- Conectar servicios externos (Gmail, Stripe, Slack, API internos) a través de servidores MCP por usuario
+
+El giro: todo está almacenado en la base de datos, no en el sistema de archivos. No hay un entorno de desarrollo que poner en marcha, ni un contenedor por usuario. Cada usuario obtiene su propio espacio de trabajo completo (memoria personal, conexiones personales, skills personal) esencialmente gratis, porque son todas las filas de una tabla. Eso es lo que hace que la flexibilidad a nivel de código Claude sea viable dentro de un producto SaaS multiinquilino real.
+
+Consulte [Workspace](/docs/workspace) para conocer el concepto completo.
+
+## Qué lo hace diferente {#what-makes-it-different}
+
+| Enfoque                                         | Descripción                                                                                                                                                |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Aplicaciones tradicionales con IA integrada** | La IA es una idea de último momento. Limitado a autocompletar, resúmenes o una barra lateral de chat que en realidad no puede hacer nada en la aplicación. |
+| **Interfaces puras de chat/agente**             | Poderoso pero inaccesible. Sin paneles, sin flujos de trabajo, sin persistencia. Los que no son desarrolladores no pueden utilizarlos de forma eficaz.     |
+| **Código Claude / Codex para SaaS**             | Excelente para desarrolladores en sus propias máquinas. No se traduce en SaaS multiinquilino: una base de código por usuario en un dev-box no escala.      |
+| **Aplicaciones nativas del agente**             | El agente es un ciudadano de primera clase. Comparte la misma base de datos, el mismo estado y puede hacer todo lo que puede hacer el UI, y viceversa.     |
+
+## Desarrollo de todo el equipo {#whole-team-development}
+
+El agente nativo no es solo para desarrolladores. Debido a que el agente puede editar el propio código de la aplicación, la evolución de una aplicación deja de ser una actividad exclusiva del desarrollador:
+
+- **Los diseñadores** actualizan los diseños directamente en la aplicación en ejecución a través del agente
+- **Los gerentes de producto** agregan funcionalidad y actualizan flujos describiéndolos
+- **QA** prueba la aplicación y le pide al agente que arregle lo que está roto
+- **Cualquier persona del equipo** contribuye a través del lenguaje natural
+
+La visión: menos traspasos, una persona haciendo el trabajo de un equipo pequeño.
+
+## Bifurcar y personalizar {#fork-and-customize}
+
+Las aplicaciones nativas del agente siguen un modelo de bifurcación y personalización. Comienza desde una **plantilla** (calendario, contenido, diapositivas, análisis, correo, clips, diseño, formularios, envío) y la hace suya. Cada uno es un producto SaaS completo y funcional que se vende al por mayor, no un andamio en blanco:
+
+1. Elija una plantilla en [agent-native.com/templates](/templates)
+2. Úselo inmediatamente como una aplicación alojada (por ejemplo, mail.agent-native.com)
+3. Búsquelo cuando desee personalizar: "conectar nuestra cuenta de Stripe", "agregar un gráfico de cohortes"
+4. El agente modifica el código para adaptarlo a sus necesidades
+5. Implemente su bifurcación en su propio dominio o permanezca en agent-native.com
+
+Debido a que es _su_ aplicación, no una infraestructura compartida, el agente puede desarrollar el código de manera segura. Tu aplicación sigue mejorando a medida que la usas. Consulte [Templates](/docs/cloneable-saas) para conocer la historia completa.
+
+¿No estás listo para bifurcar una plantilla completa? También puede probar el agente nativo agregando una **habilidad** a un agente de codificación que ya usa: instale la habilidad Planes con `npx @agent-native/core@latest skills add visual-plan`. Ver el [Skills Guide](/docs/skills-guide#app-backed-skills).
+
+## Agentes componibles {#composable-agents}
+
+Las aplicaciones nativas del agente pueden comunicarse entre sí. Desde dentro de la aplicación de correo, puede etiquetar al agente de análisis para consultar datos e incluir el resultado en un borrador de correo electrónico. Los agentes descubren qué otros agentes están disponibles, se reparten el trabajo entre ellos y muestran los resultados en el UI en el que ya se encuentra.
+
+Esto funciona con [A2A](/docs/a2a-protocol) y [MCP](/docs/mcp-protocol) bajo el capó (misma definición, múltiples superficies), pero como usuario, todo lo que tienes que saber es "Puedo pedir ayuda a cualquiera de mis aplicaciones con cualquier cosa que puedan hacer".
+
+## ¿Cómo se ve esto en el código? {#what-does-it-look-like-in-code}
+
+Si está creando o ampliando una aplicación nativa del agente, este es el patrón central: cada operación en la aplicación es una **acción**, definida una vez, disponible tanto para el agente como para el 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 />;
+```
+
+Una acción, muchas superficies: el agente lo llama como una herramienta, el UI lo llama como una mutación con seguridad de tipos, el [native chat](/docs/native-chat-ui) puede generar resultados explícitos del widget, los agentes externos acceden a él a través de [A2A](/docs/a2a-protocol) y los hosts de MCP lo llaman a través del [MCP server](/docs/mcp-protocol) de la aplicación, opcionalmente con los recursos UI de las aplicaciones MCP y el MCP remoto estándar OAuth. manejado por el marco. Consulte [Actions](/docs/actions) para obtener la referencia completa.
+
+## ¿Qué sigue? {#whats-next}
+
+- [**Getting Started**](/docs/getting-started): empieza con una acción, elige una plantilla o instala una habilidad
+- [**Agent Surfaces**](/docs/agent-surfaces): elige chat enriquecido sin cabeza, sidecar integrado o aplicación completa
+- [**Key Concepts**](/docs/key-concepts): la arquitectura: SQL, actions, sincronización de sondeo, reconocimiento del contexto, portabilidad
+- [**Templates**](/docs/cloneable-saas): plantillas como productos completos de tu propiedad
+- [**Workspace**](/docs/workspace): la capa de personalización por usuario (skills, memoria, instrucciones, MCP) respaldada por SQL, no archivos
+- [**Dispatch**](/docs/dispatch): plano de control del espacio de trabajo: bóveda de secretos, Slack/bandeja de entrada de correo electrónico, delegación entre aplicaciones
+- [**Extensions**](/docs/extensions): miniaplicaciones en espacio aislado que el agente crea instantáneamente sin cambios de código
+- [**Drop-in Agent**](/docs/drop-in-agent): monta `<AgentPanel>` en cualquier aplicación React