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 vos collaborateurs en interne.

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

• Un agent « Site public Acme Immo » embarqué sur la page Contactez-nousde l'agence — il qualifie les prospects entrants (type de bien, budget, zone), crée un dossier et notifie l'équipe commerciale.
• Un agent « Portail collaborateurs »sur l'intranet — il lit les mails / l'agenda du conseiller connecté (via JWT SSO) et répond à ses questions de la journée.

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 partage les données et intégrations du workspace, mais il a son propre system prompt, son propre secret, son propre statut (active / paused / archived).

Tout se passe sur /console/agents. Vous y voyez la liste des agents existants dans vos workspaces.

1. Cliquez « + Nouvel agent »en haut à droite. Un formulaire modal s'ouvre.
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 allowlistde 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 publicne 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é depuis /console/agents au moment de 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 agentest 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.

Sur la page détail d'un agent (/console/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 /console/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 vos collaborateurs 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 comportementdiffère d'un agent à l'autre.

Côté site client, deux choses : le snippet embed.jsqui 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-product="solve-web"
  data-theme="light"
  defer
></script>

<!-- Puis : votre backend rend un JWT signé avec le claim 'agent: site-public-acme-immo'
     et l'injecte côté client. L'iframe est chargée avec ?token=<JWT>. -->

• 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 PATCHpour modifier l'allowlist côté backend en attendant le picker UI.