@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/tracking.md

@@ -0,0 +1,236 @@
+---
+title: "Suivi et analyses"
+description: "Analyses côté serveur avec fournisseurs enfichables : PostHog, Mixpanel, Amplitude ou webhook personnalisé"
+---
+
+# Suivi des analyses
+
+Une fonction, plusieurs destinations. Appelez `track()` à partir de n'importe quel code côté serveur (actions, plugins, routes de serveur) et l'événement est diffusé auprès de chaque fournisseur d'analyse enregistré. Aucune dépendance SDK, aucun script côté client, aucun blocage. Le même `track()` est également disponible dans [browser/app code](#client) et est acheminé vers les mêmes fournisseurs.
+
+Il s'agit de _product_ Analytics : les événements de votre application sont transmis à PostHog/Mixpanel/Amplitude. Pour les métriques de _qualité des agents_ (traces, coûts, évaluations, commentaires) stockées dans votre propre base de données, voir [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}"
+}
+```
+
+## Fournisseurs intégrés {#built-in}
+
+Définissez une variable d'environnement et le fournisseur s'enregistre automatiquement au démarrage du serveur. Aucune modification de code requise.
+
+| Fournisseur       | Vars d'environnement                                                                                |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| PostHog           | `POSTHOG_API_KEY` (obligatoire), `POSTHOG_HOST` (facultatif, par défaut `https://us.i.posthog.com`) |
+| Panneau de mixage | `MIXPANEL_TOKEN`                                                                                    |
+| Amplitude         | `AMPLITUDE_API_KEY`                                                                                 |
+| Webhook           | `TRACKING_WEBHOOK_URL` (obligatoire), `TRACKING_WEBHOOK_AUTH` (en-tête `Authorization` en option)   |
+
+Plusieurs fournisseurs peuvent être actifs simultanément. Chaque événement leur est destiné à tous.
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+Déclenchez un événement d'analyse. Distribution à tous les fournisseurs enregistrés.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+Identifiez un utilisateur avec des caractéristiques. Transmis aux fournisseurs qui le prennent en charge (PostHog, Mixpanel, Amplitude, webhook).
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+Besoin d'un backend personnalisé, du registre de fournisseur API ou des composants internes de traitement par lots/singleton ? Voir [Advanced: custom providers & internals](#advanced) à la fin.
+
+## Utiliser track() dans les modèles {#templates}
+
+Appelez `track()` à partir des gestionnaires d'actions pour enregistrer l'activité de l'utilisateur ou de l'agent :
+
+```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 };
+  },
+});
+```
+
+Les appels de suivi sont déclenchés et oubliés : ils reviennent immédiatement et ne bloquent jamais la réponse à l'action.
+
+## Suivi côté client {#client}
+
+`track()` fonctionne également à partir du code du navigateur/de l'application. Importez le jumeau client de `@agent-native/core/client` et appelez-le de la même manière : il POST l'événement sur la route du framework sur `POST /_agent-native/track`, qui le transmet aux **mêmes** fournisseurs côté serveur enregistrés (PostHog, Mixpanel, Amplitude, webhook). Aucune analyse SDK n'est envoyée au navigateur et aucune clé de fournisseur n'est exposée côté client.
+
+```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 });
+```
+
+Principales différences par rapport au [server `track()`](#track) :
+
+- **Aucun argument d'identité.** L'événement est attribué côté serveur à l'utilisateur connecté (et à l'organisation active, comme `org_id` dans `properties`). Le code du navigateur ne transmet jamais un `userId`.
+- **`source: "client"`** est ajouté aux propriétés de chaque événement afin que vous puissiez distinguer les événements générés par le client de ceux du serveur.
+- **Fire-and-forget.** Il ne bloque jamais le UI, ne lance jamais et avale les erreurs réseau.
+- **Authentifié, propriétaire uniquement.** L'itinéraire nécessite une session et un marqueur de même origine/CSRF (défini automatiquement par l'assistant), il ne peut donc pas être utilisé comme relais d'analyse ouvert. `name` est limité à 200 caractères et `properties` à ~ 16 Ko ; les charges utiles surdimensionnées ou mal formées sont rejetées.
+
+Ceci est distinct de la télémétrie interne du navigateur du framework (`trackEvent()` / pages vues automatiques – voir [Browser defaults](#browser-defaults) ci-dessous), qui alimente les propres analyses de produits de Agent Native. Utilisez `track()` pour les événements d'analyse de votre application qui doivent atteindre vos fournisseurs configurés.
+
+## Avancé : fournisseurs personnalisés et éléments internes {#advanced}
+
+La plupart des applications n'ont besoin que de `track()` / `identify()` et d'un fournisseur intégré. Le reste de la surface (enregistrement des fournisseurs personnalisés, de l'interface `TrackingProvider`, des éléments internes de traitement par lots et de la propre télémétrie du navigateur du framework) se trouve ci-dessous.
+
+<details>
+<summary><strong>Registre du fournisseur API, interface, composants internes et paramètres par défaut du navigateur</strong></summary>
+
+### `registerTrackingProvider(provider)` {#register}
+
+Enregistrez un fournisseur personnalisé pour n'importe quel backend d'analyse.
+
+```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}
+
+Videz tous les fournisseurs. Appelez avant la sortie du processus pour garantir que les événements en attente sont envoyés.
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+Supprimer un fournisseur par son nom. Renvoie `true` si le fournisseur a été trouvé et supprimé.
+
+### `listTrackingProviders()` {#list}
+
+Renvoie les noms de tous les fournisseurs enregistrés.
+
+### L'interface TrackingProvider {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+Seuls les `name` et `track` sont requis. `identify` et `flush` sont facultatifs : implémentez-les si votre backend prend en charge l'identité utilisateur et la livraison par lots.
+
+### Comment ça marche {#internals}
+
+- **HTTP par lots** : les fournisseurs intégrés mettent les événements en file d'attente et les vident toutes les 10 secondes ou lorsque 50 événements s'accumulent, selon la première éventualité. Cela minimise les requêtes sortantes sans perdre de données.
+- **Aucune dépendance SDK** — tous les fournisseurs intégrés utilisent `fetch()` brut. Pas de PostHog SDK, pas de Mixpanel SDK, pas d'Amplitude SDK. Maintient la légèreté du framework.
+- **Livraison dans les meilleurs efforts** : les erreurs du fournisseur sont détectées et enregistrées. Une intégration analytique défaillante ne fait jamais planter l'appelant ni ne bloque le traitement des requêtes.
+- **Global singleton** : le registre utilise une clé `Symbol.for` sur `globalThis` afin que plusieurs instances de graphiques ESM (mode développement Vite + Nitro, liens symboliques) partagent un ensemble de fournisseurs.
+
+### Paramètres par défaut du navigateur {#browser-defaults}
+
+Cela couvre la télémétrie interne du framework, qui concerne principalement les contributeurs du framework et les auteurs de modèles avancés.
+
+Les racines du modèle appellent `configureTracking()` une fois au démarrage. Les événements du navigateur envoyés avec `trackEvent()` incluent automatiquement le contexte de l'application/du modèle ainsi que la connexion LLM actuelle lorsque l'application peut le résoudre :
+
+- `llm_connection` : étiquette de fournisseur normalisée telle que `builder`, `anthropic`, `openai`, `google` ou `none`
+- `llm_engine` : identifiant du moteur, par exemple `builder` ou `ai-sdk:openai`
+- `llm_model` — le modèle sélectionné/par défaut lorsqu'il est connu
+- `llm_connection_source` — `app_secrets`, `settings` ou `env`
+- `llm_connection_configured` – si une connexion LLM est disponible
+
+Le framework suit également `builder connect clicked` à partir des CTA Connect Builder, et les routes de connexion Builder côté serveur suivent les événements de cycle de vie démarrés/réussis/échoués. `configureTracking()` est appelé automatiquement par le framework ; vous n'avez pas besoin de l'appeler dans votre propre code de modèle.
+
+</details>
+
+## Quelle est la prochaine étape
+
+- [**Actions**](/docs/actions) – d'où proviennent la plupart des appels de suivi
+- [**Server Plugins**](/docs/server) — `registerBuiltinProviders()` s'exécute dans le plugin core-routes au démarrage
+- [**Secrets**](/docs/security) : gérer les clés API pour les fournisseurs de suivi

package/docs/content/locales/fr-FR/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "Utiliser votre agent"
+description: "La boucle quotidienne du travail avec l'agent : il voit ce que vous regardez, vous le dirigez, l'intégrez, passez à UI-light et co-éditez à côté de lui."
+---
+
+# Utiliser votre agent
+
+L'idée déterminante derrière l'agent natif est que l'agent et le UI sont des **partenaires égaux** — voir [What Is Agent-Native?](/docs/what-is-agent-native) pour le pourquoi. Cette section concerne l'autre moitié de cette promesse : ce que l'on ressent en travaillant réellement avec l'agent une fois qu'il est ancré à côté de votre application.
+
+Il existe une ligne directe simple. L'agent **voit** ce que vous regardez, vous le **dirigez** vers ce que vous voulez, vous pouvez l'**intégrer** n'importe où, vous pouvez devenir entièrement **UI-light** lorsque cela vous convient le mieux, et vous pouvez **co-éditer** les mêmes documents en même temps. Chacun d'entre eux est une page de cette section.
+
+```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}"
+}
+```
+
+## Il voit ce que vous regardez {#it-sees}
+
+L'agent n'est pas aveugle à votre écran. Ouvrez un e-mail et il sait quel fil de discussion. Sélectionnez un graphique et il sait quel graphique. Mettez en surbrillance un paragraphe et il peut agir uniquement sur cette plage. Cette conscience partagée est ce qui vous permet de dire « répondre à ceci » ou « résumer la sélection » sans préciser le contexte à chaque fois.
+
+Cela fonctionne car la navigation et la sélection actuelles se trouvent dans `application_state` SQL, que l'agent lit dans le cadre de son contexte. L'agent peut également ramener ce même état en arrière (ouvrir une vue, sélectionner une ligne) afin que vous le regardiez fonctionner dans le vrai UI plutôt que dans une transcription.
+
+```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) : état de navigation, affichage de l'écran, commandes de navigation et manière dont l'agent reste synchronisé avec votre écran.
+
+## Vous le dirigez {#you-direct-it}
+
+La plupart du temps, vous dirigez l'agent en écrivant dans le chat. Deux choses rendent cela plus rapide.
+
+**Mentions.** Marquez un agent personnalisé, un agent connecté ou un fichier avec `@` pour l'intégrer à la conversation : "laissez `@analytics` extraire les chiffres de la semaine dernière, puis rédigez le résumé." Les mentions vous permettent d'atteindre le bon spécialiste ou d'attacher le bon contexte sans quitter le compositeur.
+
+**Voix.** Le compositeur a un microphone. Dictez une demande au lieu de la saisir, avec des options de fournisseur allant de la transcription hébergée de Builder à l'apport de votre propre clé en passant par une solution de secours du navigateur.
+
+→ [**Agent Mentions**](/docs/agent-mentions) : `@` mentionne les agents personnalisés, les agents connectés et les fichiers dans le chat.
+→ [**Voice Input**](/docs/voice-input) — dictée dans le composeur de chat et comment la transcription est acheminée.
+
+## Vous l'intégrez {#you-embed-it}
+
+L'agent n'est pas une application distincte vers laquelle vous accédez. Il est livré sous la forme d'une poignée de composants React (une barre latérale, un panneau brut et un appel `sendToAgentChat()`) que vous déposez dans n'importe quelle application. Rendu `<AgentSidebar>` pour attribuer à chaque écran un agent commutable, ou câblez un bouton pour confier une tâche spécifique au chat au lieu d'exécuter un appel LLM unique.
+
+→ [**Drop-in Agent**](/docs/drop-in-agent) : montez les `<AgentPanel>`, `<AgentSidebar>` et `sendToAgentChat()` dans n'importe quelle application React.
+→ [**Agent Surfaces**](/docs/agent-surfaces) : choisissez si le flux de travail doit être sans tête, axé d'abord sur le chat, intégré ou une application complète.
+
+## Vous pouvez passer au UI-light {#ui-light}
+
+Toutes les applications n'ont pas besoin d'un tableau de bord complet. Lorsque l'agent _est_ le produit, vous pouvez ignorer la plupart des UI personnalisés : ouvrez l'application, demandez ce que vous voulez et laissez l'agent faire le reste. L'agent dispose toujours de sa surface de gestion (historique, espace de travail, paramètres), mais l'interaction principale est la conversation plutôt que les clics.
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — applications où l'agent est l'ensemble du produit.
+
+## Vous co-éditez avec lui {#you-co-edit}
+
+Lorsque vous et l'agent travaillez sur le même document, vous ne vous relayez pas. Grâce à la collaboration en temps réel, les modifications de l'agent sont diffusées parallèlement aux vôtres (curseurs en direct, pas d'écrasement) de la même manière que celles d'un coéquipier. Vous pouvez continuer à taper pendant qu'il fonctionne et il voit vos modifications au fur et à mesure qu'elles se produisent.
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — édition collaborative multi-utilisateurs avec curseurs en direct et modifications d'agent dans le même document.
+
+## Quelle est la prochaine étape {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) — l'agent sait ce que vous regardez
+- [**Agent Mentions**](/docs/agent-mentions) — dirigez-le avec les mentions `@`
+- [**Voice Input**](/docs/voice-input) — dirigez-le en parlant
+- [**Drop-in Agent**](/docs/drop-in-agent) : intégrez-le dans n'importe quelle application React
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) — passez à UI-light lorsque l'agent est le produit
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — co-éditez ensemble le même document

package/docs/content/locales/fr-FR/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "Saisie vocale"
+description: "Dictée vocale dans l'outil de composition de chat de l'agent : fournisseurs Builder Gemini, BYOK et solution de secours Web Speech du navigateur."
+---
+
+# Saisie vocale
+
+Chaque application native d'agent dispose d'un microphone dans l'éditeur de chat. Cliquez dessus, parlez et vos mots seront transcrits dans l'invite. Utile sur mobile, utile pour les invites longues, utile lorsque vos mains sont sur autre chose.
+
+Le framework gère tout cela automatiquement. Les utilisateurs connectés à Builder obtiennent par défaut Gemini Flash-Lite hébergé sur Builder ; sinon, les utilisateurs peuvent apporter leur propre clé de fournisseur ou recourir à la reconnaissance vocale du navigateur.
+
+## Comment ça marche {#how-it-works}
+
+Le bouton vocal du compositeur enregistre l'audio dans le navigateur, puis sélectionne un fournisseur :
+
+1. **Builder Gemini Flash-Lite (par défaut lorsque Builder est connecté).** Le navigateur POSTe l'audio sur `/_agent-native/transcribe-voice`, qui passe par proxy via Builder.io à l'aide de Gemini Flash-Lite. Aucune clé Google API requise.
+2. **Fournisseurs cloud BYOK.** Les utilisateurs peuvent choisir Google Gemini, Groq Whisper ou OpenAI Whisper dans les paramètres. La route résout les secrets chiffrés à l'échelle de l'utilisateur avant les informations d'identification de déploiement partagées.
+3. **Browser Web Speech API (repli).** Si aucun fournisseur de serveur n'est disponible, le compositeur peut utiliser la reconnaissance vocale intégrée du navigateur. Fonctionne dans les navigateurs basés sur Chromium (Chrome, Edge, Arc) et Safari. Moins précis ; diffuse en direct.
+
+Le choix du fournisseur est stocké dans l'état de l'application sous `voice-transcription-prefs` afin que l'utilisateur puisse forcer `"auto"` (par défaut : sélectionne le meilleur fournisseur disponible), `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"` ou `"browser"` dans les paramètres de la barre latérale.
+
+```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}"
+}
+```
+
+L'itinéraire est **de même origine uniquement** : les POST intersites sont rejetés afin qu'un attaquant ne puisse pas graver les crédits de transcription à partir d'une page externe.
+
+## Activation des fournisseurs {#enabling-providers}
+
+Builder est le chemin le plus simple : connectez Builder.io à partir des paramètres et le fournisseur par défaut devient Builder Gemini Flash-Lite. Pour les fournisseurs BYOK, ajoutez la clé correspondante dans Paramètres → Clés API.
+
+### Par utilisateur (recommandé pour SaaS)
+
+L'utilisateur définit sa propre clé via les paramètres de la barre latérale de l'agent UI. Il est stocké en tant que secret chiffré à l'échelle de l'utilisateur (via `readAppSecret`). Chaque utilisateur paie sa propre transcription ; aucun coût pour l'hôte.
+
+### Partagé (pour les outils internes)
+
+Définissez `GEMINI_API_KEY`, `GROQ_API_KEY` ou `OPENAI_API_KEY` en tant que variable d'environnement ou dans la table `settings`. La transcription de chaque utilisateur atteint la clé partagée.
+
+```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."
+}
+```
+
+## L'itinéraire {#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\" }" }
+  ]
+}
+```
+
+Vous n'avez pas besoin de l'appeler directement : le compositeur le fait. Si vous créez une surface de saisie personnalisée, réutilisez d'abord les éléments partagés du compositeur/client vocal de `@agent-native/core/client`. Traitez cet itinéraire comme la limite de transport de bas niveau pour les assistants personnalisés qui doivent envoyer de l'audio en plusieurs parties.
+
+## Personnalisation du fournisseur {#customizing}
+
+Le champ du fournisseur est une clé d'état d'application simple, l'agent peut donc le modifier sur demande (`"use the browser speech recognizer instead"`). Si vous créez un modèle avec des exigences différentes (par exemple, un déploiement Whisper sur site), remplacez le gestionnaire de route en enregistrant votre propre route `transcribe-voice` avant que le framework ne monte la route par défaut.
+
+## Quelle est la prochaine étape
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — le compositeur qui expose le bouton vocal
+- [**Onboarding**](/docs/onboarding) – enregistrement des clés du fournisseur en tant qu'étapes de configuration
+- [**Security & Data Scoping**](/docs/security) – comment les secrets chiffrés sont stockés par utilisateur

package/docs/content/locales/fr-FR/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "Qu'est-ce que Agent-Native ?"
+description: "Pourquoi la plupart des applications d'IA semblent à moitié construites, ce qui rend une application véritablement native pour les agents et à quoi ressemble votre expérience quotidienne en conséquence."
+---
+
+# Qu'est-ce que Agent-Native ?
+
+L'agent natif est un moyen de créer des logiciels dans lesquels l'agent IA et le produit qui l'entoure sont des **partenaires égaux**. Cette surface peut être un agent sans tête avec une action personnalisée, une discussion riche ou un UI complet. L'important est que les agents et les humains partagent le même actions, la même base de données et le même état.
+
+Si vous ne vous souvenez que d'une chose de cette page, rappelez-vous ceci : la plupart des applications d'IA actuelles sont loin d'être utiles, et cet écart est la plus grosse erreur du secteur à l'heure actuelle.
+
+## À quoi cela ressemble en tant qu'utilisateur {#what-it-looks-like}
+
+Imaginez un travailleur en arrière-plan, une boîte de réception, un calendrier, un générateur de formulaires ou un tableau de bord d'analyse. Parfois, il n’y a pas encore d’écran personnalisé : vous exécutez une action ou une invite d’agent d’application sans tête. Parfois, le premier écran est le chat : vous demandez ce que vous voulez, l'agent guide la configuration, affiche un tableau ou un graphique et ouvre la vue appropriée de l'application. Parfois, le chat est ancré sur le côté droit d’une application complète. À travers ces formes, vous pouvez :
+
+- **Commencez par l'opération réelle.** Une action durable peut être exécutée à partir du CLI, du HTTP, du MCP, du A2A, de la boucle d'agent d'application et, plus tard, d'un UI.
+- **Cliquez sur tout ce sur quoi vous cliqueriez normalement lorsqu'il y a un UI.** Tous les boutons, listes, tableaux de bord, raccourcis clavier : ils appellent tous les mêmes opérations que l'agent peut appeler.
+- **Ou demandez simplement.** Tapez « Répondre à l'e-mail de Sara disant que je serai là à 15 heures » dans l'agent. Il ouvre le bon fil de discussion, rédige la réponse et vous la montre pour approbation, exactement comme si vous l'aviez fait à la main.
+- **Voir ce qu'il voit.** Ouvrez un e-mail et l'agent sait lequel. Sélectionnez un graphique et l'agent sait quel graphique. Mettez en surbrillance un paragraphe et appuyez sur Cmd+I, et l'agent agit uniquement sur ce paragraphe.
+- **Regardez-le fonctionner.** Pendant que l'agent fait certaines choses (ouvre des vues, modifie des brouillons, exécute des rapports), le UI est mis à jour en temps réel. Vous pouvez l'arrêter, le rediriger ou prendre le relais avec la souris à tout moment.
+- ** Pilotez-le comme un coéquipier. ** Donnez votre avis, mettez une autre tâche en file d'attente, modifiez ses instructions, auditez ce qu'il a fait hier. Il se souvient et vos flux de travail s'améliorent au fil du temps.
+
+C'est l'expérience pour laquelle l'agent natif est conçu. Voici maintenant pourquoi la plupart des produits n'y arrivent pas.
+
+## Pourquoi la plupart des "applications d'IA" ne sont pas à la hauteur (le principe de l'échelle) {#the-ladder}
+
+La plupart des équipes montent une progression, un peu comme une échelle, et la plupart arrêtent un échelon trop tôt.
+
+### Rung 1 – un seul appel LLM (l'anti-modèle) {#rung-one}
+
+Une zone de texte envoie une invite, l'IA renvoie une chaîne et vous l'affichez. Peut-être avec une roulette. Il n'y a aucun moyen pour l'utilisateur de corriger sa trajectoire, aucun moyen pour l'IA d'agir, aucun moyen de voir ce qui s'est passé ou pourquoi.
+
+Vous voyez cela partout : des "fonctionnalités IA" qui sont essentiellement un bouton "Résumer" intégré à un produit SaaS. Ils ont l’air impressionnants dans les démos et brisent dès que la réalité devient compliquée. Ce n'est pas un produit ; c'est un jouet.
+
+### Rung 2 : une conversation avec des outils {#rung-two}
+
+Maintenant, l'IA peut _faire des choses_. Il dispose d'outils — « brouillon d'e-mail », « rechercher des contacts », « exécuter une requête » — et d'une interface de discussion où il fonctionne devant vous, affichant les appels et les résultats des outils au fur et à mesure. Voici à quoi ressemblent les Claude, ChatGPT et Cursor sous le capot.
+
+C'est un véritable pas en avant. Mais à lui seul, il s'agit toujours d'une fenêtre de discussion. Il n’y a pas de véritable UI. Pas de tableaux de bord, pas de listes, pas de formulaires, pas de raccourcis clavier, pas de collaboration en équipe. Si l'IA est confuse, vous êtes obligé de retaper plutôt que de simplement cliquer sur le bouton droit. Les non-développeurs ont du mal à accomplir un vrai travail dans ce format.
+
+### Échelon 3 — agent + UI en tant que partenaires égaux {#rung-three}
+
+Il s'agit d'un agent natif. Vous ajoutez une véritable application complète autour de l'agent - et, surtout, chaque action que l'agent peut entreprendre est également un bouton dans le UI, et chaque bouton sur lequel l'utilisateur clique exécute la même logique que celle utilisée par l'agent. Une implémentation, deux voies d'entrée.
+
+Trois choses changent lorsque vous atteignez le barreau 3 :
+
+- **Vous avez arrêté d'ajouter des boutons à un chatbot. Vous avez ajouté un agent à une application.** Il s'agit d'un produit de bien meilleure qualité des deux côtés.
+- **L'agent dispose d'un contexte réel.** Il voit ce que vous regardez, ce que vous avez sélectionné, ce que vous venez de faire. Il écrit dans la même base de données que celle à partir de laquelle UI lit, donc son travail apparaît immédiatement.
+- **Les agents externes peuvent également l'utiliser.** D'autres applications natives d'agent peuvent appeler celle-ci actions via la [A2A protocol](/docs/a2a-protocol). Le code Claude, les applications Codex, les applications MCP personnalisées ChatGPT, le curseur et d'autres hôtes MCP peuvent le piloter comme un [MCP server](/docs/mcp-protocol). Une application, plusieurs points d'entrée.
+
+Il s'agit de l'échelon 3. Il s'agit d'un agent natif.
+
+```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}"
+}
+```
+
+Voir [Key Concepts — Protocols](/docs/key-concepts#protocols) pour savoir comment tout cela dépend de la même définition d'action.
+
+## Pourquoi chaque agent a besoin d'un UI {#why-every-agent-needs-a-ui}
+
+Même lorsque l'agent fait tout le gros du travail, les humains doivent toujours :
+
+- **Voir ce qu'il fait** — progression, résultat intermédiaire, ce qu'il a touché
+- ** Dirigeez-le ** – donner des commentaires, interrompre, mettre en file d'attente la tâche suivante
+- **Gérez-le** : modifiez ses instructions, skills, la mémoire, les tâches planifiées, les comptes connectés
+- **Inspecter son travail** : examiner les brouillons, l'historique d'audit, annuler les erreurs
+- **Partager ses résultats** : tableaux de bord, rapports, formulaires, liens à envoyer aux coéquipiers
+
+Au minimum, « un UI pour l'agent » est un tableau de bord d'observabilité et de gestion. Au maximum, il s'agit d'une application SaaS complète avec l'agent intégré en tant que copilote. Les deux extrémités comptent comme agent natif, et la surface peut s'étendre à partir d'une seule sans réécriture.
+
+Vous n'êtes pas obligé de choisir une forme à l'avance. L'agent peut fonctionner sans tête, s'asseoir derrière une discussion riche ou vivre dans une application complète autour de la même surface d'action – voir [Agent Surfaces](/docs/agent-surfaces) pour les formes concrètes et les API.
+
+## Pourquoi chaque application bénéficie d'un agent {#why-every-app-benefits-from-an-agent}
+
+Le revers de la médaille est tout aussi important. Les produits SaaS existants se heurtent toujours au même mur : 80 % de ce dont vous avez besoin fonctionne très bien et 20 % ne peuvent tout simplement pas être modifiés. L'ajout d'une barre latérale de discussion résout rarement ce problème : le chat ne peut généralement pas _faire_ les choses que le UI peut faire.
+
+L'agent natif inverse cela. Étant donné que chaque action dans l'application est définie une fois et exposée à la fois comme un bouton et un outil d'agent, l'agent peut faire tout ce que les boutons peuvent faire - et plus encore - sans avoir à gérer un « monde IA » distinct. Le langage naturel devient une entrée de premier ordre aux côtés des clics.
+
+L'argument n'est pas "les agents remplacent UI". C'est "**les agents appartiennent aux applications, avec un UI au sommet, en tant que partenaires égaux**". Même une application dans laquelle l'agent _est_ le produit a toujours besoin d'un UI pour que les humains puissent le superviser, le configurer et le diriger — voir [Agent Surfaces — Headless](/docs/agent-surfaces#headless).
+
+## Parité Agent + UI {#agent-ui-parity}
+
+C'est le principe déterminant.
+
+> **Depuis le UI** : cliquez sur les boutons, remplissez les formulaires, parcourez les vues. Le UI écrit dans la base de données ; l'agent voit les résultats.
+>
+> **De l'agent** — langage naturel, autres agents via A2A, Slack, Telegram. L'agent écrit dans la base de données ; le UI se met à jour automatiquement.
+
+```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}"
+}
+```
+
+Lorsque l'agent crée un brouillon d'e-mail, celui-ci apparaît dans le UI. Lorsque vous cliquez sur « Envoyer », l'agent sait que le message a été envoyé. Il n'y a pas de « monde des agents » et de « monde UI » distincts : c'est un seul système. Voir [Key Concepts](/docs/key-concepts) pour l'architecture qui fait que cela fonctionne.
+
+## Personnalisation généralement réservée aux outils électriques {#workspace-customization}
+
+La raison pour laquelle des outils tels que Claude Code semblent si puissants n'est pas le modèle, mais la **couche de personnalisation** : instructions par projet, skills, mémoire, sous-agents, services connectés. Vous pouvez adapter l'agent à votre base de code, à vos préférences et à votre équipe.
+
+Agent-native offre à chaque utilisateur la même couche de personnalisation, sans jamais quitter l'application. Chaque application est livrée avec un **espace de travail** personnel dans lequel vous (ou n'importe quel membre de votre équipe) pouvez :
+
+- Modifier les règles à l'échelle de l'équipe lues par tous les agents
+- Laissez l'agent mémoriser automatiquement les préférences lorsque vous les corrigez
+- Écrire des guides pratiques réutilisables sous forme de commandes `/slash`
+- Conserver les sous-agents personnalisés pour des tâches spécifiques (invoqués avec `@mentions`)
+- Planifiez les tâches à exécuter sur un cron (par exemple, "tous les lundis matin, résumez la semaine dernière")
+- Connectez les services externes (Gmail, Stripe, Slack, API internes) via des serveurs MCP par utilisateur
+
+Le problème : tout est stocké dans la base de données, pas dans le système de fichiers. Il n'y a pas d'environnement de développement à démarrer, pas de conteneur par utilisateur. Chaque utilisateur dispose de son propre espace de travail complet (mémoire personnelle, connexions personnelles, skills personnel) essentiellement gratuitement, car il s'agit de toutes les lignes d'un tableau. C'est ce qui rend la flexibilité au niveau du code Claude viable dans un véritable produit SaaS multi-tenant.
+
+Voir [Workspace](/docs/workspace) pour le concept complet.
+
+## Qu'est-ce qui le rend différent {#what-makes-it-different}
+
+| Approche                                          | Description                                                                                                                                                                                    |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Applications traditionnelles avec IA intégrée** | L'IA est une réflexion après coup. Limité à la saisie semi-automatique, aux résumés ou à une barre latérale de discussion qui ne peut rien faire dans l'application.                           |
+| **Interfaces de chat/agent pures**                | Puissant mais inaccessible. Pas de tableaux de bord, pas de workflows, pas de persistance. Les non-développeurs ne peuvent pas les utiliser efficacement.                                      |
+| **Code Claude / Codex pour SaaS**                 | Idéal pour les développeurs sur leurs propres machines. Cela ne se traduit pas par un SaaS multi-tenant : une base de code par utilisateur sur une boîte de développement n'est pas évolutive. |
+| **Applications natives pour agents**              | L'agent est un citoyen de première classe. Il partage la même base de données, le même état et peut faire tout ce que le UI peut faire — et vice versa.                                        |
+
+## Développement de toute l'équipe {#whole-team-development}
+
+L'agent natif n'est pas réservé aux développeurs. Étant donné que l'agent peut modifier le propre code de l'application, le développement d'une application cesse d'être une activité réservée aux développeurs :
+
+- **Les concepteurs** mettent à jour les conceptions directement dans l'application en cours d'exécution via l'agent
+- **Les chefs de produit** ajoutent des fonctionnalités et mettent à jour les flux en les décrivant
+- **QA** teste l'application et demande à l'agent de réparer ce qui ne fonctionne pas
+- **Tous les membres de l'équipe** contribuent via le langage naturel
+
+La vision : moins de transferts, une seule personne effectuant le travail d'une petite équipe.
+
+## Fork et personnaliser {#fork-and-customize}
+
+Les applications natives d'agent suivent un modèle de type "fork-and-customize". Vous partez d'un **modèle** : calendrier, contenu, diapositives, analyses, courrier, clips, conception, formulaires, répartition – et vous vous l'appropriez. Chacun est un produit SaaS complet et fonctionnel que vous vendez en gros, et non un échafaudage vierge :
+
+1. Choisissez un modèle sur [agent-native.com/templates](/templates)
+2. Utilisez-le immédiatement en tant qu'application hébergée (par exemple mail.agent-native.com)
+3. Forkez-le lorsque vous souhaitez personnaliser : "connectez notre compte Stripe", "ajoutez un graphique de cohorte"
+4. L'agent modifie le code pour correspondre à vos besoins
+5. Déployez votre fork sur votre propre domaine — ou restez sur agent-native.com
+
+Comme il s'agit de _votre_ application, et non d'une infrastructure partagée, l'agent peut faire évoluer le code en toute sécurité. Votre application continue de s'améliorer au fur et à mesure que vous l'utilisez. Voir [Templates](/docs/cloneable-saas) pour l'histoire complète.
+
+Vous n'êtes pas prêt à créer un modèle complet ? Vous pouvez également essayer l'agent natif en ajoutant une **compétence** à un agent de codage que vous utilisez déjà : installez la compétence Plans avec `npx @agent-native/core@latest skills add visual-plan`. Voir le [Skills Guide](/docs/skills-guide#app-backed-skills).
+
+## Agents composables {#composable-agents}
+
+Les applications natives des agents peuvent communiquer entre elles. Depuis l'application de messagerie, vous pouvez marquer l'agent d'analyse pour interroger les données et inclure le résultat dans un brouillon d'e-mail. Les agents découvrent quels autres agents sont disponibles, se répartissent le travail et affichent les résultats dans le UI dans lequel vous vous trouvez déjà.
+
+Il est alimenté par [A2A](/docs/a2a-protocol) et [MCP](/docs/mcp-protocol) sous le capot (même définition, plusieurs surfaces), mais en tant qu'utilisateur, tout ce que vous devez savoir est "Je peux demander de l'aide à n'importe laquelle de mes applications pour tout ce qu'elles peuvent faire."
+
+## À quoi cela ressemble-t-il dans le code ? {#what-does-it-look-like-in-code}
+
+Si vous créez ou étendez une application native d'agent, voici le modèle central : chaque opération dans l'application est une **action** — définie une fois, disponible à la fois pour l'agent et pour le 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": "Contrat typé", "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 />;
+```
+
+Une action, plusieurs surfaces : l'agent l'appelle comme un outil, le UI l'appelle comme une mutation de type sécurisé, le [native chat](/docs/native-chat-ui) peut restituer des résultats de widget explicites, les agents externes l'atteignent via [A2A](/docs/a2a-protocol) et les hôtes MCP l'appellent via le [MCP server](/docs/mcp-protocol) de l'application, éventuellement avec les ressources UI des applications UI et la télécommande standard MCP OAuth. gérés par le framework. Voir [Actions](/docs/actions) pour la référence complète.
+
+## Quelle est la prochaine étape {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) : commencez par une action, choisissez un modèle ou installez une compétence
+- [**Agent Surfaces**](/docs/agent-surfaces) : choisissez un chat riche, sans tête, un side-car intégré ou une application complète
+- [**Key Concepts**](/docs/key-concepts) — l'architecture : SQL, actions, synchronisation des interrogations, prise en compte du contexte, portabilité
+- [**Templates**](/docs/cloneable-saas) – modèles en tant que produits complets que vous possédez
+- [**Workspace**](/docs/workspace) — la couche de personnalisation par utilisateur (skills, mémoire, instructions, MCP) soutenue par SQL, pas des fichiers
+- [**Dispatch**](/docs/dispatch) : plan de contrôle de l'espace de travail : coffre-fort de secrets, boîte de réception Slack/e-mail, délégation inter-applications
+- [**Extensions**](/docs/extensions) : mini-applications en bac à sable que l'agent crée instantanément sans modification du code
+- [**Drop-in Agent**](/docs/drop-in-agent) : montez le `<AgentPanel>` dans n'importe quelle application React