Publier un agent

Un agent créé et approuvé ne vit pas seulement dans Abra. Vous pouvez le mettre entre les mains de vos utilisateurs finaux de trois façons : l’embarquer sur un site sous forme de bulle de chat, le partager par un lien où l’utilisateur se connecte avant de discuter, ou l’appeler par API depuis vos propres applications. Ce guide couvre les trois canaux, la gestion des clés API, la traçabilité des conversations et le suivi de la consommation.

Public : administrateurs d’organisation et intégrateurs. Aucune ligne de code n’est nécessaire pour le widget et le lien de partage ; l’API demande un développeur côté client, mais toute la configuration (clés, quotas, domaines) se fait depuis l’interface.

Toute la distribution se pilote depuis une seule page — Agents en API (/agent-ai/api, réservée aux admins) — organisée en trois onglets :

• Setup complet — récupérer le widget et les extraits d’appel (cURL, JavaScript), choisir le mode (clé ou login SSO), prévisualiser l’agent en direct, et gérer les clés API ;
• Dashboard — les indicateurs de consommation et la traçabilité par agent ;
• Conversations — l’explorateur détaillé des échanges.

Le lien de partage SSO, lui, ne demande aucune configuration : c’est simplement l’URL https://votre-abra/a/{slug} de l’agent.

Dans tous les exemples, remplacez https://votre-abra par le domaine réel de votre instance.

---

1. Vue d’ensemble — les trois canaux

Avant de publier, choisissez le canal adapté à votre public. Les trois partagent le même moteur que le chat interne (mêmes outils, mêmes documents RAG, mêmes garde-fous), mais diffèrent par la façon dont l’utilisateur y accède et dont la conversation est attribuée.

Canal	Idéal pour	Connexion de l’utilisateur	Attribution	Effort
Widget embarquable	Site public, intranet, portail	Aucune (clé API) ou login SSO	Par clé, ou par utilisateur réel	Coller un <script>
Lien de partage SSO	Membres et clients identifiés	Connexion requise	Par utilisateur réel	Copier un lien
API (Agents-as-API)	Vos applications, vos scripts	Clé API (Bearer)	Par clé	Développement côté client

Comment choisir ?

• Vous voulez un assistant visible sur une page web, sans écrire de code → widget. Sur un site public, utilisez la variante avec clé (chat anonyme) ; sur un intranet, la variante avec login SSO pour savoir qui a échangé quoi.
• Vous voulez juste envoyer un lien (e-mail, Slack, base de connaissances interne) sans toucher au HTML d’un site → lien de partage SSO.
• Vous voulez brancher l’agent dans votre produit ou vos automatismes (backend, chatbot maison, script métier) → API.

Prérequis communs :

• L’agent doit être approuvé dans votre organisation. Un agent en brouillon n’est ni embarquable ni appelable (l’API répond 404).
• La fonctionnalité Agents en API doit être activée sur l’instance. Si elle est désactivée, tous les endpoints répondent 404 et le widget reste inerte.
• Notez le slug de l’agent — son identifiant court (ex. agent-rh), visible dans l’URL de l’agent et dans le sélecteur d’agents. Deux organisations peuvent réutiliser le même slug sans ambiguïté : la clé (ou la session) tranche à quelle organisation il appartient.

La section « Intégrer un agent » (onglet Setup complet) rassemble le widget et les extraits d’appel pour un agent donné.

---

2. Le widget embarquable

Le widget ajoute une bulle de chat en bas à droite de n’importe quelle page web. Vous collez un seul <script> dans le HTML du site : aucune dépendance, aucun build, aucune configuration CORS à faire côté iframe (elle est servie par Abra, en même origine). Deux variantes selon que vous voulez un chat anonyme ou un chat identifié.

2a. Widget avec clé — chat anonyme

Le visiteur discute sans se connecter. La conversation passe par une clé API que vous créez au préalable (voir §5). Collez ce bloc juste avant </body> :

<script
  src="https://votre-abra/embed/agent.js"
  data-agent="agent-rh"
  data-key="abra_live_..."></script>

• data-agent — le slug de l’agent (obligatoire).
• data-key — une clé API dont le périmètre autorise cet agent.

Le script injecte la bulle et ouvre l’agent dans une iframe servie par Abra. La clé est transmise à l’iframe en interne — elle n’apparaît jamais dans l’URL — mais elle reste lisible dans le code source de la page.

Créez une clé dédiée à ce site. Limitez-la à cet unique agent, fixez-lui un plafond mensuel, un rate-limit et une liste de domaines autorisés (voir §5). Ne réutilisez jamais une clé serveur-à-serveur dans un widget public : une clé exposée dans une page est, de fait, publique.

2b. Widget avec login SSO — aucune clé exposée

Le visiteur se connecte (SSO de votre organisation) avant de discuter. La conversation est alors rattachée à son compte réel, et aucune clé n’est présente dans la page. Remplacez data-key par data-require-login :

<script
  src="https://votre-abra/embed/agent.js"
  data-agent="agent-rh"
  data-require-login="true"></script>

Dans ce mode, la bulle ouvre l’agent dans une fenêtre Abra en contexte « first-party » : le login et la session fonctionnent normalement — ce qui ne serait pas possible dans une iframe tierce, où le navigateur bloque le cookie de session.

Attributs du script

Attribut	Obligatoire	Rôle
data-agent	oui	Slug de l’agent à afficher
data-key	oui (mode clé)	Clé API abra_live_… autorisant l’agent
data-require-login	—	"true" pour le mode login SSO (aucune clé)
data-origin	—	Forcer le domaine de l’instance Abra si le script est recopié sur un autre site

Apparence. La bulle a un rendu standard (bouton rond en bas à droite, fenêtre de chat sobre) : il n’y a pas, à ce jour, d’option de couleur ou de position à passer dans le script. Vous choisissez uniquement l’agent et le mode (clé ou login SSO).

Le snippet à copier-coller ; la case « Exiger un login SSO » bascule entre chat anonyme (clé) et chat identifié (login SSO).

Prévisualiser avant de publier

Depuis la section Intégrer un agent (onglet Setup complet), un Aperçu en direct affiche la bulle telle qu’elle apparaîtra sur votre site, avec l’agent réel. Ouvrez-le, posez quelques questions représentatives, vérifiez le ton et les réponses, puis seulement collez le snippet en production. C’est aussi l’occasion de confirmer que la variante choisie (clé ou SSO) se comporte comme attendu.

L’Aperçu en direct permet de tester le widget avec l’agent réel avant de le mettre en ligne.

---

3. Le lien de partage SSO

Vous voulez simplement partager un lien — par e-mail, dans un intranet, sur un portail — sans toucher au HTML d’un site ? Chaque agent dispose d’une page hébergée par Abra :

https://votre-abra/a/agent-rh

L’utilisateur qui ouvre ce lien se connecte via le SSO de votre organisation, puis discute avec l’agent dans une interface plein écran. La conversation est rattachée à son compte : vous savez exactement qui a échangé quoi, et l’utilisateur retrouve son historique.

C’est le même mécanisme que le widget « login SSO », mais sous forme de lien direct — sans intégration technique. À privilégier pour un usage interne ou pour des clients qui possèdent déjà un compte sur votre instance.

Widget SSO ou lien de partage ? Le résultat pour l’utilisateur est proche (connexion puis chat, conversation nominative). Choisissez le widget SSO si vous voulez la bulle présente en permanence sur vos pages, et le lien si vous voulez juste diffuser une adresse à ouvrir.

---

4. L’API (Agents-as-API)

Pour intégrer l’agent dans votre propre application — backend, script, produit, chatbot maison — appelez-le directement. L’API expose chaque agent approuvé derrière une URL stable, authentifiée par clé, qui renvoie la réponse en temps réel (streaming). C’est le canal des intégrateurs.

Le principe, en quatre points :

1. Une clé API authentifie chaque requête, dans l’en-tête Authorization: Bearer abra_live_… (ou x-api-key). La clé détermine l’organisation et les agents autorisés — vous n’indiquez jamais l’organisation dans l’URL.
2. Un endpoint par agent, identifié par son slug — par exemple POST /api/v1/agents/agent-rh/messages pour un échange en un tour, ou des threads pour conserver l’historique côté serveur.
3. Une réponse en streaming (Server-Sent Events) diffusée au fil de la génération, comme le chat interne.
4. Des garde-fous attachés à la clé : rate-limit par minute, plafond de dépense mensuel, et liste de domaines autorisés (CORS) pour un appel depuis un navigateur.

Aperçu d’un appel minimal — un message, une réponse en streaming :

curl -N -X POST "https://votre-abra/api/v1/agents/agent-rh/messages" \
  -H "Authorization: Bearer abra_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"Bonjour, quelles sont les règles de RTT ?"}'

CORS — appeler l’agent depuis votre frontend

Par défaut, une clé est serveur-à-serveur : aucun en-tête CORS n’est renvoyé, donc un navigateur ne peut pas lire la réponse. Pour appeler l’agent depuis le JavaScript de votre propre site (votre design, votre interface), ajoutez l’origine exacte de la page dans les Domaines autorisés de la clé (ex. https://app.mon-site.com). Abra reflète alors cette origine — et uniquement celle-ci — dans les en-têtes CORS ; jamais *. Rappel : du code navigateur expose la clé, réservez donc ce mode aux clés à périmètre restreint (un seul agent, plafond mensuel serré).

Le cap mensuel et le rate-limit

Deux garde-fous protègent votre budget et votre instance :

• Rate-limit (par minute) — au-delà, les appels reçoivent 429 (Too Many Requests). Ralentissez et réessayez.
• Plafond mensuel — une fois le coût de dépense cumulé atteint, les appels reçoivent 402 (Payment Required) jusqu’au reset (début du mois, UTC) ou jusqu’au relèvement du plafond par un administrateur.

Le détail complet

Liste des endpoints, threads avec état, corps de requête (message, messages, model), format exact du flux SSE, tableau des codes d’erreur et exemples complets (curl et fetch navigateur) : tout est dans la Référence API — Agents-as-API. La même documentation est aussi accessible en ligne depuis /agent-ai/api → onglet Setup complet → carte « Documentation ».

---

5. Gérer les clés API

Les canaux « widget avec clé » et « API » s’appuient sur une clé API. On les crée et on les administre depuis la page Agents en API (/agent-ai/api) → onglet Setup complet → section Clés API.

Créer une clé

À l’émission, vous renseignez :

• Nom (obligatoire) — pour vous y retrouver (ex. « Site vitrine RH », « Backend commande »).
• Agents autorisés — cochez le ou les agents que la clé peut appeler. Si vous n’en cochez aucun, la clé autorise tous les agents approuvés de l’organisation ; pour un widget public, cochez un seul agent.
• Rate limit (req/min) — nombre maximal d’appels par minute (429 au-delà).
• Plafond mensuel — coût de dépense maximal par mois (402 une fois atteint, jusqu’au mois suivant).
• Domaines autorisés (CORS) — les origines qui peuvent appeler l’agent depuis un navigateur (ex. https://client.com). Laissez vide pour un usage serveur-à-serveur uniquement.

Une clé est rattachée à un utilisateur principal de l’organisation (par défaut, l’admin qui la crée) : tous les appels sont exécutés, audités et débités en son nom, et l’agent voit les documents accessibles à cet utilisateur.

Le secret ne s’affiche qu’une seule fois, dans une bannière juste après l’émission. Copiez-le immédiatement et rangez-le dans un gestionnaire de secrets. Abra n’en conserve qu’une empreinte : personne — pas même un administrateur — ne peut le réafficher ensuite. En cas de perte, faites une rotation (nouveau secret) plutôt que de chercher à récupérer l’ancien.

Gérer une clé existante

Chaque clé de la liste montre son préfixe, les agents autorisés, sa dernière utilisation et la consommation du mois. Vous pouvez :

• Modifier les agents autorisés, le rate-limit, le plafond et les domaines CORS à tout moment.
• Faire tourner la clé (rotation) — génère un nouveau secret et invalide immédiatement l’ancien. À faire si une clé a pu fuiter, ou périodiquement par hygiène.
• Révoquer la clé — la désactive sur-le-champ ; les appels suivants reçoivent 401. Irréversible : pour réactiver un usage, créez une nouvelle clé.
• Consulter l’activité (30 jours) — appels, tokens, coût et éventuels dépassements de rate-limit, avec les derniers événements horodatés.

Bonnes pratiques : une clé par usage (un site, une app, un client), plafond et rate-limit systématiques, domaines CORS restreints pour tout widget, et rotation régulière. Une clé compromise se révoque sans impacter les autres.

La console des clés API : une ligne par clé, avec sa consommation et ses actions de gestion.

Traçabilité — retrouver qui a discuté

Chaque conversation garde son origine : appelée via une clé API, via un lien / login SSO (utilisateur réel), ou depuis le chat interne. Vous les explorez dans l’onglet Conversations de la page Agents en API, sous forme d’explorateur maître-détail :

1. Choisissez une clé puis un agent.
2. La liste de gauche affiche les conversations correspondantes.
3. Cliquez-en une pour lire l’échange complet à droite.

Pour une conversation en login SSO, la trace remonte jusqu’à l’utilisateur réel. Pour une conversation anonyme via clé, elle est rattachée à la clé (et à son propriétaire) — d’où l’intérêt, à nouveau, d’une clé distincte par site pour ne pas mélanger les usages.

L’explorateur de conversations : filtrez par clé et par agent, puis lisez chaque échange intégralement.

---

6. Suivi & quotas

Au-delà du détail par conversation, l’onglet Dashboard de la page Agents en API donne la vue d’ensemble de la consommation, sur une fenêtre de 30 jours par défaut :

• Indicateurs clés — cinq compteurs : Appels API, Tokens, Coût, Clés actives et Agents exposés.
• Courbes — l’évolution des Appels API dans le temps, et un histogramme Conversations par agent qui distingue les échanges via clé API de ceux via login SSO.
• Traçabilité par agent — un tableau récapitulatif : par agent, le nombre de conversations, la ventilation clé / SSO et les tokens consommés.

Ces vues répondent aux questions courantes : quel agent est le plus sollicité ?, combien coûte l’API ce mois-ci ?, une clé est-elle proche de son plafond ?. Le plafond mensuel défini sur chaque clé (§5) est votre garde-fou de budget : une fois atteint, la clé cesse de répondre (402) jusqu’au reset mensuel, ce qui évite toute mauvaise surprise de facturation.

Combinez plafond mensuel (budget) et rate-limit (pics de charge) : le premier borne le coût total, le second protège l’instance des rafales.

---

Questions fréquentes

Puis-je limiter les domaines qui peuvent appeler mon agent ? Oui. Sur chaque clé, renseignez les Domaines autorisés (CORS) : seules ces origines pourront lire la réponse depuis un navigateur. Une clé sans domaine listé reste serveur-à-serveur — un navigateur ne peut pas l’utiliser. Abra ne renvoie jamais Access-Control-Allow-Origin: *.

Comment révoquer une clé compromise ? Ouvrez Agents en API → Setup complet → Clés API, repérez la clé, puis Révoquer (désactivation immédiate, les appels reçoivent 401) ou Rotation (nouveau secret, l’ancien cesse de fonctionner aussitôt). La révocation d’une clé n’affecte aucune autre clé.

L’utilisateur final doit-il se connecter ? Cela dépend du canal. Avec le widget à clé, non : le chat est anonyme. Avec le widget SSO ou le lien de partage, oui : l’utilisateur se connecte, et la conversation est nominative. L’API n’implique pas de connexion utilisateur — c’est la clé qui authentifie l’appel.

Combien ça coûte, et comment plafonner la dépense ? Chaque clé porte un plafond mensuel de dépense. Une fois atteint, les appels sont refusés (402) jusqu’au début du mois suivant (UTC). Vous suivez le coût cumulé dans le Dashboard et dans l’activité de chaque clé. Ajoutez un rate-limit par minute pour lisser les pics.

Puis-je restreindre une clé à un seul agent ? Oui, et c’est recommandé pour tout usage public : à la création, cochez uniquement l’agent concerné dans Agents autorisés. Une clé sans agent coché autorise tous les agents approuvés de l’organisation — à éviter pour un widget exposé.

La clé est-elle visible dans mon widget ? Dans le widget à clé, oui : le secret figure dans le code source de la page. C’est pourquoi il faut une clé dédiée, mono-agent, plafonnée et restreinte par domaine. Si vous ne voulez exposer aucune clé, utilisez le widget avec login SSO ou le lien de partage.

Puis-je changer le modèle utilisé lors d’un appel API ? Oui, via le champ model de la requête — mais uniquement vers un modèle de l’allowlist de votre organisation (et de l’agent). Un modèle hors liste est refusé (403), sans repli silencieux. Voir la Référence API.

Que se passe-t-il si la fonctionnalité Agents en API est désactivée ? Toute la surface répond 404 et le widget reste inerte. Un administrateur d’instance doit l’activer pour que widget, lien SSO et API fonctionnent.

---

Voir aussi

• Créer un agent — préparer et approuver l’agent avant publication
• Référence API — Agents-as-API — endpoints, flux SSE, threads, CORS, codes d’erreur, exemples complets
• Guide admin — approbation des agents, gouvernance des modèles autorisés
• Concepts — le vocabulaire Abra (agent, RAG, connecteur, rôle, slug…)