Comment connecter un agent IA à une API avec Botpress
Hub Botpress, Execute Code, Open-Meteo, variables, tokens, headers, actions personnalisées et agent autonome : voici comment connecter concrètement un agent IA à une API.
Comment connecter un agent IA à une API avec Botpress
Un agent IA devient réellement utile lorsqu'il peut agir sur les outils de l'entreprise.
Google Calendar, CRM, ERP, Jira, météo, système de commande ou application interne : dans beaucoup de cas, cette connexion passe par une API.
Dans cette vidéo, je montre comment faire cette connexion dans Botpress avec un exemple concret basé sur l'API Open-Meteo.
La vidéo complète
Le tutoriel est disponible ici :
Commencer par vérifier le Hub Botpress
Avant de créer un appel API personnalisé, je commence par vérifier si une intégration existe déjà dans le Hub Botpress.
Si vous voulez connecter un outil courant, il est possible qu'un connecteur fournisse déjà les actions nécessaires.
Quand l'intégration existe, elle permet généralement d'éviter une partie du code et de récupérer directement des actions que l'agent peut utiliser.
Si aucun connecteur adapté n'existe, on peut alors passer à un appel API personnalisé.
Comprendre les éléments d'un appel API
Un appel API contient quelques éléments importants :
- une URL ;
- une méthode HTTP comme GET ou POST ;
- des paramètres ;
- parfois un body ;
- des headers ;
- éventuellement un token d'authentification.
Le but est de récupérer une réponse structurée, souvent en JSON, puis de l'utiliser dans le workflow ou dans un agent autonome.
Exemple avec Open-Meteo
Dans la vidéo, j'utilise Open-Meteo pour montrer le principe.
L'objectif est simple : permettre à l'agent de récupérer la température pour une latitude et une longitude données.
On part d'un endpoint API puis on passe les coordonnées dans l'URL.
Les valeurs ne doivent pas être écrites en dur.
Elles doivent venir des variables de l'agent.
Cela permet à l'utilisateur de demander une météo différente à chaque conversation.
Utiliser une carte Execute Code
Une manière simple de tester l'appel est d'utiliser une carte Execute Code dans Botpress.
Le code peut :
- construire l'URL ;
- exécuter la requête ;
- attendre la réponse ;
- convertir la réponse JSON ;
- extraire le champ utile ;
- stocker la valeur dans une variable.
Cette étape est pratique pour comprendre exactement ce que retourne l'API avant de transformer l'appel en outil réutilisable.
Rendre les paramètres dynamiques
Pour que l'agent puisse appeler l'API lui-même, les paramètres doivent être fournis dynamiquement.
Dans l'exemple météo, on peut utiliser :
- latitude ;
- longitude.
Pour d'autres APIs, ce pourrait être :
- email du client ;
- identifiant de commande ;
- numéro de ticket ;
- identifiant produit ;
- date ;
- nom d'entreprise.
L'agent extrait ou collecte ces informations puis les transmet à l'action.
Gérer les clés API avec les variables d'environnement
Toutes les APIs ne sont pas publiques.
Lorsqu'un token est nécessaire, il ne faut pas le copier directement dans le prompt ou dans un message.
Botpress permet d'utiliser des variables de configuration pour stocker ces secrets.
Cette pratique facilite aussi le remplacement d'une clé sans modifier toute la logique du workflow.
Ajouter un header Authorization
Beaucoup d'APIs utilisent un header du type :
Authorization: Bearer VOTRE_TOKEN
Le token vient alors de la variable de configuration.
Le principe est le même pour d'autres headers comme une clé API ou un identifiant de projet.
L'agent n'a pas besoin de connaître la valeur du secret.
Il utilise simplement l'action qui a été configurée.
Transformer l'appel en action personnalisée
Une fois l'appel testé, il devient beaucoup plus intéressant de le transformer en action réutilisable.
Dans Botpress, une action personnalisée peut avoir :
- un nom ;
- une description ;
- un schéma d'entrée ;
- un schéma de sortie ;
- du code.
Pour notre exemple, l'entrée peut contenir :
- latitude ;
- longitude.
La sortie peut contenir :
- température.
L'agent reçoit alors un outil clair qu'il peut appeler lorsqu'il en a besoin.
Pourquoi le schéma d'entrée et de sortie est important
Le schéma décrit ce que l'agent doit envoyer et ce qu'il va récupérer.
Si l'action demande une latitude et une longitude, le modèle sait qu'il doit produire ces deux valeurs.
Si l'action retourne une température, il sait comment utiliser le résultat.
Cette structure rend l'outil beaucoup plus compréhensible pour l'agent.
Donner l'action à un nœud autonome
Une fois l'action créée, elle peut être ajoutée aux outils d'un nœud autonome.
L'agent peut alors décider de l'utiliser en fonction de la question.
Par exemple, si l'utilisateur demande :
Quelle température fait-il à Nantes ?
l'agent doit d'abord obtenir les coordonnées nécessaires puis appeler l'action météo.
Il récupère la valeur retournée et peut ensuite préparer sa réponse.
Décrire clairement quand utiliser l'outil
Le nom de l'action et sa description comptent beaucoup.
Un outil appelé apiCall est difficile à interpréter.
Un outil appelé getWeather avec une description claire indique immédiatement son rôle.
Pour un projet métier, j'utilise le même principe :
- getOrderStatus ;
- createSupportTicket ;
- findCustomer ;
- updateLead.
Chaque outil doit avoir une responsabilité précise.
Exemple avec un outil d'entreprise
Prenons un agent de support e-commerce.
Le client écrit :
Où est ma commande 4582 ?
L'agent peut appeler une action de recherche de commande avec l'identifiant 4582.
L'action contacte votre API interne ou Shopify.
Elle retourne par exemple :
- statut ;
- transporteur ;
- numéro de suivi ;
- date estimée de livraison.
L'agent transforme ensuite ces données en réponse compréhensible pour le client.
Gérer les erreurs d'API
Une API peut retourner une erreur.
Il faut prévoir au minimum :
- timeout ;
- erreur d'authentification ;
- identifiant invalide ;
- donnée absente ;
- réponse inattendue ;
- service indisponible.
L'action doit retourner une information exploitable par l'agent.
Selon le cas, l'agent peut demander une nouvelle donnée, réessayer ou transférer la conversation.
Limiter les permissions
Une action donnée à un agent doit avoir uniquement les permissions nécessaires.
Un outil qui consulte une commande n'a pas besoin de pouvoir la supprimer.
Un outil qui crée un ticket n'a pas besoin d'un accès administrateur complet au CRM.
Cette limitation réduit les risques en production.
Action personnalisée ou intégration du Hub
J'utilise une intégration existante lorsque le connecteur couvre bien le besoin.
Je crée une action personnalisée lorsque :
- l'intégration n'existe pas ;
- l'API est interne ;
- les paramètres doivent être contrôlés précisément ;
- il faut transformer la réponse ;
- une logique métier spécifique est nécessaire.
Les deux approches peuvent parfaitement cohabiter dans le même agent.
Ce que cette connexion change pour un agent IA
Sans outils, un agent peut surtout répondre avec du texte.
Avec des APIs, il peut récupérer des données et déclencher des actions.
Il peut alors :
- consulter une commande ;
- créer un rendez-vous ;
- mettre à jour un CRM ;
- ouvrir un ticket ;
- récupérer des données métier ;
- envoyer une information à un autre système.
C'est cette couche d'intégration qui transforme une interface conversationnelle en véritable agent.
Pour approfondir la conception globale, vous pouvez aussi lire ma méthodologie pour créer un agent IA performant.
Si vous voulez connecter un agent à vos outils internes ou à une API métier, vous pouvez me contacter.
Vous voulez appliquer ces idées ?
Réservez un diagnostic pour identifier les premiers cas d'usage utiles dans votre activité.