@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/fr-FR/embedding-sdk.md

@@ -0,0 +1,597 @@
+---
+title: "Intégration de SDK"
+description: "Intégrez un side-car Agent-Native dans une application SaaS existante avec un contexte de page et des commandes d'hôte."
+---
+
+# Intégration de SDK
+
+Intégrez Agent-Native dans un produit existant : conservez votre application SaaS, ajoutez un produit durable
+side-car de l'agent, et laissez cet agent voir et opérer sur la page sur laquelle se trouve l'utilisateur
+utilise déjà. Si vous hésitez encore entre des agents sans tête, un chat enrichi, un
+side-car intégré ou application complète, commencez par
+[Agent Surfaces](/docs/agent-surfaces).
+
+```an-diagram title="The embedding membrane" summary="The host app supplies server-side auth and live page context; Agent-Native runs the durable sidecar and reaches the open tab through client actions and host commands."
+{
+  "html": "<div class=\"diagram-embed\"><div class=\"diagram-box\" data-rough><strong>Host SaaS app</strong><small class=\"diagram-muted\">your UI, your auth</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">getContext &rarr;</div><div class=\"diagram-pill\">&larr; client actions</div><div class=\"diagram-pill\">&larr; host commands</div></div><div class=\"diagram-panel center\" data-rough><strong>Agent-Native sidecar</strong><small class=\"diagram-muted\">durable chat · app state · extensions</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL<br><small class=\"diagram-muted\">framework tables</small></div></div>",
+  "css": ".diagram-embed{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-embed .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-embed .diagram-arrow{font-size:22px;line-height:1}.diagram-embed .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Commencez ici : le plugin avec piles incluses {#batteries-included}
+
+Pour la plupart des hôtes SaaS, **utilisez le runtime intégré complet** : le plug-in du serveur
+`createAgentNativeEmbeddedPlugin` plus le client `<AgentNativeEmbedded>`
+composant. C'est la valeur par défaut recommandée : il réutilise l'intégralité du framework
+(actions, état de l'application basée sur SQL, extensions, outils de session de navigateur) et donne le
+agent la possibilité de voir et d'opérer sur la page que l'utilisateur utilise déjà.
+
+L'hôte monte les routes du serveur Agent-Native dans son application existante, transmet son
+utilisateur connecté à Agent-Native et affiche la barre latérale React dans le produit UI.
+Agent-Native utilise le déploiement de l'hôte, la session hôte et la configuration
+`DATABASE_URL` pour gérer ses propres tables framework : fils de discussion, paramètres,
+état de l'application, extensions, données d'extension, secrets, sessions de navigateur et
+itinéraires d'action.
+
+```bash
+pnpm add @agent-native/core
+```
+
+Sur le serveur :
+
+```ts
+// server/plugins/agent-native.ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+import { builderActions } from "../agent-native/actions";
+import { getBuilderSession } from "../auth";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.DATABASE_URL,
+  auth: async (event) => {
+    const session = await getBuilderSession(event);
+    if (!session) return null;
+    return {
+      userId: session.user.id,
+      email: session.user.email,
+      name: session.user.name,
+      orgId: session.organization.id,
+      orgRole: session.organization.role,
+    };
+  },
+  actions: builderActions,
+  agentChat: {
+    appId: "builder",
+    systemPrompt:
+      "You are Builder's embedded agent. Use Builder actions for durable work.",
+  },
+});
+```
+
+Sur le client :
+
+```tsx
+import {
+  AgentNativeEmbedded,
+  defineClientAction,
+} from "@agent-native/core/client";
+
+export function BuilderAppShell({ children, content, editor }) {
+  return (
+    <AgentNativeEmbedded
+      defaultOpen
+      session={{
+        id: browserTabId(),
+        label: "Builder editor",
+      }}
+      getContext={() => ({
+        route: {
+          name: "builder-editor",
+          pathname: window.location.pathname,
+          params: { contentId: content.id },
+        },
+        resource: {
+          type: "content",
+          id: content.id,
+          name: content.name,
+        },
+        user: currentUser(),
+        organization: currentOrganization(),
+      })}
+      actions={[
+        defineClientAction({
+          name: "select-element",
+          description: "Select an element in the visual editor",
+          schema: {
+            type: "object",
+            properties: { elementId: { type: "string" } },
+            required: ["elementId"],
+          },
+          run: ({ elementId }) => editor.select(elementId),
+        }),
+      ]}
+      onRefresh={() => queryClient.invalidateQueries()}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRemount={() => setAppKey((key) => key + 1)}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+Ce mode est le mode par défaut recommandé car il réutilise l'intégralité du framework : le backend actions est monté sous `/_agent-native/actions`, l'agent peut appeler le même actions que le UI, les extensions créées par l'utilisateur sont stockées dans SQL, le `extensionData` est durable et limité à l'utilisateur/à l'organisation, et les outils de session de navigateur permettent à l'agent backend d'inspecter ou d'utiliser l'onglet actuellement ouvert.
+
+L'authentification de l'hôte est côté serveur. Ne transmettez pas l’identité du navigateur comme source de vérité ; utilisez l'objet de requête/session de l'hôte ou un jeton de courte durée vérifié par le serveur. Si l'hôte n'expose pas les e-mails, renvoyez un `userId` stable et Agent-Native l'utilisera comme clé de propriétaire.
+
+### Isolement de base de données
+
+Le mode intégré gère les tables Agent-Native dans SQL. Pour un produit SaaS mature, la valeur par défaut la plus sûre est **même hébergement et authentification, base de données/schéma Agent-Native dédié** :
+
+```ts
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+L'utilisation du `DATABASE_URL` principal du produit hôte est prise en charge, mais faites-en un choix explicite. Agent-Native crée des tables de structure telles que `settings`, `application_state`, `tools`, `tool_data`, des tables de session de navigateur, des secrets, des fils de discussion et des index associés. Une base de données/un schéma dédié évite les collisions de noms de tables, maintient clairement la propriété des tables gérées et facilite le raisonnement de la politique de sauvegarde/rétention. Si vous partagez intentionnellement la base de données hôte, examinez d'abord les noms de tables existantes et traitez les tables Agent-Native comme appartenant au framework.
+
+## Autres modes {#other-modes}
+
+Le plugin ci-dessus avec piles incluses est la voie heureuse. Achetez-en un
+uniquement lorsque cela correspond mieux à votre situation :
+
+| Mode                                   | Utilisez-le quand                                                                                                                                     | Forfait                                             |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **Sélecteur d'applications intégrées** | Lancement d'une application Agent-Native complète en tant qu'iframe ciblée (sélecteur d'actifs, générateur de formulaires, panneau d'approbation).    | `@agent-native/embedding`                           |
+| **Pont hôte `<AgentNative>`**          | Applications side-car autonomes ou iframes d'origine croisée qui relient manuellement le contexte de la page et le client actions.                    | `@agent-native/core/client`                         |
+| **Extensions portables**               | Permettre aux utilisateurs hôtes de créer des mini-applications en bac à sable lorsque le SaaS possède déjà le stockage/l'approbation des extensions. | Emplacement d'extension `@agent-native/core/client` |
+
+Le package `@agent-native/embedding` de niveau inférieur expose :
+
+| Chemin d'importation               | Ce qu'il fournit                                                                              |
+| ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| `@agent-native/embedding`          | Composant de sélecteur `EmbeddedApp`, `getA2AUrl`, `getMcpUrl`, `sendMessage` (diffusion A2A) |
+| `@agent-native/embedding/react`    | Crochets et composants spécifiques à React                                                    |
+| `@agent-native/embedding/bridge`   | `announceEmbeddedAppReady`, `sendEmbeddedAppMessage` — utilisés dans l'application intégrée   |
+| `@agent-native/embedding/agent`    | Assistants de point de terminaison d'agent                                                    |
+| `@agent-native/embedding/protocol` | Types de protocoles                                                                           |
+
+```bash
+pnpm add @agent-native/embedding
+```
+
+### Application intégrée et mode sélecteur
+
+Utilisez `@agent-native/embedding` lorsque le produit hôte souhaite lancer une version complète
+Application Agent-Native en tant que surface iframe ciblée : un sélecteur d'éléments, un générateur d'éléments,
+Générateur de formulaires, sélecteur d'emplacements de calendrier, panneau d'approbation ou tout autre outil spécifique à une tâche
+flux de travail. Celui-ci est intentionnellement plus petit que le pont hôte side-car ci-dessous : le
+iframe annonce qu'il est prêt, l'hôte peut envoyer des messages nommés et les messages intégrés
+l'application peut émettre des événements de domaine tels que `chooseAsset` ou `close`.
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+export function AssetPickerDialog({ close }) {
+  return (
+    <EmbeddedApp
+      url="https://assets.agent-native.com/picker"
+      className="h-full w-full"
+      onLoad={(ref) => {
+        ref.postMessage("configure", {
+          prompt: "Editorial blog hero",
+          aspectRatio: "16:9",
+        });
+      }}
+      onMessage={(name, payload) => {
+        if (name === "chooseAsset") {
+          const asset = payload as { url: string; altText?: string };
+          insertAsset(asset.url, asset.altText);
+          close();
+        }
+        if (name === "close") close();
+      }}
+    />
+  );
+}
+```
+
+Dans l'application intégrée, utilisez le pont du navigateur pour annoncer que vous êtes prêt et envoyer
+événements renvoyés à l'hôte :
+
+```ts
+import {
+  announceEmbeddedAppReady,
+  sendEmbeddedAppMessage,
+} from "@agent-native/embedding/bridge";
+
+announceEmbeddedAppReady({ app: "assets", mode: "picker" });
+sendEmbeddedAppMessage("chooseAsset", {
+  url: asset.previewUrl,
+  assetId: asset.id,
+  altText: asset.altText,
+});
+```
+
+Assets émet également `chooseImage` comme alias de compatibilité pour les anciens sélecteurs d'images
+hôtes ; les nouvelles intégrations devraient écouter `chooseAsset`.
+
+Pour les applications propriétaires hébergées, activez Cross-App SSO avec Dispatch comme identité
+hub pour que `content.agent-native.com` et `assets.agent-native.com` relient les utilisateurs par
+e-mail vérifié. Les lancements d'Iframe doivent toujours utiliser des applications de courte durée et à portée d'itinéraire
+intégrer des sessions lorsqu'elles ont besoin d'une résilience aux cookies tiers ; cookies d'application normaux
+ne constituent pas à eux seuls une histoire d'authentification intégrée complète.
+
+Le même package inclut des assistants de point de terminaison d'agent pour la découverte de protocoles et
+diffusion de texte sur A2A :
+
+```ts
+import { getA2AUrl, getMcpUrl, sendMessage } from "@agent-native/embedding";
+
+getMcpUrl("https://assets.agent-native.com");
+getA2AUrl("https://assets.agent-native.com");
+
+for await (const chunk of sendMessage(
+  "https://assets.agent-native.com",
+  "Generate a blog hero",
+)) {
+  append(chunk);
+}
+```
+
+### Application hôte (pont hôte `<AgentNative>`)
+
+> Le plugin ci-dessus avec piles incluses est préférable. Utilisez ce pont de niveau inférieur
+> uniquement pour les applications side-car autonomes ou les iframes d'origine croisée dans lesquels vous câblez la page
+> contexte et client actions vous-même.
+
+Pour les applications side-car autonomes ou les iframes d'origine croisée, utilisez le `<AgentNative />` de niveau inférieur. Il restitue le contexte de la page side-car et des fils iframe, le client en direct actions et les commandes d'actualisation/navigation de l'hôte en un seul endroit :
+
+```tsx
+import { AgentNative, defineClientAction } from "@agent-native/core/client";
+
+export function AssistantDock({ customer, sessionToken }) {
+  return (
+    <AgentNative
+      agentUrl="https://agent.example.com/workspaces/acme/sidecar"
+      className="h-full w-full"
+      session={{ id: browserTabId(), label: "Customer detail" }}
+      auth={() => ({ token: sessionToken })}
+      screen={{ includeVisibleText: true }}
+      getContext={() => ({
+        route: {
+          name: "customer-detail",
+          pathname: window.location.pathname,
+          params: { customerId: customer.id },
+        },
+        resource: {
+          type: "customer",
+          id: customer.id,
+          name: customer.name,
+        },
+        selection: {
+          ids: getSelectedRowIds(),
+          text: window.getSelection()?.toString() || undefined,
+        },
+        user: currentUser(),
+        organization: currentOrganization(),
+      })}
+      actions={[
+        defineClientAction<{ contentId: string }, { published: true }>({
+          name: "publish-content",
+          description: "Publish a Builder content entry",
+          schema: {
+            type: "object",
+            properties: { contentId: { type: "string" } },
+            required: ["contentId"],
+          },
+          destructive: true,
+          approval: { title: "Publish this entry?", risk: "medium" },
+          run: async ({ contentId }, { refresh }) => {
+            await builderApi.publish(contentId);
+            await refresh({ queryKey: ["content", contentId] });
+            return { published: true };
+          },
+        }),
+        defineClientAction<{ elementId: string }, void>({
+          name: "select-element",
+          description: "Select an element in the live visual editor",
+          schema: {
+            type: "object",
+            properties: { elementId: { type: "string" } },
+            required: ["elementId"],
+          },
+          run: ({ elementId }) => editor.select(elementId),
+        }),
+      ]}
+      onNavigate={(payload) => {
+        const { path } = payload as { path: string };
+        router.navigate(path);
+      }}
+      onRefresh={(payload) => {
+        const { queryKey } = payload as { queryKey?: readonly unknown[] };
+        queryClient.invalidateQueries({ queryKey });
+      }}
+      onRemount={() => setAppKey((key) => key + 1)}
+      onOpenResource={(payload) => openResource(payload)}
+      onRequestApproval={(payload) => approvalDialog.confirm(payload)}
+    />
+  );
+}
+```
+
+Utilisez `screen={false}` si vous souhaitez uniquement un contexte sémantique explicite. Utilisez `screen={{ includeDomHtml: true }}` comme solution de secours pour les applications qui n'ont pas encore mappé leur UI en ID sémantiques et en état de sélection. Le pont hôte n'accepte que les messages provenant de l'origine du `agentUrl` par défaut. Transmettez `agentOrigin` si l'iframe URL est un URL routé/proxy dont l'origine approuvée est différente.
+
+Pour les hôtes non-React, appelez directement `createAgentNativeHostBridge()` et transmettez les mêmes options `getContext`, `actions` et `commands`.
+
+### Côté Iframe
+
+Dans le side-car Agent-Native, utilisez les assistants de trame pour demander le contexte de l'hôte, découvrir la session de navigateur en direct actions, les exécuter ou demander à l'hôte d'effectuer le travail UI. Passez toujours le `hostOrigin` attendu en production :
+
+```ts
+import {
+  announceAgentNativeFrameReady,
+  createAgentNativeHostTools,
+  requestAgentNativeHostActions,
+  requestAgentNativeHostContext,
+  runAgentNativeHostAction,
+  sendAgentNativeHostCommand,
+} from "@agent-native/core/client";
+
+announceAgentNativeFrameReady({ hostOrigin: "https://app.example.com" });
+
+const context = await requestAgentNativeHostContext({
+  hostOrigin: "https://app.example.com",
+});
+
+const liveActions = await requestAgentNativeHostActions({
+  hostOrigin: "https://app.example.com",
+});
+
+await runAgentNativeHostAction(
+  "select-element",
+  { elementId: context.selection?.ids?.[0] },
+  { hostOrigin: "https://app.example.com" },
+);
+
+await sendAgentNativeHostCommand(
+  "refreshData",
+  { queryKey: ["customer", context.resource?.id] },
+  { hostOrigin: "https://app.example.com" },
+);
+
+const hostTools = createAgentNativeHostTools({
+  hostOrigin: "https://app.example.com",
+});
+```
+
+### Pont d'outils médié par le serveur
+
+Pour un collègue de style CLAW, l'iframe peut également enregistrer son onglet de navigateur en direct auprès du backend side-car. L'agent obtient ensuite les outils backend normaux qui mettent une requête en file d'attente, l'iframe la revendique, la page hôte l'exécute et le backend renvoie le résultat à l'agent.
+
+```an-diagram title="Server-mediated browser-session bridge" summary="A backend tool enqueues work; the registered tab claims it, runs it on the live page, and the result returns to the agent — so a backend/Slack/A2A agent can still touch the open tab."
+{
+  "html": "<div class=\"diagram-bridge\"><div class=\"diagram-node\" data-rough>Backend agent<br><small class=\"diagram-muted\">chat · Slack · A2A</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>enqueue request<br><small class=\"diagram-muted\">/_agent-native/browser-sessions</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Live tab claims it<br><small class=\"diagram-muted\">registered bridge</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">result &rarr; agent</div></div>",
+  "css": ".diagram-bridge{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bridge .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Dans l'application side-car, démarrez le pont de session de navigateur une fois lorsque l'iframe est monté :
+
+```tsx
+import { useEffect } from "react";
+import { startAgentNativeBrowserSessionBridge } from "@agent-native/core/client";
+
+export function SidecarRuntime() {
+  useEffect(() => {
+    const bridge = startAgentNativeBrowserSessionBridge({
+      hostOrigin: "https://app.example.com",
+      label: "Builder editor",
+    });
+    return () => bridge.stop();
+  }, []);
+
+  return null;
+}
+```
+
+Le framework monte automatiquement `/_agent-native/browser-sessions`. Une fois le pont exécuté, l'agent side-car peut utiliser :
+
+| Outil                          | Objectif                                                                                 |
+| ------------------------------ | ---------------------------------------------------------------------------------------- |
+| `list-browser-sessions`        | Voir les onglets des hôtes connectés pour l'utilisateur actuel.                          |
+| `view-browser-session`         | Demandez à un onglet en direct le contexte de la page actuelle et un instantané d'écran. |
+| `list-browser-session-actions` | Demandez un onglet en direct pour les manifestes d'action actuels côté client.           |
+| `run-browser-session-action`   | Exécuter une action client en cours via l'onglet en direct.                              |
+| `send-browser-session-command` | Demander à l'hôte d'actualiser, de naviguer, de remonter, de recharger ou d'approuver.   |
+
+Il s'agit du pont à utiliser lorsque l'agent s'exécute sur le backend, dans Slack/Telegram/email ou en tant qu'appelé A2A, mais doit toujours toucher l'onglet actuel du navigateur de l'utilisateur lorsqu'il est ouvert. Si le navigateur est fermé, le backend actions devrait toujours gérer un travail durable et les outils de session du navigateur signaleront qu'aucun onglet actif n'est connecté.
+
+### Actions
+
+Il existe deux classes d'actions :
+
+| Type d'action    | Où il s'exécute                                                    | Fonctionne lorsque le navigateur est fermé ? | Idéal pour                                                                                                                                               |
+| ---------------- | ------------------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Action back-end  | Application side-car, backend API, MCP ou adaptateur d'intégration | Oui                                          | Travail durable comme créer, mettre à jour, publier, synchroniser, envoyer, importer.                                                                    |
+| Action du client | Onglet du navigateur actuel via `<AgentNative actions={...} />`    | Non                                          | Les UI éphémères fonctionnent comme sélectionner un élément, lire l'état de l'éditeur, faire défiler jusqu'à une ligne, copier l'état actuel du canevas. |
+
+Le backend actions doit être le serveur par défaut pour tout ce qui doit survivre aux actualisations, aux navigateurs fermés, aux tentatives ou aux exécutions déclenchées par l'intégration. Ils appartiennent à la couche d'action/outil Agent-Native normale de l'application side-car, où l'agent peut les appeler à partir du chat, des automatisations, des intégrations Slack/Telegram/e-mail et des tâches en arrière-plan.
+
+Le client actions constitue un pont actif vers un onglet de navigateur. L'hôte les annonce avec `source: "client"` et `availability: "browser-session"`, et le side-car doit traiter ce manifeste comme temporaire. Ré-listez actions lorsque l'itinéraire ou la sélection change, et revenez au backend actions lorsque l'onglet disparaît.
+
+### Extensions portables
+
+> Préférez le plugin avec piles incluses lorsque vous souhaitez que Agent-Native gère
+> définitions d'extension, approbation, stockage et extensions créées par l'agent. Utiliser
+> l'emplacement portable ci-dessous uniquement lorsque le SaaS possède déjà ces préoccupations.
+
+Le SDK prend également en charge les extensions définies par l'utilisateur : des mini-applications Alpine.js en bac à sable qu'un SaaS hôte peut restituer dans des emplacements nommés. Utilisez-le lorsque le client souhaite créer ses propres petits panneaux, calculatrices, tableaux de bord ou assistants de flux de travail sur la même surface d'action/contexte que celle utilisée par l'agent.
+
+```tsx
+import {
+  AgentNativeExtensionSlot,
+  createHttpAgentNativeExtensionStorage,
+  defineClientAction,
+} from "@agent-native/core/client";
+
+const storage = createHttpAgentNativeExtensionStorage({
+  endpoint: "/api/agent-native/extensions/storage",
+  headers: () => ({ Authorization: `Bearer ${sessionToken()}` }),
+});
+
+const actions = [
+  defineClientAction({
+    name: "list-at-risk-customers",
+    description: "List customers currently at risk",
+    schema: { type: "object", properties: {} },
+    run: () => crmApi.customers.list({ status: "at-risk" }),
+  }),
+];
+
+const customerHealthExtension = {
+  id: "customer-health",
+  name: "Customer health",
+  description: "Shows at-risk customers and quick notes.",
+  manifest: {
+    slots: ["crm.customer.sidebar"],
+    requestedActions: ["list-at-risk-customers"],
+    requestedCommands: ["openResource", "refreshData"],
+    storageScopes: ["user", "org"],
+  },
+  content: `
+    <div x-data="{
+      customers: [],
+      note: '',
+      async init() {
+        this.customers = await appAction('list-at-risk-customers', {})
+        const row = await extensionData.get('notes', slotContext.customerId, { scope: 'user' })
+        this.note = row?.data?.text || ''
+      },
+      async save() {
+        await extensionData.set('notes', slotContext.customerId, { text: this.note }, { scope: 'user' })
+        await agentNative.refresh({ customerId: slotContext.customerId })
+      }
+    }" x-init="init()" class="space-y-3">
+      <textarea class="w-full rounded-md border bg-background p-2" x-model="note"></textarea>
+      <button class="rounded-md bg-primary px-3 py-2 text-primary-foreground" @click="save()">Save</button>
+    </div>
+  `,
+};
+
+export function CustomerSidebar({ customer, userExtensions }) {
+  return (
+    <AgentNativeExtensionSlot
+      id="crm.customer.sidebar"
+      extensions={[customerHealthExtension, ...userExtensions]}
+      context={{ customerId: customer.id, plan: customer.plan }}
+      actions={actions}
+      storage={storage}
+      storageContext={{
+        userId: currentUser().id,
+        organizationId: currentOrganization().id,
+      }}
+      getContext={() => ({
+        resource: { type: "customer", id: customer.id, name: customer.name },
+      })}
+      commands={{
+        refreshData: async () => queryClient.invalidateQueries(),
+      }}
+    />
+  );
+}
+```
+
+Le manifeste est le contrat d’installation. Lorsque `requestedActions`, `requestedCommands` ou `storageScopes` sont présents, le SDK les applique dans l'hôte avant qu'une requête iframe n'atteigne le pont d'action ou l'adaptateur de stockage. Lorsque `slots` est présent, `AgentNativeExtensionSlot` restitue uniquement l'extension dans les emplacements correspondants. Les hôtes peuvent toujours ignorer la politique par emplacement avec `allowedActions`, `allowedCommands` et `allowedStorageScopes`.
+
+Une extension est simplement HTML. Le moteur d'exécution iframe fournit les mêmes primitives de pont sécurisé à la mini-application :
+
+```html
+<div
+  x-data="{ customers: [], async init() { this.customers = await appAction('list-at-risk-customers', {}) } }"
+  x-init="init()"
+>
+  <template x-for="customer in customers" :key="customer.id">
+    <button
+      class="block w-full rounded-md px-3 py-2 text-left hover:bg-muted"
+      x-text="customer.name"
+      @click="agentNative.command('openResource', { type: 'customer', id: customer.id })"
+    ></button>
+  </template>
+</div>
+```
+
+Globaux disponibles dans l'iframe :
+
+| Aide                           | Objectif                                                                              |
+| ------------------------------ | ------------------------------------------------------------------------------------- |
+| `appAction(name, args)`        | Exécuter une action déclarée par l'hôte.                                              |
+| `agentNative.context()`        | Lire la page hôte actuelle, les ressources, l'emplacement et les données utilisateur. |
+| `agentNative.command(name, p)` | Demandez à l'hôte de naviguer, d'actualiser, de remonter ou d'ouvrir.                 |
+| `agentNative.refresh(payload)` | Raccourci pour `refreshData`.                                                         |
+| `extensionData.*`              | Conserver les données locales de l'extension via l'adaptateur hôte.                   |
+
+Par défaut, `extensionData` utilise le navigateur `localStorage`, ce qui est utile pour les prototypes et les widgets locaux. Les hôtes SaaS de production doivent transmettre un adaptateur `storage` basé sur le backend afin que les données d'extension au niveau de l'utilisateur et de l'organisation soient durables, vérifiables et régies par les autorisations de l'application. L'adaptateur générique HTTP envoie des corps POST comme `{ operation, extensionId, slotId, collection, id, data, options, context }` et attend soit `{ result }`, soit le résultat JSON directement.
+
+Cette couche SDK portable est distincte du magasin d'extensions intégré au framework soutenu par SQL. Dans une application Agent-Native, utilisez les composants `ExtensionSlot`/`EmbeddedExtension` existants et l'action `create-extension`. Dans un scénario d'intégration SaaS hébergé, préférez `createAgentNativeEmbeddedPlugin()` plus `AgentNativeEmbedded` lorsque vous souhaitez que Agent-Native gère les définitions d'extension, l'approbation, le stockage et les extensions créées par les agents. Utilisez `AgentNativeExtensionSlot` uniquement lorsque le SaaS possède déjà les définitions d'extension, l'approbation, la place de marché, le stockage et la facturation.
+
+Modèle de sécurité :
+
+- Les iframes d'extension sont mises en bac à sable sans `allow-same-origin` ; la mini-application ne peut pas lire directement le DOM parent, les cookies ou le runtime de l'application.
+- Les extensions ne peuvent appeler que le actions et les commandes autorisées par le manifeste de l'hôte et de l'extension.
+- Le actions risqué doit définir `destructive` ou `requiresApproval` afin que l'hôte puisse afficher un flux d'approbation.
+- Traitez l'extension HTML créée par l'utilisateur comme non fiable. Examinez les installations du Marketplace, l'utilisation des actions de journalisation et l'étendue du stockage backend par utilisateur/organisation.
+
+### Sessions et onglets
+
+Le pont hôte est limité à une paire iframe/fenêtre hôte. Si le même utilisateur ouvre plusieurs onglets, chaque onglet possède son propre `session`, son propre contexte, sa sélection, son client actions et ses propres réponses de commande en attente. Ne présumez pas qu'une action client découverte dans un onglet peut s'exécuter dans un autre onglet, ou qu'elle existera toujours après la navigation.
+
+Pour les produits multi-onglets, conservez l'état durable dans SQL/backend actions et utilisez le client actions uniquement pour les parties locales des onglets : focalisation d'une ligne, copie de l'état visible de l'éditeur, sélection d'un élément de canevas ou actualisation du cache de requête React actuel. Incluez suffisamment de contexte `route`, `resource` et `selection` pour que le side-car décide si l'onglet actuel est le bon endroit pour exécuter une action de session de navigateur.
+
+### Modèle de commande
+
+Les noms de commandes intégrés sont délibérément en forme d'application et non de base de données :
+
+| Commande                               | Objectif                                                                                     |
+| -------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `navigate`                             | Déplacez l'hôte UI vers un chemin/une vue/une ressource.                                     |
+| `refreshData` / `refresh-data`         | Demander à l'hôte d'invalider les données côté client.                                       |
+| `remountView` / `remount-view`         | Demander à l'hôte de remonter un sous-arbre, par ex. `<App key={key} />`.                    |
+| `hardReload` / `hard-reload`           | Rechargement complet du navigateur.                                                          |
+| `openResource` / `open-resource`       | Ouvrez un objet de domaine spécifique dans l'hôte UI.                                        |
+| `requestApproval` / `request-approval` | Demandez à l'hôte d'afficher un flux de confirmation. Enregistrez un gestionnaire pour cela. |
+
+Si aucun gestionnaire n'est fourni, les valeurs par défaut sécurisées distribuent les événements du navigateur tels que `agentNative:refresh-data` et `agentNative:remount-view`. `requestApproval` n'a pas de gestionnaire par défaut ; enregistrez-en un avant de vous y fier.
+
+### Conseils d'approbation
+
+Marquez le client à risque actions avec `destructive: true` dans son manifeste et exigez l'approbation de l'hôte avant d'exécuter des opérations qui suppriment, publient, envoient, facturent, invitent, partagent ou affectent de toute autre manière les utilisateurs en dehors de la vue actuelle. Le backend actions doit également appliquer ses propres contrôles d'autorisation et d'approbation ; l'approbation de l'hôte est une UX utile, pas une limite de sécurité.
+
+Préférez cette forme :
+
+- La mutation durable s'exécute dans une action backend avec validation, authentification, journalisation d'audit et tentatives.
+- La commande Hôte ouvre une approbation UI ou concentre la ressource affectée.
+- L'action du client gère uniquement l'étape UI en direct qui ne peut pas se produire sur le backend.
+
+### Intégration du runtime
+
+Utilisez `createAgentNativeHostTools()` dans l’iframe side-car lorsque le runtime de votre agent accepte les descripteurs d’outils simples. Il renvoie quatre outils indépendants du framework :
+
+| Outil               | Objectif                                                                                             |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `view-host-screen`  | Lire le contexte sémantique de l'hôte et l'instantané d'écran.                                       |
+| `list-host-actions` | Liste des sessions de navigateur en direct actions exposées par l'onglet actuel.                     |
+| `run-host-action`   | Exécuter une action client en direct par nom.                                                        |
+| `send-host-command` | Envoyer des commandes hôte telles que l'actualisation, la navigation, le remontage ou l'approbation. |
+
+L'assistant renvoie intentionnellement des objets `{ name, description, parameters, execute }` simples afin que les side-cars puissent les adapter à l'appel de fonction AI SDK, Anthropic, OpenAI ou à la forme Agent-Native `ActionEntry` sans coupler ce SDK à un seul environnement d'exécution.
+
+## Forme de produit recommandée
+
+Démarrez l'iframe en premier. Il fonctionne pour Builder.io, les applications SaaS client et les outils d'administration internes sans coupler les cycles de publication ou les hypothèses CSS/runtime.
+
+Le side-car lui-même doit toujours être une application/un modèle Agent-Native : les actions sont la surface du backend API, l'état de l'application soutenu par SQL est la mémoire de l'agent et des intégrations telles que Slack ou Telegram peuvent être acheminées vers la même discussion durable. L'intégration SDK fournit la membrane active entre ce side-car et la page hôte actuelle.