@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,294 @@
+---
+title: "Observabilité"
+description: "Traces d'agent, évaluations, commentaires, expériences A/B et tableau de bord intégré, le tout sans configuration."
+---
+
+# Observabilité des agents
+
+Chaque application native d'agent bénéficie d'une observabilité prête à l'emploi. Les traces, les évaluations automatisées, les commentaires des utilisateurs et les expériences A/B fonctionnent sans configuration : toutes les données se trouvent dans la propre base de données SQL de l'application.
+
+Cette page couvre les métriques de *qualité de l'agent* : traces, coûts, évaluations et commentaires stockés dans votre base de données. Pour les analyses de _produit_ (les événements de votre application transmis à PostHog/Mixpanel/Amplitude), voir [Tracking](/docs/tracking).
+
+## Trois choses appelées « évaluations »/« observabilité » – qu'est-ce que je veux ? {#which}
+
+Ces trois pages sont faciles à confondre. Choisissez en fonction de la question que vous posez :
+
+| Page                                                           | La question à laquelle il répond                                           | Quand il s'exécute                                    | Inquiétudes     |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- | --------------- |
+| **Évaluations d'observabilité** (cette page, l'onglet _Evals_) | "Comment se sont déroulés mes véritables cycles de production ?"           | Passif, après chaque course (échantillon du juge LLM) | Qualité         |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)                  | "L'agent fait-il ce qu'il faut sur cette entrée fixe ?"                    | Actif, déterministe, une porte CI/déploiement         | Qualité         |
+| **[Observational Memory](/docs/observational-memory)**         | "Est-ce que ce long fil reste bon marché et à l'intérieur de la fenêtre ?" | Compactage en arrière-plan sur les threads longs      | Coût / contexte |
+
+L'observabilité et CI Eval Gate obtiennent tous deux une _qualité_ mais à partir d'extrémités opposées : notation passive post-hoc du trafic réel par rapport aux contrôles actifs de réussite/d'échec sur les entrées fixes. La mémoire observationnelle n'est pas liée à la qualité ; il s'agit du coût des jetons et de la pression de la fenêtre contextuelle.
+
+## Ce qui est capturé automatiquement {#captured}
+
+Lorsqu'un utilisateur envoie un message, le framework enregistre automatiquement :
+
+- **Utilisation du jeton** — entrée, sortie, lecture du cache, écriture du cache
+- **Coût** — calculé à partir du nombre de jetons et de la tarification du modèle
+- **Latence** – durée totale et durée par appel d'outil
+- **Appels d'outils** — quels actions ont été invoqués, statut de réussite/erreur, durée
+- **Évaluations automatisées** – 5 scores de qualité calculés après chaque exécution
+
+Aucune modification de code n’est nécessaire. L'instrumentation s'accroche de manière transparente au `production-agent.ts`.
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Le tableau de bord {#dashboard}
+
+Ajoutez le tableau de bord à n'importe quel modèle avec un seul itinéraire :
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+Toutes les données sont limitées à l'utilisateur connecté ; il n'existe pas de vue d'administration multi-utilisateurs aujourd'hui.
+
+Le tableau de bord comporte 5 onglets :
+
+| Onglet             | Ce que cela montre                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------- |
+| **Vue d'ensemble** | Mesures clés : exécutions, coût, latence, taux de réussite de l'outil, satisfaction, score d'évaluation |
+| **Conversations**  | Liste de traces avec exploration vers des étendues individuelles (agent_run, llm_call, tool_call)       |
+| **Évaluations**    | Scores d'évaluation automatisés par critères, tendances au fil du temps                                 |
+| **Expériences**    | Liste de tests A/B avec badges de statut, résultats des variantes avec intervalles de confiance         |
+| **Commentaires**   | Flux de pouces vers le haut/vers le bas, répartition par catégorie, scores de frustration               |
+
+## Commentaires des utilisateurs {#feedback}
+
+### Commentaires explicites
+
+Les boutons de pouce vers le haut/vers le bas s'affichent en ligne sur chaque message d'agent dans le chat UI. Le pouce vers le bas ouvre une fenêtre contextuelle de catégorie (Inexact, Pas utile, Mauvais outil, Trop lent). Ceci est automatiquement connecté au `AssistantChat.tsx`.
+
+### Commentaires implicites (indice de frustration)
+
+Le framework calcule un indice de frustration (0-100) à partir des signaux de conversation :
+
+| Signal                        | Poids | Ce qu'il détecte                                    |
+| ----------------------------- | ----- | --------------------------------------------------- |
+| Reformulation                 | 30%   | L'utilisateur répète des messages similaires        |
+| Modèles de nouvelle tentative | 20%   | "Réessayez", "non, c'est faux"                      |
+| Abandon                       | 20%   | La session se termine peu de temps après la réponse |
+| Sentiments                    | 15%   | Modèles de langage négatifs                         |
+| Tendance de longueur          | 15%   | Diminution de la longueur des messages              |
+
+Interprétation des scores : 0-20 = sain, 20-40 = friction, 40-60 = insatisfait, 60+ = session interrompue.
+
+## Évaluations automatisées {#evals}
+
+Cinq scoreurs déterministes s'exécutent après chaque exécution d'agent :
+
+| Critères            | Ce qu'il mesure                                                                 | Plage de scores |
+| ------------------- | ------------------------------------------------------------------------------- | --------------- |
+| `tool_success_rate` | % d'appels d'outils sans erreurs                                                | 0-1             |
+| `step_efficiency`   | Pénalise les itérations LLM excessives pour les exécutions utilisant des outils | 0-1             |
+| `latency_score`     | Normalisé par rapport à la ligne de base de 10 s/outil                          | 0-1             |
+| `cost_efficiency`   | Normalisé par rapport au coût de référence                                      | 0-1             |
+| `error_recovery`    | L'agent a-t-il récupéré des erreurs de l'outil ?                                | 0 ou 1          |
+
+### LLM-en tant que juge (facultatif)
+
+Activez l'évaluation basée sur LLM échantillonnée en définissant `evalSampleRate` :
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+Les critères personnalisés utilisent des rubriques en langage naturel :
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## Expériences A/B {#experiments}
+
+Testez différents modèles, températures ou configurations d'agent :
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+Utilisez les identifiants de modèle réels acceptés par votre moteur à la place de `<your-model-id>` / `<other-model-id>` (les noms de modèles changent souvent — vérifiez votre fournisseur/moteur pour les identifiants actuels). La boucle d'agent résout automatiquement la variante de l'utilisateur et applique le remplacement de la configuration. L'affectation utilise un hachage cohérent : le même utilisateur obtient toujours la même variante.
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Configuration {#config}
+
+Tous les paramètres sont stockés dans la clé `observability-config` :
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## Points de terminaison API {#api}
+
+Tous montés automatiquement sur `/_agent-native/observability/` :
+
+| Méthode | Chemin                     | Objectif                                |
+| ------- | -------------------------- | --------------------------------------- |
+| GET     | `/`                        | Statistiques générales                  |
+| GET     | `/traces`                  | Liste des résumés de trace              |
+| GET     | `/traces/:runId`           | Détails de la trace (résumé + étendues) |
+| GET     | `/traces/:runId/evals`     | Évaluations pour une exécution          |
+| POST    | `/feedback`                | Envoyer des commentaires                |
+| GET     | `/feedback`                | Répertorier les commentaires            |
+| GET     | `/feedback/stats`          | Agrégation de commentaires              |
+| GET     | `/satisfaction`            | Notes de satisfaction                   |
+| GET     | `/evals/stats`             | Statistiques d'évaluation               |
+| POST    | `/experiments`             | Créer un test                           |
+| GET     | `/experiments`             | Liste des tests                         |
+| GET     | `/experiments/:id`         | Obtenir les détails du test             |
+| PUT     | `/experiments/:id`         | Mettre à jour le test                   |
+| POST    | `/experiments/:id/results` | Calculer les résultats                  |
+| GET     | `/experiments/:id/results` | Obtenir des résultats                   |
+
+Tous les points de terminaison prennent en charge les paramètres de requête `?since=N` (horodatage ms) et `?limit=N`.
+
+## Exporter vers des plateformes externes {#export}
+
+Envoyer des traces à Langfuse, Datadog, Grafana ou tout autre backend compatible OTel :
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+Le framework émet des étendues de convention sémantique `gen_ai.*` compatibles avec la spécification OpenTelemetry GenAI.
+
+## Étendues OpenTelemetry {#otel}
+
+Séparée de la configuration `exporters` ci-dessus (qui envoie les traces internes à un point de terminaison OTLP), la boucle d'agent peut également émettre des **spans OpenTelemetry en direct** pour chaque exécution, appel de modèle et appel d'outil — de sorte qu'un hôte qui exécute déjà un collecteur OTel voit l'activité de l'agent aux côtés du reste de ses traces distribuées.
+
+Cette couche est **facultative et non opérationnelle par défaut** :
+
+- `@opentelemetry/api` est une **dépendance facultative**. S'il n'est pas installé, les assistants se dégradent en mode silencieux - rien ici n'est jamais jeté dans la boucle de l'agent.
+- Même lorsque le package API _est_ présent, il fournit un traceur sans opération par défaut. Les étendues ne deviennent réelles qu'une fois que le **hôte enregistre un `TracerProvider`** (via `@opentelemetry/sdk-node` ou similaire). Le framework ne dépend délibérément **pas** des packages lourds SDK/exporter ni n'enregistre un fournisseur lui-même - l'instrumentation est activée par l'application d'intégration.
+
+Ainsi, le coût lorsque vous n'avez pas câblé OTel est de quelques lectures de propriétés mises en cache par appel. Pour l'activer, installez le package API ainsi que votre SDK et enregistrez un fournisseur au démarrage du serveur de la même manière que vous le feriez pour tout autre service Node.
+
+La boucle d'agent émet trois types de span :
+
+| Portée      | Quand                          | Attributs                                                         |
+| ----------- | ------------------------------ | ----------------------------------------------------------------- |
+| `agent.run` | une fois par exécution d'agent | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | une fois par appel d'action    | `tool.name`, plus statut de réussite/erreur                       |
+| `llm.call`  | par appel de modèle            | timing + état OK/erreur                                           |
+
+Les travées sont terminées avec l'état OK/ERROR et enregistrent le message d'erreur en cas d'échec. Les valeurs des attributs zéro/sentinelle sont élaguées afin que les étendues ne soient pas encombrées de bruit. Cette couche OTel est purement additive aux tables internes `agent_trace_spans` / `agent_trace_summaries` qui alimentent le tableau de bord ci-dessus : les deux sont produites à partir des mêmes événements d'exécution.
+
+## Rapport d'erreurs (Sentry) {#sentry}
+
+Les erreurs côté serveur qui échappent aux gestionnaires de route Nitro sont signalées à Sentry lorsqu’un DSN est configuré. Sans cela, le SDK ne fonctionne silencieusement, il est donc prudent de laisser les variables d'environnement non définies dans le développement. Les événements du navigateur et du serveur peuvent être dirigés vers le même projet Sentry ; divisez-les en projets distincts uniquement lorsque vous souhaitez une séparation opérationnelle pour la propriété, le volume, les quotas ou le routage des alertes.
+
+| Surface            | SDK               | Variable d'environnement                                      | Remarques                                                                                    |
+| ------------------ | ----------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Navigateur / SPA   | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`, `SENTRY_CLIENT_DSN` ou `SENTRY_DSN` | Capture les erreurs non gérées et le fil d'Ariane de changement d'itinéraire dans le client. |
+| Serveur Nitro      | `@sentry/node`    | `SENTRY_SERVER_DSN` ou `SENTRY_DSN`                           | Capture les réponses 5xx et les erreurs de cycle de vie Nitro. Utilisateur par requête.      |
+| `agent-native` CLI | `@sentry/node`    | _hardcoded_                                                   | Rapports de crash du binaire CLI publié ; non configurable par l'utilisateur.                |
+
+### Configuration côté serveur {#sentry-config}
+
+Définissez `SENTRY_SERVER_DSN` ou le `SENTRY_DSN` partagé dans l'environnement de déploiement (tableau de bord Netlify, secrets Cloudflare, etc.). Le framework monte automatiquement un plugin Nitro qui :
+
+1. Appelle `Sentry.init` une fois au démarrage (idempotent : appel sécurisé à partir de plusieurs plugins).
+2. Résout l'utilisateur via `getSession(event)` pour chaque demande API/framework et attache `id` / `email` / `username` ainsi qu'une balise `orgId` à la portée d'isolation par demande de Sentry. Les chemins d'actifs statiques sont ignorés pour éviter des accès supplémentaires à la base de données.
+3. Capture chaque framework-route 5xx avec les balises `route`, `method` et `userAgent` consultables.
+
+Boutons optionnels :
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (float `0`–`1`) : activez le suivi des performances. La valeur par défaut est `0` (erreurs uniquement). Les valeurs non valides se limitent à `0`.
+- `AGENT_NATIVE_RELEASE` : remplace la balise `release`. La valeur par défaut est `agent-native-server@<core-version>`.
+
+### Modèles
+
+Chaque modèle en hérite automatiquement : il n'y a rien à importer. Pour les applications SSR, le serveur injecte un petit script de configuration de navigateur lorsque `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN` ou `SENTRY_DSN` partagé est disponible au moment de l'exécution, de sorte que la capture du navigateur n'est pas limitée à l'environnement de construction Vite. Les modèles qui souhaitent un comportement personnalisé (balises supplémentaires, DSN différent par modèle, Sentry désactivée) peuvent remplacer en exportant leur propre plugin depuis `server/plugins/sentry.ts` :
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+Le DSN codé en dur du CLI est intentionnel : le binaire publié doit téléphoner aux plantages, quel que soit l'environnement qui l'exécute. Le module serveur ne code jamais en dur un DSN car il s'exécute dans des environnements clients où les opérateurs décident si les erreurs doivent atteindre Sentry.
+
+### Confidentialité et PII {#privacy}
+
+Le serveur et CLI s'initialisent avec `sendDefaultPii: false` et un hook `beforeSend` qui supprime :
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (collecté automatiquement sans consentement)
+- `contexts.runtime_env` (instantané d'environnement de processus)
+- Tout événement dont le type d'exception de niveau supérieur est `ValidationError` (traité comme un rejet attendu d'une entrée utilisateur, et non comme un bug).
+
+Les champs d'identité explicitement définis via `setUser({ id, email, username })` sont conservés.
+
+## Quelle est la prochaine étape
+
+- [**Tracking**](/docs/tracking) – analyses de produits (PostHog, Mixpanel, Amplitude) pour les propres événements de votre application
+- [**Actions**](/docs/actions) — les opérations qui apparaissent sous forme d'appels d'outils dans les traces
+- [**Security**](/docs/security) – Portée des données et gestion des informations d'identification

package/docs/content/locales/fr-FR/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "Mémoire d'observation"
+description: "Compactage en arrière-plan à trois niveaux (bruts récents → observations → réflexions) qui maintient les longs threads d'agent bon marché et stables dans le cache d'invite sans toucher aux conversations courtes."
+---
+
+# Mémoire d'observation
+
+Un thread d'agent de longue durée accumule une énorme transcription : chaque message, chaque appel d'outil, chaque résultat. Rejouer toute cette histoire dans le modèle à chaque tour coûte cher et finit par faire exploser la fenêtre contextuelle. La **mémoire d'observation (OM)** compacte la partie la plus ancienne d'un long fil de discussion en un résumé daté et superposé afin que le modèle sache toujours ce qui s'est passé (juste pour une fraction du coût du jeton) tandis que les tours les plus récents restent textuellement.
+
+OM est entièrement automatique et limité au propriétaire. **Les threads courts ne sont pas affectés** : jusqu'à ce qu'un thread franchisse le premier seuil de compactage, OM est un non-op et le contexte est octet pour octet ce qu'il serait sans lui.
+
+## Les trois niveaux {#tiers}
+
+OM représente un long fil de discussion composé de trois couches, du plus distillé au plus récent :
+
+| Niveau                     | Qu'est-ce que c'est                                                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Réflexions**             | Niveau le plus élevé, condensé à partir du journal d'observation une fois qu'il devient volumineux. Le résumé en arc long.    |
+| **Observations**           | Des entrées denses et datées qui regroupent une série de messages bruts dans un enregistrement compact de ce qui s'est passé. |
+| **Messages bruts récents** | Les N derniers tours, conservés **textuellement** — jamais pliés — afin que l'agent voie toujours le dernier contexte.        |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+À chaque tour, le côté lecture les assemble en un seul bloc `[Observational Memory]` auto-étiqueté qui remplace l'ancien préfixe brut, conserve la fenêtre brute récente intacte et indique au modèle de traiter l'enregistrement compacté comme faisant autorité (ne refaites pas le travail terminé, faites confiance aux décisions, noms, dates et statuts enregistrés).
+
+## Comment se déroule le compactage {#compaction}
+
+Deux passes s'exécutent comme une étape **de tir et d'oubli, au mieux** _après_ un tour propre, de sorte qu'elles n'ajoutent jamais de latence à la réponse visible par l'utilisateur et que tout échec est avalé :
+
+1. **Observateur** — une fois que les messages _non observés_ d'un fil dépassent le seuil du jeton d'observation, les regroupe en une seule entrée d'observation dense.
+2. **Réflecteur** — une fois que le journal d'observation persistant lui-même dépasse le seuil du jeton de réflexion, condense les observations en une réflexion de niveau supérieur.
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Les deux passent sans opération en dessous de leurs seuils, donc appeler le compacteur après chaque tour est bon marché. Étant donné que OM remplace le préfixe brut volatile par du texte compacté stable, il conserve également l'invite **stable en cache** au fil des tours d'un long thread.
+
+Les données OM résident dans la propre base de données SQL de l'application, limitée au propriétaire (et à l'organisation le cas échéant) – le même modèle de portée que le reste du framework. Il n'est jamais partagé entre les utilisateurs.
+
+## Configuration {#config}
+
+Les valeurs par défaut sont conservatrices. Un opérateur peut composer le compactage au moment du déploiement avec les variables d'environnement `AGENT_NATIVE_OM_*` (aucun redéploiement du code de l'application n'est nécessaire) ; une valeur invalide ou manquante revient toujours à la valeur par défaut nommée.
+
+| Variable d'environnement                      | Par défaut | Ce qu'il contrôle                                                                                     |
+| --------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000`    | Jetons de message non observés qui incitent l'observateur à les regrouper en une seule observation.   |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000`    | Jetons de journal d'observation qui déclenchent la condensation du réflecteur en une réflexion.       |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`       | Combien de messages parmi les plus récents restent textuellement (jamais intégrés à une observation). |
+
+Les capuchons de sortie Observer et Reflector (4 000 / 2 000 jetons) empêchent une seule passe de compactage de faire exploser le budget ; ils sont réglables dans le code via `resolveObservationalMemoryConfig({ ... })` mais ne sont pas exposés à l'environnement.
+
+> [!TIP]
+> Abaissez les seuils pour compacter plus tôt (threads longs moins chers, légèrement plus de résumé) ; augmentez-les pour conserver un historique plus brut dans son contexte avant de les compacter. Définissez `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` plus haut si vos flux de travail nécessitent une queue textuelle plus longue.
+
+## Quand il entre en jeu {#when}
+
+OM ne modifie le comportement que pour les threads suffisamment longtemps pour avoir produit au moins une observation ou une réflexion. Concrètement :
+
+- Un fil de discussion tout nouveau ou court : aucune entrée OM pour l'instant → le contexte est la transcription simple, inchangée.
+- Un long fil de discussion qui a franchi le seuil d'observation : l'ancien préfixe est remplacé par le bloc `[Observational Memory]` compacté, la queue brute récente reste textuellement et l'utilisation des jetons diminue considérablement.
+
+L'injection se fait au mieux et sans danger pour les limites : si un point de découpage sûr ne peut pas être trouvé (par exemple, une paire outil-utilisation/résultat en attente se trouve au bord de la fenêtre), OM injecte le bloc de mémoire _de manière additive_ sans couper plutôt que de risquer de supprimer un résultat d'outil en attente.
+
+## Connexe
+
+- [**Using Your Agent**](/docs/using-your-agent) : la boucle quotidienne de travail avec l'agent ancré à côté de votre application.
+- [**Observability**](/docs/observability) – mesures de jetons et de coûts par exécution, où les économies d'OM apparaissent.
+- [**Custom Agents & Teams**](/docs/agent-teams) : les longues exécutions de sous-agents bénéficient du même compactage.

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

@@ -0,0 +1,216 @@
+---
+title: "Intégration et clés API"
+description: "Liste de contrôle d'installation pour la configuration de première exécution : clés API, OAuth et connexions du fournisseur"
+---
+
+# Intégration
+
+Lorsque vous ouvrez pour la première fois une application construite sur le framework natif d'agent, vous verrez un
+**Liste de contrôle de configuration** dans la barre latérale de l'agent. Il maintient la configuration de première exécution proche
+au chat de l'agent : connectez un moteur d'IA, pointez éventuellement l'application vers partagé
+infrastructure et ajoutez des fournisseurs uniquement lorsque vous en avez besoin.
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## Pour les utilisateurs finaux
+
+### Ce que vous verrez
+
+- Un panneau **Configuration** au-dessus du chat de l'agent avec une liste de contrôle telle que "Connecter une IA
+  moteur", "Envoi par e-mail", etc.
+- Un compteur en haut (par exemple "1 sur 4") indique combien d'étapes sont prêtes.
+- L'étape actuelle est développée ; les étapes terminées affichent une coche verte et restent
+  lisible si vous les ouvrez.
+- Les étapes obligatoires affichent une petite pilule rouge **obligatoire**. Le panneau reste visible
+  jusqu'à ce que chaque étape requise soit terminée.
+- Une fois que tout le nécessaire est fait, le panneau se cache automatiquement.
+- L'ensemble du panneau peut être réduit avec le chevron en haut à droite, ou
+  entièrement masqué avec **Masquer la configuration** en bas.
+
+### Comment terminer chaque étape
+
+Les étapes proposent une ou plusieurs **méthodes** : différentes manières de satisfaire la même chose
+exigence. Le chemin principal est affiché en premier ; les chemins secondaires restent compacts
+derrière un sélecteur ou une divulgation lorsqu'une étape a plusieurs fournisseurs équivalents.
+
+- **Connectez un service (un clic)** — par ex. _Connectez Builder_ pour le géré
+  Passerelle IA. Cliquez sur le bouton, une fenêtre s'ouvre, vous vous connectez, la fenêtre se ferme,
+  et l'étape est marquée comme terminée. Aucune clé à copier.
+- **Collez une clé API ou remplissez un formulaire** — par ex. choisissez un fournisseur LLM, une base de données,
+  Fournisseur OAuth ou fournisseur de messagerie, collez la ou les valeurs, cliquez sur **Enregistrer**.
+  Les champs secrets utilisent une saisie de mot de passe afin que la valeur ne soit pas affichée à l'écran. Enregistré
+  les valeurs vont dans votre `.env` local (ou dans les paramètres de l'espace de travail) – voir
+  [Security](/docs/security) pour l'endroit où ils habitent.
+- **Ouvrir un lien** : certaines étapes pointent vers une page de connexion ou des documents. Cliquez
+  **Continuer** et terminer le flux dans le nouvel onglet.
+- **Demandez à l'agent** : quelques étapes proposent une option "Laisser l'agent le configurer".
+  Cliquez dessus et l'agent répond dans le chat et vous guide à travers n'importe quelle étape
+  configuration externe (création d'identifiants OAuth, etc.).
+
+### Les étapes intégrées que vous verrez habituellement
+
+- **Connecter un moteur IA** (obligatoire) : la seule étape obligatoire. Se connecter
+  Builder pour une passerelle gérée en un clic, ou ouvrez la clé du fournisseur secondaire
+  sélectionnez et collez votre propre clé LLM.
+- **Base de données** (facultatif) — définissez `DATABASE_URL` lorsque vous souhaitez utiliser un fichier spécifique
+  Chaîne de connexion à la base de données SQL.
+- **Authentification** (facultatif) – les comptes de messagerie/mot de passe intégrés fonctionnent par
+  par défaut. Ajoutez OAuth ou une connexion par jeton d'accès uniquement lorsque vous souhaitez ces chemins.
+- **Envoi par e-mail** (facultatif) — utile avant le déploiement pour la réinitialisation du mot de passe,
+  invitations d'équipe et notifications de partage. Utilisez le fournisseur que vous utilisez déjà ;
+  le développement local peut fonctionner sans lui.
+
+Les modèles peuvent ajouter leurs propres étapes par-dessus celles-ci – par ex. un modèle CRM pourrait
+ajoutez « Connecter Gmail », un modèle de documentation peut ajouter « Choisir un espace de travail par défaut ». Voir
+[Authentication](/docs/authentication) pour les détails de configuration de la connexion.
+
+### Revenir à la liste de contrôle
+
+Si vous cliquez sur **Masquer la configuration**, le panneau disparaît pour cette session de navigateur.
+Les étapes obligatoires qui ne sont pas encore terminées réapparaîtront lors du prochain chargement. Une fois
+tout ce qui est nécessaire est fait, le panneau se cache automatiquement pour de bon – il n'y a rien
+reste à faire.
+
+## Pour les développeurs
+
+Si vous créez un modèle, vous enregistrez les étapes d'intégration afin qu'elles apparaissent dans
+la liste de contrôle de la barre latérale de l'utilisateur. Le framework gère le rendu, la complétion
+suivi et licenciement – vous déclarez simplement quelle est l'étape et comment elle se déroule
+satisfait.
+
+Le système est **monté automatiquement**. Les modèles n'ont pas besoin de câbler quoi que ce soit pour obtenir
+les quatre étapes intégrées (LLM, base de données, authentification, e-mail). Pour ajouter des informations spécifiques à l'application
+étapes (Gmail, Slack, Notion, etc.), appeler `registerOnboardingStep()` depuis un
+plug-in serveur.
+
+### Itinéraires montés automatiquement
+
+Tous les itinéraires sont en direct sous `/_agent-native/onboarding/` :
+
+| Itinéraire                                          | Objectif                                        |
+| --------------------------------------------------- | ----------------------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | Répertorier les étapes avec l'état d'achèvement |
+| `POST /_agent-native/onboarding/steps/:id/complete` | Marquer l'étape terminée (remplacement)         |
+| `POST /_agent-native/onboarding/dismiss`            | Ignorer la bannière d'intégration               |
+| `POST /_agent-native/onboarding/reopen`             | Effacer le licenciement (réafficher le panneau) |
+| `GET /_agent-native/onboarding/dismissed`           | Lire le licenciement + l'indicateur allComplete |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### Ajouter une étape à partir d'un modèle
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### Vérification des connexions à l'espace de travail lors de l'intégration
+
+Lors de la création de modèles qui interagissent avec des services externes (tels que Slack, Google Workspace, GitHub ou HubSpot), vous devez vérifier si l'espace de travail s'est déjà connecté et a accordé à ce fournisseur la connexion à votre application. Cela évite aux utilisateurs d'avoir à dupliquer les informations d'identification (telles que les clés API ou les jetons d'actualisation) dans leurs variables d'environnement locales lorsqu'une connexion centrale gérée existe.
+
+Vous pouvez vérifier l'état de préparation de la connexion dans votre rappel `isComplete` à l'aide du catalogue de connexions API :
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+Référez-vous à la documentation [Workspace Connections](/docs/workspace-connections) pour la liste complète des méthodes du catalogue des fournisseurs de connexion.
+
+### Types de méthodes
+
+| Gentil             | Charge utile                                          | Utiliser pour                                                         |
+| ------------------ | ----------------------------------------------------- | --------------------------------------------------------------------- |
+| `link`             | `{ url, external? }`                                  | Envoyer l'utilisateur vers un flux OAuth ou une page de documentation |
+| `form`             | `{ fields, writeScope? }`                             | Collecter les variables d'environnement (clés, secrets, URL)          |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra)                                |
+| `agent-task`       | `{ prompt }`                                          | Envoyer une invite au chat de l'agent pour gérer                      |
+
+L'indicateur `primary: true` marque une méthode comme le grand CTA pour son étape.
+Utilisez `badge: "soon"` plus `disabled: true` lorsqu'un chemin de configuration doit être visible
+avant qu'il ne soit disponible.
+
+### Étapes intégrées
+
+| ID         | Obligatoire | Description                                                     |
+| ---------- | ----------- | --------------------------------------------------------------- |
+| `llm`      | oui         | Connexion Builder ou clé LLM du fournisseur                     |
+| `database` | non         | Base de données par défaut ou n'importe quel SQL `DATABASE_URL` |
+| `auth`     | non         | Comptes intégrés, OAuth ou jeton d'accès en option              |
+| `email`    | non         | Renvoyer ou SendGrid pour les e-mails transactionnels           |
+
+N'importe lequel de ces éléments peut être annulé en vous réinscrivant avec le même `id` après le
+Chargement des valeurs par défaut.
+
+### Utilisation des clients
+
+Le panneau est déjà à l'intérieur du `<AgentPanel>`. Pour créer une mise en page personnalisée :
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+Pour en savoir plus sur l'emplacement de stockage des valeurs d'étape et la manière dont les secrets sont gérés,
+voir [Security](/docs/security). Pour les points de contact de messagerie de l'utilisateur final (invitations,
+réinitialisations du mot de passe) qui dépendent de l'étape **Envoi par e-mail**, voir
+[Messaging](/docs/messaging).