@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/agent-teams.md

@@ -0,0 +1,171 @@
+---
+title: "Équipes d'agents"
+description: "Les délégués de l'agent principal travaillent auprès des sous-agents qui s'exécutent dans leurs propres fils de discussion et apparaissent sous forme de puces d'aperçu en direct dans le chat."
+---
+
+# Équipes d'agents
+
+Le chat de l'agent est un **orchestrateur**, pas un monolithe. Lorsque l'agent principal exécute une tâche qui relève mieux d'un spécialiste – « écrire cet e-mail avec ma voix », « exécuter une analyse BigQuery », « examiner ce PR » - il génère un sous-agent dans son propre fil de discussion, ses propres outils et son propre contexte. Le sous-agent apparaît sous la forme d'une **puce** d'aperçu en direct en ligne dans le chat principal ; cliquez dessus pour ouvrir la conversation complète sous forme d'onglet.
+
+Cela permet de garder le thread principal concentré, de permettre aux sous-agents de s'exécuter en parallèle et de vous fournir une piste d'audit claire pour tout travail délégué.
+
+Agent Teams s'exécute sur le gestionnaire d'exécution principal : les événements sont diffusés et persistants, les abandons se propagent via SQL et les tâches survivent aux démarrages à froid sans serveur.
+
+## Le modèle mental {#mental-model}
+
+- **Chat principal** — l'orchestrateur. Lit votre demande, délégués. Il est rare qu'un travail pénible lui-même soit réalisé.
+- **Sous-agents** : exécutés avec leur propre thread, leur propre invite système, leur propre ensemble d'outils. Chacun correspond à un profil « agent personnalisé » dans le [workspace](/docs/workspace).
+- **Chips** — la carte d'aperçu riche qui apparaît en ligne dans le chat principal, montrant l'étape actuelle du sous-agent, la sortie en streaming et le résumé final. Réduit par défaut ; se développe en une conversation complète en un seul clic.
+- **Messagerie bidirectionnelle** — l'agent principal peut envoyer des suivis à un sous-agent en cours d'exécution ; un sous-agent peut répondre lorsqu'il atteint un point ambigu.
+
+L'état du sous-agent est conservé dans la table `application_state` SQL (sous `agent-task:<taskId>`), de sorte que les tâches survivent aux démarrages à froid sans serveur et fonctionnent sur plusieurs processus.
+
+```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}"
+}
+```
+
+## Quand générer un sous-agent {#when-to-spawn}
+
+Apparaître lorsque la tâche :
+
+- Nécessite une **invite système** différente (une voix ou un ton spécialisé, par exemple « révision du code »).
+- Possède une chaîne d'outils **de longue durée** qui polluerait le contexte principal.
+- Peut s'exécuter **en parallèle** avec d'autres tâches effectuées par l'agent principal.
+- appartient à une **équipe différente** qui dispose déjà d'un profil d'agent personnalisé.
+
+Ne vous lancez pas pour un travail ponctuel trivial : appelez l'action directement.
+
+## Invoquer un sous-agent {#invoking}
+
+Trois façons de lancer un sous-agent, de la moins explicite à la plus explicite :
+
+### 1. `@mention` un agent personnalisé {#mention}
+
+L'utilisateur saisit `@agent-name` dans le composeur de chat. Une liste déroulante des sous-agents de l'espace de travail apparaît. En sélectionner un insère une puce ; Lors de la soumission, l'agent principal délègue le message à ce sous-agent.
+
+Les agents personnalisés se trouvent dans l'espace de travail de `agents/<slug>.md` : un fichier Markdown avec le thème principal YAML. Voir [Custom Agents](/docs/workspace#custom-agents) pour le format.
+
+### 2. L'agent principal délègue automatiquement {#auto-delegate}
+
+Le framework donne à l'agent principal un outil `agent-teams`. Lorsque le modèle décide qu'une tâche correspond à un profil de sous-agent enregistré, il appelle l'outil avec `action: "spawn"` et un paramètre `agent` facultatif nommant un profil de `agents/*.md`. Une puce apparaît ; le sous-agent s'exécute. L'agent principal attend (ou avance en parallèle) et intègre le résultat lorsque le sous-agent a terminé.
+
+L'ensemble complet d'actions `agent-teams` est :
+
+| Action        | Objectif                                                     |
+| ------------- | ------------------------------------------------------------ |
+| `spawn`       | Démarrer une nouvelle tâche de sous-agent                    |
+| `status`      | Vérifier la progression d'un sous-agent en cours d'exécution |
+| `read-result` | Obtenir le résultat d'un sous-agent terminé                  |
+| `send`        | Envoyer un message à un sous-agent en cours d'exécution      |
+| `list`        | Voir toutes les tâches de l'utilisateur actuel               |
+
+### 3. Apparition programmatique {#programmatic-spawn}
+
+Pour les intégrations au niveau du framework, utilisez `spawnTask()` à partir 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 plupart des codes d'application n'appellent pas cela directement : le framework le fait sous le capot pour `@mentions` et pour l'outil `agent-teams`. Accédez à `spawnTask()` uniquement lorsque vous connectez un nouveau point d'entrée (par exemple, un bouton qui lance une tâche en arrière-plan qui s'exécute en tant que sous-agent).
+
+## Cycle de vie des tâches {#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}"
+}
+```
+
+À tout moment, l'agent parent peut reprendre le sous-agent avec un suivi via `sendToTask(taskId, message)`. En cas d'erreur du sous-agent, `markTaskErrored(taskId, reason)` enregistre l'échec et le signale à l'utilisateur.
+
+La messagerie bidirectionnelle est durable. Les suivis des parents pour les sous-agents en cours d'exécution sont
+fournis tout au long du cycle de vie de la tâche ; si le sous-agent ne peut pas les consommer en
+à l'étape en cours, ils doivent rester en file d'attente et être appliqués dans un coffre-fort
+point de suite. Les sous-agents peuvent également répondre lorsqu'ils ont besoin d'éclaircissements
+au lieu de bloquer de manière invisible.
+
+## Lecture de l'état de la tâche {#reading-state}
+
+Depuis le code du serveur ou autre 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)
+```
+
+Champs clés `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
+}
+```
+
+## Profils d'agent personnalisés {#profiles}
+
+Les sous-agents sont mappés aux profils d'agent personnalisés : fichiers Markdown sur `agents/<slug>.md` dans l'espace de travail qui apparaissent dans la liste déroulante `@mention` et servent de cibles de délégation. [Workspace — Custom Agents](/docs/workspace#custom-agents) possède le format complet (frontmatter, `tools`, `delegate-default`, remplacements de modèle).
+
+## Garde-profondeur de délégation {#depth-guard}
+
+Les sous-agents peuvent engendrer des sous-agents, ce qui représente un risque d'emballement/de coût : une chaîne illimitée de délégations pourrait s'étendre indéfiniment. Le framework impose un **plafond strict sur la profondeur de la délégation**, côté serveur, indépendamment de toute protection au niveau de l'outil.
+
+Le chat de niveau supérieur est la profondeur `0`. Un sous-agent qu'il génère est la profondeur `1` ; ce sous-agent peut réapparaître (profondeur `2`) ; un spawn qui créerait un sous-agent de profondeur `3` est **refusé**. La limite par défaut est **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}"
+}
+```
+
+L'application est ambiante : chaque sous-agent s'exécute à l'intérieur d'un `AsyncLocalStorage` qui enregistre sa propre profondeur, de sorte que tout `spawnTask` atteint de manière transitive à partir de cette exécution lit la profondeur de son parent et refuse une fois le plafond atteint - même si l'outil `agent-teams` a été remis à un sous-agent qui n'aurait pas dû l'avoir. La décision est exposée comme un `evaluateSubagentDepth(parentDepth)` pur et testable unitairement. Un spawn refusé renvoie une erreur claire : _"Limite de profondeur de délégation atteinte (max N) ; impossible de générer un autre sous-agent."_
+
+### Configurer le capuchon {#depth-guard-config}
+
+Remplacez la valeur par défaut au moment du déploiement avec `AGENT_NATIVE_MAX_SUBAGENT_DEPTH` :
+
+| Valeur           | Effet                                                                                                                                                                        |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _(non défini)_   | Capuchon par défaut de `2`.                                                                                                                                                  |
+| `0`              | **Aucun sous-agent ne peut être généré** : l'agent de niveau supérieur fait tout le travail.                                                                                 |
+| `1`…`16`         | Autant de niveaux de délégation.                                                                                                                                             |
+| invalide / `>16` | Une valeur non entière/négative/NaN revient à `2` ; tout ce qui se trouve au-dessus de `16` est lié à `16` afin qu'une faute de frappe ne puisse jamais désactiver la garde. |
+
+```bash
+AGENT_NATIVE_MAX_SUBAGENT_DEPTH=1   # sub-agents allowed, but they can't sub-delegate
+```
+
+Lorsqu'un sous-agent est égal ou inférieur au plafond, le framework injecte une ligne dans son contexte d'exécution lui indiquant à quelle profondeur il se trouve et s'il peut déléguer davantage, afin que le modèle dépense son budget de manière appropriée.
+
+## Quelle est la prochaine étape
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — le format de profil
+- [**A2A Protocol**](/docs/a2a-protocol) — lorsque le « sous-agent » vit dans une application entièrement différente
+- [**Actions**](/docs/actions) — les outils qu'un sous-agent appelle

package/docs/content/locales/fr-FR/agent-web-surfaces.md

@@ -0,0 +1,161 @@
+---
+title: "Web des agents publics"
+description: "Rendre les routes publiques explorables, lisibles, citables et éventuellement appelables par les agents : robots.txt, llms.txt, miroirs de démarque, JSON-LD et une surface publique MCP."
+---
+
+# Web des agents publics
+
+Le Web public des agents permet aux agents d'explorer, de lire, de citer et d'appeler facilement les routes Agent-Native publiques. L’objectif n’est pas de rendre public chaque point de terminaison d’une application. L'objectif est de publier une surface publique propre pour les pages déjà publiques, tout en conservant l'accès aux données privées et aux outils derrière des contrôles explicites.
+
+Le site de documentation est l'implémentation de référence. Aujourd'hui, il est expédié :
+
+- `/robots.txt` avec une stratégie de robot d'exploration qui autorise la récupération mais interdit l'entraînement par défaut.
+- `/sitemap.xml` avec URL canoniques absolus et `lastmod` lorsque le fichier source l'expose.
+- `/llms.txt` et `/llms-full.txt` pour une découverte de contenu conviviale pour les agents.
+- Miroirs Markdown tels que `/docs/getting-started.md`.
+- Réponses `Accept: text/markdown` pour les pages de documentation publique après une version de production.
+- JSON-LD pour les métadonnées de l'organisation de base, du site Web et de la page.
+- Un audit CLI (`npx @agent-native/core@latest audit-agent-web`) qui vérifie tout ce qui précède.
+
+La configuration de `publicMcp: true` expose en outre le actions activé en tant que point de terminaison public MCP, permettant aux agents externes de les appeler directement (voir [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}"
+}
+```
+
+## Configuration {#config}
+
+Ajoutez `agentWeb` sous la configuration de l'application d'espace de travail existante (dans le `package.json` de votre application sous la clé `agent-native` – ou de manière équivalente `workspace.agentWeb`, `agentWeb` ou `root.agentWeb`). La liste des itinéraires publics est toujours dérivée des paramètres d'accès aux itinéraires de l'application ; `agentWeb` contrôle la façon dont cette surface publique est représentée aux agents.
+
+```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"
+        }
+      }
+    }
+  }
+}
+```
+
+Pour la plupart des applications, laissez les valeurs par défaut inchangées. Si une application dispose d'un itinéraire public, `discoverable` est activé par défaut. La politique du robot d'exploration par défaut est « détectable, non entraînable » : la recherche, la récupération déclenchée par l'utilisateur, les agents de codage et les agents de navigation autonomes sont autorisés ; Les robots d'exploration d'entraînement ne sont pas autorisés.
+
+## Itinéraire source de vérité {#route-source}
+
+La découverte Web de l'agent suit le modèle d'accès par route :
+
+- Les applications publiques exposent tous les itinéraires à l'exception de `protectedPaths`.
+- Les applications internes exposent uniquement `publicPaths`.
+- Les pages de partage public et de formulaire peuvent être lisibles par les agents.
+- Les données privées soumises, les tableaux de bord authentifiés et l'état de l'utilisateur/de l'organisation ne sont jamais inclus simplement parce qu'une page à proximité est publique.
+
+Cela permet aux applications mixtes de rester naturelles. Une application de formulaires peut exposer une page de formulaire publique et garder les soumissions privées. Une application de contenu peut exposer les publications publiées et garder l'éditeur privé. Un site de documentation peut tout exposer, sauf les outils d'administration.
+
+## Les pages publiques ne sont pas des outils publics {#public-tools}
+
+L'accès aux pages publiques et l'accès aux outils publics sont distincts. Un itinéraire public signifie uniquement que les agents peuvent lire cet itinéraire en tant que HTML, Markdown, entrées de plan de site, entrées LLMS et données structurées.
+
+```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."
+}
+```
+
+Pour exposer une action via un protocole d'agent public, l'action doit s'inscrire :
+
+```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` reste `false` par défaut. Lorsque le public MCP est activé, le serveur doit exposer uniquement actions avec `publicAgent.expose === true`, et doit toujours exclure les conséquences ou écrire actions à moins que l'action et la politique d'authentification ne les autorisent explicitement.
+
+## Fichiers au moment de la construction {#build-time}
+
+Les utilitaires Framework dans `@agent-native/core/agent-web` génèrent les fichiers communs à partir d'une liste de pages :
+
+```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(),
+    },
+  ],
+});
+```
+
+Les applications Vite peuvent utiliser `createAgentWebVitePlugin` à partir de `@agent-native/core/vite` pour écrire ces fichiers dans `public`, `dist`, `dist/client`, `dist/server/public` ou `build/client` pendant les versions de production.
+
+## Auditer un site {#audit}
+
+Utilisez l'audit CLI sur un site déployé ou un serveur de production local :
+
+```bash
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
+```
+
+L'audit vérifie :
+
+- SSR-HTML visible.
+- URL canoniques.
+- JSON-LD.
+- Politique `robots.txt` et plan de site absolu URL.
+- Entrées absolues du plan du site.
+- `/llms.txt` et `/llms-full.txt`.
+- Miroirs Markdown.
+- `Accept: text/markdown`.
+- Aucun bloc 401/403 accidentel pour les agents utilisateurs de récupération d'agent commun.
+
+L'audit sort non nul si une surface publique requise est manquante.
+
+## Quelle est la prochaine étape
+
+- [**Actions**](/docs/actions) — comment inscrire actions dans le protocole d'agent public
+- [**MCP Protocol**](/docs/mcp-protocol) : la surface MCP activée par `publicMcp: true`
+- [**Deployment**](/docs/deployment) — où ces fichiers statiques sont écrits lors des builds

package/docs/content/locales/fr-FR/audit-log.md

@@ -0,0 +1,111 @@
+---
+title: "Journal d'audit"
+description: "Un enregistrement durable, en ajout uniquement, indiquant qui a modifié quelles données d'application, quand et s'il s'agissait de vous ou de l'agent, capturé automatiquement au moment de l'action."
+---
+
+# Journal d'audit
+
+Chaque application native d'agent reçoit immédiatement un journal d'audit : un enregistrement durable, complet, avec accès limité et en ajout uniquement, indiquant ** qui a muté quelles données d'application, quand, d'où et - quand il s'agissait de l'agent - dans quelle exécution. ** La capture est automatique au niveau de l'action ; vous n'écrivez aucun code pour cela.
+
+Étant donné que l'agent peut modifier les données en votre nom, la question principale à laquelle un journal d'audit répond ici n'est pas seulement « qui a modifié cet enregistrement » – c'est ** « était-ce moi ou l'agent, et quelle tournure l'a causé ? »** Aucun autre système du framework ne peut répondre à cette question.
+
+## Audit vs observabilité vs suivi {#which}
+
+Trois systèmes enregistrent « ce qui s'est passé », pour trois raisons différentes. Choisissez en fonction de la question que vous posez :
+
+| Système                                  | La question à laquelle il répond                                   | Fidélité                            | Public                                        |
+| ---------------------------------------- | ------------------------------------------------------------------ | ----------------------------------- | --------------------------------------------- |
+| **Journal d'audit** (cette page)         | "Qui a modifié cet enregistrement, quand et était-ce l'agent ?"    | **Complet, durable, limité**        | Utilisateur, administrateur, l'agent lui-même |
+| **[Observability](/docs/observability)** | "Pourquoi l'agent a-t-il fait cela et combien cela a-t-il coûté ?" | Télémétrie d'étendue échantillonnée | Développeur                                   |
+| **[Tracking](/docs/tracking)**           | "Comment les gens utilisent-ils le produit ?"                      | Activez et oubliez le SaaS externe  | PM / croissance                               |
+
+Un journal d'audit échantillonné ou expédié à un fournisseur d'analyses est inutile : l'essentiel est qu'il soit complet, local et interrogeable. C'est donc son propre sous-système, pas un mode des deux autres.
+
+## Ce qui est capturé automatiquement {#captured}
+
+Lorsqu'une action de **mutation** est exécutée (tout ce qui n'est pas un `GET` en lecture seule), le framework ajoute une ligne à `agent_audit_log` avec :
+
+- **Action** — le nom de l'action (par exemple `delete-recording`).
+- **Acteur** – `agent`, `human` ou `system`, plus l'adresse e-mail de l'acteur – renseignée **même pour les appels d'agent**, vous obtenez donc "l'agent, agissant pour alice@,…".
+- **Exécuter la liaison** — l'agent `threadId` / `turnId` qui a déclenché l'appel (un appel d'outil), donc une mutation remonte au tour exact de l'agent.
+- **Surface** – `tool` (agent), `frontend`, `http`, `cli`, `mcp` ou `a2a`.
+- **Résultat** — `success`, `error` (avec un code d'erreur) ou `denied` (bloqué par une porte d'approbation humaine).
+- **Inputs** — les arguments d'appel, avec des valeurs en forme d'identifiant [redacted](#privacy).
+- **Cible et propriétaire** : ressource modifiée par l'action, utilisée pour [scope reads](#reading).
+
+Aucun câblage nécessaire : la capture s'accroche de manière transparente au `defineAction`. Les actions en lecture seule sont ignorés et quelques frameworks haute fréquence actions (synchronisation de l'état de l'application, radiographie contextuelle, navigation) sont ignorés par défaut pour éviter d'inonder le journal.
+
+## Déclarer ce qu'une action a modifié {#target}
+
+Par défaut, un événement est limité au **acteur** : vous voyez vos propres modifications et celles de l'agent en votre nom. Pour apporter une modification à une ressource _partagée_ qui apparaît également dans le journal du **propriétaire** et pour étiqueter les événements par ressource, déclarez 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... */
+  },
+});
+```
+
+Tout dans `audit` est facultatif. L'ajout minimum utile est `target: () => ({ type, id })`.
+
+### Capture de réglage {#tuning}
+
+| Option               | Effet                                                                        |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `audit.target`       | Étiquetez l'événement avec la ressource et la portée lit à son propriétaire. |
+| `audit.summary`      | Une courte ligne lisible par l'homme pour l'événement.                       |
+| `audit.onRead`       | Auditer une **lecture** sensible (accès secret, exportation groupée).        |
+| `audit.enabled`      | `true` force la capture ; `false` supprime une mutation bruyante.            |
+| `audit.recordInputs` | `false` ignore la capture des arguments (déjà expurgés).                     |
+
+## Lecture du parcours {#reading}
+
+Deux actions en lecture sont disponibles pour l'agent **et** le frontend dans chaque application, étendus dans SQL à l'appelant — ils ne renvoient jamais les lignes d'un autre locataire :
+
+- **`list-audit-events`** — filtrer par `targetType` / `targetId`, `actorKind` (`agent` | `human` | `system`), `status`, `threadId` / `turnId`, `action`, `sinceMs` et `limit`.
+- **`get-audit-event`** — un événement par identifiant, y compris sa charge utile d'entrée expurgée.
+
+Créez un flux d'activité ou une ligne « qui a modifié cela » en appelant `list-audit-events` à partir du UI avec `useActionQuery` — n'écrivez jamais manuellement une récupération dans la table d'audit :
+
+```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 }, …]
+```
+
+L'agent peut appeler la même action : demandez-lui "Qu'avez-vous changé sur cet enregistrement ?" et il répond depuis le sentier.
+
+## Confidentialité et conservation {#privacy}
+
+- **Rédaction** — avant que les entrées ne soient stockées, les clés et valeurs en forme d'informations d'identification (jetons, secrets, mots de passe, chaînes de support) sont supprimées et les charges utiles surdimensionnées tronquées. Le journal d'audit ne devient jamais un magasin secondaire de secrets. Gardez également le texte `summary` exempt de données sensibles.
+- **Append-only** : il n'y a aucune action de mise à jour ou de suppression pour les lignes d'audit. La seule suppression est la purge de rétention, qui rend le journal digne de confiance en tant que piste d'audit.
+- **Isolement du locataire** : les lectures sont limitées à l'identité et à l'organisation de l'appelant ; sans identité, rien ne correspond.
+
+Configurer via l'environnement :
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` — durée pendant laquelle les lignes sont conservées (`365` par défaut ; `0` = conserver pour toujours).
+- `AGENT_NATIVE_AUDIT_ENABLED=false` — kill switch global.
+
+## Quelle est la prochaine étape
+
+- [**Actions**](/docs/actions) — la couture `defineAction` où se produit la capture
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — actions fermé, enregistré sous le nom `denied`
+- [**Security & Data Scoping**](/docs/security) — l'audit du modèle de propriété lit la réutilisation
+- [**Observability**](/docs/observability) — télémétrie exécutée par l'agent (l'autre "ce qui s'est passé")