@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/agent-teams.md

@@ -0,0 +1,171 @@
+---
+title: "Equipos de agentes"
+description: "Los agentes principales delegados trabajan con subagentes que se ejecutan en sus propios hilos y aparecen como chips de vista previa en vivo en línea en el chat."
+---
+
+# Equipos de agentes
+
+El chat del agente es un **orquestador**, no un monolito. Cuando el agente principal realiza una tarea que es mejor que la realice un especialista ( "escribir este correo electrónico con mi voz", "ejecutar un análisis de BigQuery", "revisar este PR"), genera un subagente en su propio hilo, herramientas y contexto. El subagente aparece como un **chip** de vista previa en vivo en línea en el chat principal; haz clic en él para abrir la conversación completa como una pestaña.
+
+Esto mantiene enfocado el hilo principal, permite que los subagentes se ejecuten en paralelo y le brinda un seguimiento de auditoría limpio para cualquier trabajo delegado.
+
+Agent Teams se ejecuta en el administrador de ejecución principal: los eventos se transmiten y persisten, las cancelaciones se propagan a través de SQL y las tareas sobreviven a los inicios en frío sin servidor.
+
+## El modelo mental {#mental-model}
+
+- **Chat principal**: el orquestador. Lee su solicitud, delegados. Rara vez se realiza un trabajo pesado en sí.
+- **Subagentes**: se ejecutan con su propio hilo, su propio indicador del sistema y su propio conjunto de herramientas. Cada uno se asigna a un perfil de "agente personalizado" en [workspace](/docs/workspace).
+- **Chips**: la tarjeta de vista previa enriquecida que aparece en línea en el chat principal y muestra el paso actual del subagente, el resultado de la transmisión y el resumen final. Contraído de forma predeterminada; se expande a la conversación completa al hacer clic.
+- **Mensajería bidireccional**: el agente principal puede enviar seguimientos a un subagente en ejecución; un subagente puede responder un mensaje cuando llega a un punto ambiguo.
+
+El estado del subagente persiste en la tabla `application_state` SQL (bajo `agent-task:<taskId>`), por lo que las tareas sobreviven a los arranques en frío sin servidor y funcionan en múltiples procesos.
+
+```an-diagram title="Orchestrator and specialists" summary="The main chat delegates to sub-agents that run in their own threads and report back as inline chips."
+{
+  "html": "<div class=\"at-orc\"><div class=\"diagram-card main\"><span class=\"diagram-pill accent\">Main chat</span><small class=\"diagram-muted\">orchestrator &mdash; reads your request, delegates</small></div><div class=\"at-fan\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"at-subs\"><div class=\"diagram-box\">Code review<br><small class=\"diagram-muted\">own thread &amp; prompt</small></div><div class=\"diagram-box\">BigQuery analysis<br><small class=\"diagram-muted\">own tools</small></div><div class=\"diagram-box\">Email in voice<br><small class=\"diagram-muted\">own context</small></div></div></div><div class=\"diagram-pill\">each appears inline as a live chip &#8635;</div></div>",
+  "css": ".at-orc{display:flex;flex-direction:column;align-items:center;gap:12px}.at-orc .diagram-card{padding:14px 18px;display:flex;flex-direction:column;gap:4px;align-items:center}.at-orc .at-fan{display:flex;flex-direction:column;align-items:center;gap:8px}.at-orc .diagram-arrow{font-size:22px}.at-orc .at-subs{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.at-orc .diagram-box{text-align:center}"
+}
+```
+
+## Cuándo generar un subagente {#when-to-spawn}
+
+Aparece cuando la tarea:
+
+- Necesita un **mensaje del sistema** diferente (una voz o tono especializado, por ejemplo, "revisión de código").
+- Tiene una cadena de herramientas **de larga duración** que contaminaría el contexto principal.
+- Se puede ejecutar **en paralelo** con otro trabajo que esté realizando el agente principal.
+- Es propiedad de un **equipo diferente** que ya tiene un perfil de agente personalizado.
+
+No generes trabajos triviales de una sola vez: invoca la acción directamente.
+
+## Invocar a un subagente {#invoking}
+
+Tres formas de iniciar un subagente, de menos a más explícita:
+
+### 1. `@mention` un agente personalizado {#mention}
+
+El usuario escribe `@agent-name` en el compositor del chat. Aparece un menú desplegable de subagentes del espacio de trabajo. Al seleccionar uno se inserta un chip; Al enviar, el agente principal delega el mensaje a ese subagente.
+
+Los agentes personalizados viven en el espacio de trabajo de `agents/<slug>.md`: un archivo Markdown con contenido frontal de YAML. Consulte [Custom Agents](/docs/workspace#custom-agents) para conocer el formato.
+
+### 2. El agente principal delega automáticamente {#auto-delegate}
+
+El marco le brinda al agente principal una herramienta `agent-teams`. Cuando el modelo decide que una tarea se ajusta a un perfil de subagente registrado, llama a la herramienta con `action: "spawn"` y un parámetro `agent` opcional que nombra un perfil de `agents/*.md`. Aparece un chip; corre el subagente. El agente principal espera (o avanza en paralelo) e incorpora el resultado cuando finaliza el subagente.
+
+El conjunto de acciones completo de `agent-teams` es:
+
+| Acción        | Propósito                                          |
+| ------------- | -------------------------------------------------- |
+| `spawn`       | Iniciar una nueva tarea de subagente               |
+| `status`      | Verificar el progreso de un subagente en ejecución |
+| `read-result` | Obtener el resultado final de un subagente         |
+| `send`        | Enviar mensajes a un subagente en ejecución        |
+| `list`        | Ver todas las tareas del usuario actual            |
+
+### 3. Generación programática {#programmatic-spawn}
+
+Para integraciones a nivel de marco, utilice `spawnTask()` de `@agent-native/core/server`:
+
+```ts
+import { spawnTask } from "@agent-native/core/server";
+
+const task = await spawnTask({
+  description: "Draft an outreach email to this lead",
+  instructions: "Match Steve's voice from memory/MEMORY.md.",
+  ownerEmail: user.email,
+  systemPrompt: mailAgentSystemPrompt,
+  actions: mailActions,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
+  parentSend: emit, // streaming sender for the parent chat response
+});
+```
+
+La mayoría del código de la aplicación no llama a esto directamente; el marco lo hace de forma interna para `@mentions` y para la herramienta `agent-teams`. Utilice `spawnTask()` solo cuando esté cableando un nuevo punto de entrada (por ejemplo, un botón que inicia un trabajo en segundo plano que se ejecuta como un subagente).
+
+## Ciclo de vida de la tarea {#lifecycle}
+
+```an-diagram title="What spawnTask() does" summary="Each spawn creates a thread, persists state to SQL, and streams chip events through to completion."
+{
+  "html": "<div class=\"at-life\"><div class=\"diagram-box\"><code>spawnTask()</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">create thread</span><small class=\"diagram-muted\">new row in <code>chat_threads</code>, description as first message</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">persist state</span><small class=\"diagram-muted\"><code>agent-task:&lt;id&gt;</code> &rarr; <code>application_state</code>, status=running</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">stream</span><small class=\"diagram-muted\"><code>agent_task_started</code> &rarr; chip appears; <code>agent_task_step</code> &rarr; chip updates live</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">complete</span><small class=\"diagram-muted\">status=completed, write summary + preview, emit <code>agent_task_done</code></small></div></div>",
+  "css": ".at-life{display:flex;flex-direction:column;align-items:stretch;gap:6px;max-width:560px}.at-life .diagram-card{display:flex;flex-direction:column;gap:3px;padding:10px 14px}.at-life .diagram-box{align-self:flex-start}.at-life .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+En cualquier momento, el agente principal puede reanudar al subagente con un seguimiento a través de `sendToTask(taskId, message)`. Si el subagente comete un error, `markTaskErrored(taskId, reason)` registra el error y se lo muestra al usuario.
+
+La mensajería bidireccional es duradera. Los seguimientos de los padres para ejecutar subagentes son
+entregado a lo largo del ciclo de vida de la tarea; si el subagente no puede consumirlos en
+el paso actual, deben permanecer en cola y aplicarse en un lugar seguro
+punto de continuación. Los subagentes también pueden enviar mensajes cuando necesiten una aclaración
+en lugar de bloquear de forma invisible.
+
+## Estado de la tarea de lectura {#reading-state}
+
+Desde el código del servidor u otro actions:
+
+```ts
+import { getTask, listTasks } from "@agent-native/core/server";
+
+const task = await getTask(taskId); // single task
+const tasks = await listTasks(); // all tasks for the user (sorted newest first)
+```
+
+Campos clave `AgentTask`:
+
+```ts
+interface AgentTask {
+  taskId: string;
+  threadId: string;
+  description: string;
+  status: "running" | "completed" | "errored";
+  preview: string; // short one-liner for the chip
+  summary: string; // full summary once completed
+  currentStep: string; // latest step label (updated while running)
+  createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
+}
+```
+
+## Perfiles de agentes personalizados {#profiles}
+
+Los subagentes se asignan a perfiles de agentes personalizados: archivos Markdown en `agents/<slug>.md` en el espacio de trabajo que aparecen en el menú desplegable `@mention` y sirven como objetivos de delegación. [Workspace — Custom Agents](/docs/workspace#custom-agents) posee el formato completo (frontmatter, `tools`, `delegate-default`, anulaciones de modelos).
+
+## Profundizador de delegación {#depth-guard}
+
+Los subagentes pueden generar subagentes, lo que supone un riesgo descontrolado/de costes: una cadena ilimitada de delegaciones podría desplegarse indefinidamente. El marco impone un **límite estricto en la profundidad de la delegación**, en el lado del servidor, independientemente de cualquier protección a nivel de herramienta.
+
+El chat de nivel superior es el de profundidad `0`. Un subagente que genera es la profundidad `1`; ese subagente puede aparecer una vez más (profundidad `2`); se **rechaza** un engendro que crearía un subagente de profundidad-`3`. El límite predeterminado es **2**.
+
+```an-diagram title="Delegation depth guard (default cap 2)" summary="Each level may spawn one deeper until the cap; a spawn past it is refused server-side."
+{
+  "html": "<div class=\"at-depth\"><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 0</span><strong>Top-level chat</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 1</span><strong>Sub-agent</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card warn\"><span class=\"diagram-pill warn\">depth 2</span><strong>Sub-agent's sub-agent</strong><small class=\"diagram-muted\">at the cap &mdash; may NOT spawn</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">depth 3</span><strong>Refused</strong><small class=\"diagram-muted\">server-side error</small></div></div>",
+  "css": ".at-depth{display:flex;flex-direction:column;gap:8px}.at-depth .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.at-depth .rung-1,.at-depth .diagram-card:nth-child(2){margin-inline-start:24px}.at-depth .diagram-card:nth-child(3){margin-inline-start:48px}.at-depth .diagram-card:nth-child(4){margin-inline-start:72px}"
+}
+```
+
+La aplicación de la ley es ambiental: cada subagente se ejecuta dentro de un `AsyncLocalStorage` que registra su propia profundidad, por lo que cualquier `spawnTask` alcanzado transitivamente desde esa ejecución lee la profundidad de su padre y se niega una vez que se alcanza el límite, incluso si la herramienta `agent-teams` se entregó a un subagente que no debería haberla tenido. La decisión se expone como un `evaluateSubagentDepth(parentDepth)` puro y comprobable por unidad. Una generación rechazada devuelve un error claro: _"Límite de profundidad de delegación alcanzado (N máx.); no se puede generar otro subagente."_
+
+### Configurando el límite {#depth-guard-config}
+
+Anule el valor predeterminado en el momento de la implementación con `AGENT_NATIVE_MAX_SUBAGENT_DEPTH`:
+
+| Valor             | Efecto                                                                                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| _(desarmado)_     | Límite predeterminado de `2`.                                                                                                                                            |
+| `0`               | **No se pueden generar subagentes**: el agente de nivel superior hace todo el trabajo.                                                                                   |
+| `1`…`16`          | Tantos niveles de delegación.                                                                                                                                            |
+| no válido / `>16` | Un valor no entero/negativo/NaN vuelve a `2`; todo lo que esté por encima de `16` se fija en `16`, por lo que un error tipográfico nunca podrá desactivar la protección. |
+
+```bash
+AGENT_NATIVE_MAX_SUBAGENT_DEPTH=1   # sub-agents allowed, but they can't sub-delegate
+```
+
+Cuando un subagente está en el límite o por debajo de él, el marco inyecta una línea en su contexto de tiempo de ejecución que le indica qué tan profundo se encuentra y si puede delegar más, de modo que el modelo gaste su presupuesto de manera adecuada.
+
+## ¿Qué sigue?
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — el formato del perfil
+- [**A2A Protocol**](/docs/a2a-protocol): cuando el "subagente" vive en una aplicación completamente diferente
+- [**Actions**](/docs/actions): las herramientas a las que recurre un subagente

package/docs/content/locales/es-ES/agent-web-surfaces.md

@@ -0,0 +1,161 @@
+---
+title: "Web de agente público"
+description: "Haga que los agentes puedan rastrear, leer, citar y, opcionalmente, llamar las rutas públicas: robots.txt, llms.txt, espejos de rebajas, JSON-LD y una superficie pública MCP."
+---
+
+# Web del agente público
+
+La web pública de agentes facilita que los agentes rastreen, lean, citen y llamen las rutas públicas Agent-Native. El objetivo no es hacer públicos todos los puntos finales de las aplicaciones. El objetivo es publicar una superficie pública limpia para las páginas que ya son públicas, manteniendo al mismo tiempo los datos privados y el acceso a las herramientas detrás de controles explícitos.
+
+El sitio de documentos es la implementación de referencia. Hoy se envía:
+
+- `/robots.txt` con una política de rastreador que permite la recuperación pero no permite el entrenamiento de forma predeterminada.
+- `/sitemap.xml` con URL canónicos absolutos y `lastmod` cuando el archivo fuente lo expone.
+- `/llms.txt` y `/llms-full.txt` para un descubrimiento de contenido fácil de usar para los agentes.
+- Espejos Markdown como `/docs/getting-started.md`.
+- Respuestas `Accept: text/markdown` para páginas de documentos públicos después de una compilación de producción.
+- JSON-LD para metadatos de página, sitio web y organización base.
+- Una auditoría CLI (`npx @agent-native/core@latest audit-agent-web`) que comprueba todo lo anterior.
+
+La configuración de `publicMcp: true` también expone el actions habilitado como punto final público de MCP, lo que permite a los agentes externos llamarlos directamente (consulte [MCP Protocol](/docs/mcp-protocol)).
+
+```an-diagram title="What a public route publishes" summary="A public route fans out into agent-friendly representations. Reading the route is separate from calling tools — tool access stays opt-in."
+{
+  "html": "<div class=\"diagram-web\"><div class=\"diagram-box\" data-rough>Public route<br><small class=\"diagram-muted\">derived from route access settings</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">robots.txt</span><span class=\"diagram-pill\">sitemap.xml</span><span class=\"diagram-pill\">llms.txt</span><span class=\"diagram-pill\">.md mirror</span><span class=\"diagram-pill\">JSON-LD</span><span class=\"diagram-pill\">text/markdown</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col gate\"><span class=\"diagram-pill warn\">Tools stay private</span><small class=\"diagram-muted\">publicMcp + publicAgent.expose required</small></div></div>",
+  "css": ".diagram-web{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-web .diagram-arrow{font-size:22px;line-height:1}.diagram-web .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.diagram-web .gate{display:flex;flex-direction:column;gap:4px;align-items:flex-start}"
+}
+```
+
+## Configuración {#config}
+
+Agregue `agentWeb` en la configuración de la aplicación del espacio de trabajo existente (en el `package.json` de su aplicación con la clave `agent-native`, o de manera equivalente, `workspace.agentWeb`, `agentWeb` o `root.agentWeb`). La lista de rutas públicas todavía se deriva de la configuración de acceso a rutas de la aplicación; `agentWeb` controla cómo se representa esa superficie pública ante los agentes.
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin/*"],
+      "agentWeb": {
+        "discoverable": true,
+        "markdownTwins": true,
+        "llmsTxt": true,
+        "jsonLd": true,
+        "publicAgentCard": true,
+        "publicMcp": false,
+        "crawlerPolicy": "discoverable-no-training",
+        "crawlers": {
+          "training": "disallow",
+          "search": "allow",
+          "userTriggered": "allow",
+          "codingAgents": "allow",
+          "autonomousAgents": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+Para la mayoría de las aplicaciones, no modifique los valores predeterminados. Si una aplicación tiene alguna ruta pública, `discoverable` está activado de forma predeterminada. La política de rastreo predeterminada es "detectable, no entrenable": se permiten la búsqueda, la recuperación activada por el usuario, los agentes de codificación y los agentes de navegación autónomos; Los rastreadores de entrenamiento no están permitidos.
+
+## Ruta fuente de la verdad {#route-source}
+
+El descubrimiento web del agente sigue el modelo de acceso a rutas:
+
+- Las aplicaciones públicas exponen todas las rutas excepto `protectedPaths`.
+- Las aplicaciones internas exponen solo `publicPaths`.
+- Los agentes pueden leer las páginas de formularios y recursos compartidos públicos.
+- Los datos privados enviados, los paneles autenticados y el estado del usuario/organización nunca se incluyen solo porque una página cercana es pública.
+
+Esto mantiene naturales las aplicaciones mixtas. Una aplicación de formularios puede exponer una página de formulario pública y mantener los envíos privados. Una aplicación de contenido puede exponer publicaciones publicadas y mantener la privacidad del editor. Un sitio de documentos puede exponer todo excepto las herramientas de administración.
+
+## Las páginas públicas no son herramientas públicas {#public-tools}
+
+El acceso a la página pública y el acceso a las herramientas públicas están separados. Que una ruta sea pública únicamente significa que los agentes pueden leer esa ruta como HTML, Markdown, entradas de mapas del sitio, entradas de llms y datos estructurados.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "**A public page is not a public tool.** Making a route crawlable never exposes an action. Tool access requires an explicit `publicAgent.expose` opt-in on the action *and* `publicMcp: true` on the app."
+}
+```
+
+Para exponer una acción a través de un protocolo de agente público, la acción debe optar por:
+
+```an-annotated-code title="Opting one safe action onto the public surface"
+{
+  "filename": "actions/search-docs.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Search published docs\",\n  readOnly: true,\n  publicAgent: {\n    expose: true,\n    readOnly: true,\n    requiresAuth: false,\n    isConsequential: false,\n    title: \"Search published docs\",\n  },\n  run: async (args) => {\n    // ...\n  },\n});",
+  "annotations": [
+    { "lines": "4", "label": "Explicit opt-in", "note": "Without `publicAgent.expose === true`, the action never appears on any public agent surface — no matter how public its routes are." },
+    { "lines": "5-7", "label": "Self-describe safety", "note": "Mark it read-only, declare whether it needs auth, and flag whether it is consequential. Public MCP excludes consequential/write actions unless policy explicitly allows them." }
+  ]
+}
+```
+
+`agentWeb.publicMcp` permanece `false` de forma predeterminada. Cuando el MCP público está habilitado, el servidor debe exponer solo actions con `publicAgent.expose === true` y aún debe excluir el consecuente o escribir actions a menos que la acción y la política de autenticación lo permitan explícitamente.
+
+## Archivos en tiempo de compilación {#build-time}
+
+Las utilidades de Framework en `@agent-native/core/agent-web` generan los archivos comunes a partir de una lista de páginas:
+
+```ts
+import {
+  buildAgentWebStaticFiles,
+  normalizeAgentWebConfig,
+} from "@agent-native/core/agent-web";
+
+const config = normalizeAgentWebConfig(
+  { crawlerPolicy: "discoverable-no-training" },
+  { hasPublicRoutes: true },
+);
+
+const files = buildAgentWebStaticFiles({
+  siteName: "My Agent-Native App",
+  siteUrl: "https://example.com",
+  description: "Public docs for my app.",
+  config,
+  pages: [
+    {
+      path: "/docs",
+      title: "Docs",
+      description: "Start here.",
+      markdown: "# Docs\n\nStart here.\n",
+      markdownPath: "/docs/getting-started.md",
+      lastmod: new Date(),
+    },
+  ],
+});
+```
+
+Las aplicaciones Vite pueden usar `createAgentWebVitePlugin` de `@agent-native/core/vite` para escribir esos archivos en `public`, `dist`, `dist/client`, `dist/server/public` o `build/client` durante las compilaciones de producción.
+
+## Auditar un sitio {#audit}
+
+Utilice la auditoría CLI en un sitio implementado o en un servidor de producción local:
+
+```bash
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
+```
+
+La auditoría comprueba:
+
+- SSR-visible HTML.
+- URL canónicos.
+- JSON-LD.
+- Política `robots.txt` y mapa del sitio absoluto URL.
+- Entradas absolutas del mapa del sitio.
+- `/llms.txt` y `/llms-full.txt`.
+- Espejos Markdown.
+- `Accept: text/markdown`.
+- No se permiten bloqueos 401/403 accidentales para agentes de usuario de recuperación de agentes comunes.
+
+La auditoría finaliza con un valor distinto de cero si falta una superficie pública requerida.
+
+## ¿Qué sigue?
+
+- [**Actions**](/docs/actions): cómo incluir a actions en el protocolo de agente público
+- [**MCP Protocol**](/docs/mcp-protocol): la superficie MCP que habilita `publicMcp: true`
+- [**Deployment**](/docs/deployment): dónde se escriben estos archivos estáticos durante las compilaciones

package/docs/content/locales/es-ES/audit-log.md

@@ -0,0 +1,111 @@
+---
+title: "Registro de auditoría"
+description: "Un registro duradero, solo para agregar, de quién cambió qué datos de la aplicación, cuándo y si fue usted o el agente, capturado automáticamente en la unión de acción."
+---
+
+# Registro de auditoría
+
+Cada aplicación nativa del agente obtiene un registro de auditoría listo para usar: un registro duradero, completo, con alcance de acceso y solo para agregar de **quién mutó qué datos de la aplicación, cuándo, desde dónde y (cuándo fue el agente) en qué ejecución.** La captura es automática en el punto de acción; no escribes ningún código para ello.
+
+Debido a que el agente puede cambiar los datos en su nombre, la pregunta principal que responde un registro de auditoría aquí no es solo "quién editó este registro", sino **"¿fui yo o el agente, y qué turno lo causó?"** Ningún otro sistema en el marco puede responder eso.
+
+## Auditoría versus observabilidad versus seguimiento {#which}
+
+Tres sistemas registran "lo que sucedió", por tres razones diferentes. Elija según la pregunta que esté haciendo:
+
+| Sistema                                  | La pregunta que responde                               | Fidelidad                            | Audiencia                                |
+| ---------------------------------------- | ------------------------------------------------------ | ------------------------------------ | ---------------------------------------- |
+| **Registro de auditoría** (esta página)  | "¿Quién cambió este registro, cuándo y fue el agente?" | **Completo, duradero y con alcance** | Usuario, administrador, el propio agente |
+| **[Observability](/docs/observability)** | "¿Por qué el agente hizo eso y cuánto costó?"          | Telemetría de tramo muestreado       | Desarrollador                            |
+| **[Tracking](/docs/tracking)**           | "¿Cómo utiliza la gente el producto?"                  | Dispare y olvídese en SaaS externo   | PM / crecimiento                         |
+
+Un registro de auditoría que se muestrea o se envía a un proveedor de análisis es inútil; la cuestión es que sea completo, local y consultable. Por lo tanto, es su propio subsistema, no un modo de los otros dos.
+
+## Qué se captura automáticamente {#captured}
+
+Cuando se ejecuta cualquier acción **mutante** (cualquier cosa que no sea un `GET` de solo lectura), el marco agrega una fila a `agent_audit_log` con:
+
+- **Acción**: el nombre de la acción (por ejemplo, `delete-recording`).
+- **Actor**: `agent`, `human` o `system`, más el correo electrónico del actor, completado **incluso para llamadas de agentes**, por lo que obtienes "el agente, que actúa para alice@,...".
+- **Ejecutar vínculo**: el agente `threadId` / `turnId` que activó la llamada (una llamada de herramienta), por lo que una mutación se remonta al turno exacto del agente.
+- **Superficie**: `tool` (agente), `frontend`, `http`, `cli`, `mcp` o `a2a`.
+- **Resultado**: `success`, `error` (con un código de error) o `denied` (bloqueado por una puerta de aprobación humana).
+- **Entradas**: los argumentos de llamada, con valores en forma de credencial [redacted](#privacy).
+- **Objetivo y propietario**: el recurso que cambió la acción, utilizado para [scope reads](#reading).
+
+No se necesita cableado: la captura se engancha en `defineAction` de forma transparente. Se omiten los actions de solo lectura y algunos actions del marco de alta frecuencia (sincronización de estado de aplicación, rayos X de contexto, navegación) se omiten de forma predeterminada para evitar inundar el registro.
+
+## Declarar qué cambió una acción {#target}
+
+De forma predeterminada, un evento tiene como alcance el **actor**: usted ve sus propios cambios y los cambios del agente en su nombre. Para realizar un cambio en un recurso _compartido_ que también aparezca en el registro del **propietario** y para etiquetar eventos por recurso, declare un `target`:
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({
+      type: "recording",
+      id: args.id,
+      // Optional — defaults to the actor. Set when editing someone else's resource.
+      ownerEmail: result?.ownerEmail,
+      visibility: "org",
+    }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+Todo en `audit` es opcional. La adición mínima útil es `target: () => ({ type, id })`.
+
+### Captura de ajuste {#tuning}
+
+| Opción               | Efecto                                                                     |
+| -------------------- | -------------------------------------------------------------------------- |
+| `audit.target`       | Etiquete el evento con el recurso y el alcance lee a su propietario.       |
+| `audit.summary`      | Una breve línea legible por humanos para el evento.                        |
+| `audit.onRead`       | Auditar una **lectura** confidencial (acceso secreto, exportación masiva). |
+| `audit.enabled`      | `true` fuerza la captura; `false` excluye una mutación ruidosa.            |
+| `audit.recordInputs` | `false` omite la captura de los argumentos (ya redactados).                |
+
+## Leyendo el rastro {#reading}
+
+Hay dos lecturas actions disponibles para el agente **y** la interfaz de cada aplicación, con alcance en SQL para la persona que llama; nunca devuelven las filas de otro inquilino:
+
+- **`list-audit-events`** — filtrar por `targetType` / `targetId`, `actorKind` (`agent` | `human` | `system`), `status`, `threadId` / `turnId`, `action`, `sinceMs` y `limit`.
+- **`get-audit-event`**: un evento por ID, incluida su carga útil de entrada redactada.
+
+Cree una fuente de actividad o una línea "quién cambió esto" llamando a `list-audit-events` desde UI con `useActionQuery`; nunca escriba a mano una búsqueda en la tabla de auditoría:
+
+```tsx
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data } = useActionQuery("list-audit-events", {
+  targetType: "recording",
+  targetId: recordingId,
+});
+// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
+```
+
+El agente puede realizar la misma acción: preguntarle "¿qué cambiaste en esta grabación?" y responde desde el rastro.
+
+## Privacidad y retención {#privacy}
+
+- **Redacción**: antes de almacenar cualquier entrada, se eliminan las claves y valores en forma de credenciales (tokens, secretos, contraseñas, cadenas de portador) y se truncan las cargas útiles de gran tamaño. El registro de auditoría nunca se convierte en un almacén secundario de secretos. Mantenga también el texto `summary` libre de datos confidenciales.
+- **Solo agregar**: no hay ninguna acción de actualización o eliminación para las filas de auditoría. La única eliminación es la eliminación de retención, lo que hace que el registro sea confiable como pista de auditoría.
+- **Aislamiento de inquilinos**: las lecturas tienen como alcance la identidad y la organización de la persona que llama; sin identidad, nada coincide.
+
+Configurar a través del entorno:
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS`: cuánto tiempo se conservan las filas (predeterminado `365`; `0` = conservar para siempre).
+- `AGENT_NATIVE_AUDIT_ENABLED=false`: desconexión global.
+
+## ¿Qué sigue?
+
+- [**Actions**](/docs/actions): la costura `defineAction` donde se produce la captura
+- [**Human-in-the-Loop Approvals**](/docs/human-approval): actions cerrado, registrado como `denied`
+- [**Security & Data Scoping**](/docs/security): la auditoría del modelo de propiedad dice reutilización
+- [**Observability**](/docs/observability): telemetría ejecutada por el agente (el otro "qué pasó")