Agents embed

Cette page vise l'IT d'une entreprise B2B qui a déjà configuré son workspace Gilbert, branché ses intégrations OAuth (Gmail, Calendar, etc.) et calé sa routine quotidienne. Vous voulez maintenant déployer Gilbert comme face publique de votre entreprise : un agent qui qualifie les prospects entrants sur votre site, un autre qui sert les membres de votre équipe en interne.

Exemple concret · une agence immobilière qui pilote son workspace Gilbert :

• Un agent « Site public Acme Immo » embarqué sur la page Contactez-nous de l'agence : il qualifie les prospects entrants (type de bien, budget, zone), crée un dossier et notifie l'équipe commerciale.
• Un agent « Portail interne » sur l'intranet : il présente les services de l'entreprise et oriente les demandes vers la bonne équipe.

Deux agents, même workspace, deux system prompts différents, deux secrets HMAC distincts. Le public ne voit jamais les mails du conseiller ; le conseiller ne voit pas les dossiers prospects de tout le monde.

Workspace = boundary de données. Un workspace est UN tenant : ses dossiers, ses intégrations OAuth, ses repos, ses routines. Les données ne traversent jamais cette frontière.

Agent = boundary de comportement. Un agent est UNE persona / un cas d'usage à l'intérieur de ce tenant. Il utilise la configuration IA de cet espace et dispose de ses propres consignes, de son secret et de son statut. Les outils accessibles restent limités à ceux autorisés pour un visiteur public.

Tout se passe dans le workspace qui portera l'agent : ouvrez-le dans la console, puis l'entrée Agents embarqués du menu (/console/workspaces/:id/agents, réservée aux admins). Vous y voyez les agents de ce workspace. La vue /console/agents les liste tous, tous workspaces confondus.

1. Cliquez « + Nouvel agent » en haut à droite. Un formulaire modal s'ouvre. L'agent sera rattaché au workspace dans lequel vous êtes.
2. Nom, ex : Site public Acme Immo. Le slug est généré automatiquement depuis le nom (kebab-case, alphanumérique, 3-64 chars), modifiable côté API. C'est cette valeur qui ira dans le claim agent du JWT.
3. Source URL (optionnel) : l'URL du site où l'agent sera embarqué. Sert d'aide-mémoire.
4. Sous-titre + Greeting : la ligne d'accroche et le message d'ouverture affichés en haut du chat.
5. System prompt (minimum 50 caractères) : décrit qui est l'agent, son ton, sa mission, ce qu'il doit faire et ne pas faire. Typiquement 500-2000 mots pour un usage sérieux. Voir les patterns plus bas.
6. Suggestions : une par ligne, affichées en boutons cliquables sous le greeting pour amorcer la conversation.
7. Thème : light / dark / auto (suit le système).
8. Créer → un modal coral affiche le secret HMAC une seule fois. Copiez-le immédiatement dans un password manager ou dans la variable d'env GILBERT_AGENT_HMAC du backend client. Il ne sera plus jamais ré-affiché.

Quelques canevas qu'on voit revenir, à adapter à votre métier. Ce sont des starting points, pas des dogmes.

La liste exacte des tools disponibles dépend des intégrations OAuth que vous avez activées sur le workspace (Google, GitHub, LinkedIn) et du template_kind du workspace. Voir Console B2B pour la matrice complète.

Une allowlist de tools par agent permet de limiter ce qu'un agent peut faire, indépendamment des intégrations du workspace. Le pattern de sécurité est simple : un agent site public ne doit jamais pouvoir lire la Gmail privée du dirigeant, même si l'intégration Google est connectée pour d'autres usages.

• Catégorie dossier : update_dossier, propose_solution, request_email, request_auth : utilisables par un agent public, ne touchent pas aux données sensibles.
• Catégorie fichiers : read_file, write_file, delete_file, create_from_template : scope client (jamais exposés à un visiteur en mode guest).
• Catégorie GitHub : github_list_repos, github_propose_sync : pour les agents tournés vers le code.
• Catégorie personal : gmail_search, gmail_read_message, calendar_list_today, create_scheduled_draft, list_routines : pour les assistants internes uniquement, jamais sur un agent public.
• Catégorie utilitaires : fetch_url (SSRF-safe).

Brancher l'agent dans votre site, c'est trois choses :

1. Chaque agent a un secret HMAC unique (32 bytes, généré par Gilbert à la création).
2. Votre backend signe un JWT HS256 avec ce secret, en incluant le claim agent: "<slug>" dans le payload.
3. Gilbert reçoit le JWT côté ?token=, résout l'agent par son slug, vérifie la signature avec son secret (pas le master), puis booste la session avec le system prompt et les tools de cet agent.

import jwt from 'jsonwebtoken'

// Stocké côté backend client : JAMAIS dans le bundle navigateur.
// Récupéré dans la console (Agents embarqués) à la création de l'agent
// (ou après rotation). Variable d'env recommandée : GILBERT_AGENT_HMAC.
const AGENT_SECRET = process.env.GILBERT_AGENT_HMAC
const AGENT_SLUG = 'site-public-acme-immo'

export function signGilbertAgentToken(visitor) {
  const now = Math.floor(Date.now() / 1000)
  return jwt.sign(
    {
      iss: 'solve-web',           // émetteur enregistré côté Gilbert
      aud: 'gilbert',
      product_context: 'solve-web', // legacy : dérivé du workspace si agent
      agent: AGENT_SLUG,           // ← le claim qui route vers cet agent
      sub: visitor?.id ?? null,
      email: visitor?.email ?? null,
      guest: !visitor,
      iat: now,
      exp: now + 600,              // TTL court : 10 minutes
    },
    AGENT_SECRET,
    { algorithm: 'HS256' },
  )
}

Le claim agent est ce qui différencie un JWT « legacy product-only » d'un JWT « agent custom ». Quand il est présent, Gilbert ignore le master secret et utilise uniquement workspace_agents.hmac_secret pour vérifier la sig. Voir JWT SSO pour le format complet du payload.

L'agent public utilise le fournisseur et la clé IA configurés dans son espace. Le repli vers la clé de Solve suit les autorisations de cet espace et du fournisseur concerné. Si aucun fournisseur autorisé n'est disponible, le visiteur reçoit un message d'indisponibilité. La consommation apparaît sous le libellé Agent public, avec les titres de conversation identifiés séparément.

Après validation du jeton, Gilbert établit une session visiteur signée, valable 24 heures. Le navigateur doit accepter les cookies de l'iframe. Un rechargement avec un jeton valide reprend la conversation du même agent tant que cette session reste valide. Changer d'agent ouvre une conversation distincte. Après un changement de contexte dans un autre onglet, rechargez le widget pour reprendre sa session. Les conversations personnelles du visiteur restent dans son espace personnel, même lorsqu'il est déjà connecté à Gilbert.

Un jeton refusé empêche l'ouverture du chat. Générez un nouveau jeton côté serveur et rechargez l'iframe pour rétablir la session. Le cookie est géré par Gilbert ; aucune écriture de cookie n'est à réaliser dans votre application.

Sur la page détail d'un agent (/console/workspaces/:id/agents/:slug) vous trouvez la section Secret HMAC avec un bouton Régénérer le secret.

1. Premier clic : un warning coral s'affiche sous le bouton : « Tous les JWTs signés avec l'ancien secret deviendront invalides. »
2. Second clic : confirmation. Le nouveau secret est généré côté serveur, l'ancien est invalidé instantanément.
3. Le nouveau secret s'affiche dans une carte coral une seule fois. Copiez, puis fermez.

Quatre statuts possibles, draft, active, paused, archived :

• Draft : état par défaut à la création. L'agent est utilisable (les JWTs portant son slug sont acceptés) mais signalé comme non finalisé dans la console.
• Active : l'agent est en production. Les JWTs portant son slug sont acceptés.
• Paused / archived : l'agent refuse les nouvelles connexions : tout JWT avec son slug est rejeté côté exchange. Utile pour désactiver temporairement un agent compromis sans le supprimer (et perdre l'historique).

Le slug est unique en base : un slug archivé reste pris tant que la row n'est pas supprimée. Pour réutiliser un slug, il faut supprimer l'agent (cf. section suivante).

Sur la fiche de l'agent (/console/workspaces/:id/agents/:slug), tout en bas, une zone dangereuse coral. Le bouton Supprimer l'agent est en confirm-twice :

1. Premier clic : le bouton se transforme en « Confirmer la suppression de <nom> » et un bouton « Annuler » apparaît à côté.
2. Second clic : DELETE en base. La row workspace_agents est supprimée définitivement. Tous les JWTs en circulation avec ce slug tomberont sur wrong_issuer (Agent inconnu) au prochain exchange.

Trois cas d'usage qu'on voit régulièrement :

• Public + interne : un agent Site public qualifie les prospects sur le site marketing, un agent Intranet sert les membres de votre équipe sur le portail interne. Deux system prompts, deux allowlists, deux secrets.
• A/B testing : deux agents avec deux system prompts différents sur deux sous-domaines de votre site, comparez les métriques de qualification (taux de dossier créé, longueur moyenne, satisfaction).
• Multi-langue : un agent FR, un agent EN, system prompts traduits, suggestions traduites. Le backend client choisit le slug selon la locale du visiteur.

Dans tous les cas, les données (dossiers, historiques, intégrations) sont partagées par le workspace. Seul le comportement diffère d'un agent à l'autre.

Côté site client, deux choses : le snippet embed.js qui injecte l'iframe, et le JWT signé qui porte le claim agent. Le JWT est passé en query string ?token= sur l'URL de l'iframe (rendue côté backend).

<!-- Sur la page "Contactez-nous" du site Acme Immo -->
<script
  src="https://gilbert.solveholding.com/embed.js"
  data-token="JWT_SIGNE_COTE_SERVEUR"
  data-theme="light"
  defer
></script>

<!-- Votre backend génère le JWT avec le claim agent: site-public-acme-immo
     avant de rendre cette page. -->

• Embed iframe : intégrer l'iframe dans votre page, headers CSP, params.
• JWT SSO : signer un JWT côté backend avec le HMAC propre à l'agent. Exemples Node.js, Python, cURL.
• Console B2B : gérer les workspaces, intégrations OAuth, repos liés. Tout ce dont les tools de votre agent ont besoin.
• API : endpoints /api/gilbert/embed/agents (CRUD agents), notamment PATCH pour modifier l'allowlist côté backend en attendant le picker UI.