Pourquoi connecter votre app à une API d’agent IA

Qu’est-ce qu’une API d’agent IA ?

Une API d’agent IA permet à votre propre logiciel d’envoyer un message à un agent que vous avez déjà créé et de récupérer sa réponse. L’agent garde ses instructions, ses connaissances, son modèle, ses outils et ses règles de sécurité. Votre application n’envoie que la question.

C’est la différence avec une API de modèle brute. Une API de modèle vous donne la génération de texte et vous laisse tout le reste : prompts, recherche dans les documents, mémoire, limites de débit, facturation. L’API REST d’IMFA vous donne un agent géré qui a déjà tout cela, derrière une seule clé propre à l’agent.

Vous créez l’agent avec le créateur de chatbot IA. L’API est un endroit de plus où il peut répondre, à côté de votre site, WhatsApp, Instagram, Facebook, Telegram, Discord et la ligne vocale.

Quand connecter votre agent par une API ?

Passez par l’API quand la conversation a lieu dans un outil qui vous appartient :

• Votre application ou votre portail client a besoin d’un assistant qui connaît vos conditions, sans second chatbot à entretenir.
• Votre backend doit répondre à des questions venant d’un autre système, comme des pages de commande, un outil de réservation ou un tableau de bord interne.
• Vous voulez vos prospects dans votre CRM. L’API renvoie les prospects captés par l’agent sur tous les canaux, pour les synchroniser à intervalles réguliers.
• Vous avez besoin de l’historique des conversations pour vos rapports ou le contrôle qualité.

Si vous voulez seulement une bulle de chat sur un site, la ligne d’intégration est plus simple. L’API sert quand l’interface, c’est votre produit, pas le widget.

Comment fonctionne l’API d’agent IMFA

L’URL de base est https://site.imfa.app/v1. Chaque appel exige la clé de l’agent et doit venir d’un code serveur de confiance, jamais d’un navigateur ni d’une application mobile.

1. Publiez l’agent. Réglez ses instructions, ses connaissances, son modèle et ses outils dans IMFA, testez de vraies questions, puis publiez. L’API sert la version publiée.
2. Générez la clé. Ouvrez la vue API de l’agent ou l’écran API Keys et générez une clé. Elle n’est affichée qu’une fois et n’est stockée que sous forme de hash. Gardez-la dans une variable d’environnement serveur comme IMFA_API_KEY.
3. Envoyez une requête de chat. POST /v1/agents/{slug}/chat avec Authorization: Bearer <key>, une Idempotency-Key unique (8 à 128 caractères) et un corps JSON contenant message et un sessionId facultatif. La réponse revient avec un sessionId et usage.credits.
4. Poursuivez la conversation. Omettez sessionId au premier échange, puis renvoyez celui que vous avez reçu. L’agent se souvient du contexte.
5. Lisez ce qui s’est passé. GET /v1/agents/{slug}/sessions liste les conversations, GET /v1/agents/{slug}/sessions/{sessionId}/messages en lit une, et GET /v1/agents/{slug}/leads renvoie les prospects captés. Les listes renvoient 20 éléments par défaut, jusqu’à 100, avec un curseur. GET /v1/agents confirme quel agent la clé sert.

Les limites sont explicites : seuls les 4 000 premiers caractères d’un message sont utilisés, les corps sont plafonnés à 64 000 octets, et les erreurs sont typées (validation, authentification, crédits, limite de débit, serveur). Un 429 arrive avec Retry-After ; un 402 signifie que les crédits du propriétaire sont épuisés.

Pourquoi utiliser l’API d’agent plutôt que tout construire vous-même

Vous évitez des mois de plomberie. Recherche dans les documents, sessions, limites de débit, nouvelles tentatives, décompte des crédits et règles contre l’injection de prompts tournent déjà. Votre équipe écrit un seul appel HTTP.

Un agent, un comportement. La réponse affichée dans votre application est la même que sur votre site et sur WhatsApp, parce que c’est le même agent. Mettez-le à jour une fois dans IMFA et toutes les surfaces suivent.

Les nouvelles tentatives sont sans risque. Grâce à la clé d’idempotence, une nouvelle tentative réseau renvoie la réponse d’origine au lieu de facturer un deuxième échange.

Les prospects ne restent plus cloisonnés. Récupérez tous les prospects captés via un seul endpoint, quel que soit leur canal d’origine.

Le sur-mesure complet reste possible. Si vous devez maîtriser chaque couche, une API de modèle brute vous donne ce contrôle, au prix de tout construire et faire tourner vous-même. Des agents de code comme Codex et Claude Code peuvent aussi gérer vos agents IMFA via MCP, pendant que votre serveur utilise la clé REST pour servir vos clients.

Questions fréquentes sur l’API d’agent IA

Puis-je appeler l’API d’agent IA directement depuis un navigateur ?

Non. La clé dépense les crédits du propriétaire et doit rester sur un serveur de confiance. L’API n’ouvre pas d’accès large aux navigateurs. Faites appeler par votre navigateur votre propre endpoint protégé, qui appelle ensuite IMFA.

Comment authentifier une requête à l’API d’agent IMFA ?

Générez une clé propre à l’agent dans la vue API de l’agent ou l’écran API Keys, puis envoyez Authorization: Bearer YOUR_API_KEY depuis du code serveur. Un token MCP est un autre identifiant et ne fonctionne pas ici.

Comment poursuivre la même conversation par l’API ?

Omettez sessionId à la première requête de chat, conservez le sessionId renvoyé par l’API et envoyez-le avec le message suivant. Les identifiants de session des conversations du site ou des canaux sont en lecture seule et ne peuvent pas poursuivre une conversation API.

Pourquoi une Idempotency-Key est-elle obligatoire pour le chat ?

Elle rend les nouvelles tentatives sûres. Une nouvelle tentative identique avec la même clé renvoie le même résultat au lieu de créer un nouvel échange. Utilisez une nouvelle clé pour chaque nouveau message.

L’API d’agent utilise-t-elle mes connaissances et mes outils ?

Oui. Elle appelle l’agent publié avec ses instructions, son modèle, ses connaissances, ses compétences, ses outils et ses règles de sécurité. Les réponses dépendent toujours de la configuration publiée, de vos crédits et des limites actuelles du service.