Connectez un agent IA géré à votre application

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

Une API d'agent IA permet à une application de confiance de communiquer avec un agent qui possède déjà des instructions, des connaissances, un modèle, des outils et un comportement conversationnel. L'API REST IMFA peut lister l'agent disponible, envoyer un message, poursuivre une session API, lire les messages persistés et récupérer les prospects.

Il s'agit de l'interface d'un agent géré et non d'un accès direct à un modèle. Vous configurez et publiez l'agent dans IMFA, puis votre serveur l'appelle avec une clé limitée à cet agent. Les mêmes connaissances RAG et règles approuvées peuvent servir votre application, le web, WhatsApp, Telegram, Discord et la voix éligible.

Un contrat d'agent pour les intégrations serveur de confiance

L'API expose une surface REST étroite et documentée autour d'un agent publié, tandis qu'IMFA gère connaissances, comportement, modèles, sessions, crédits et protections.

Authentification limitée à l'agent

Générez manuellement une clé REST dans la vue API de l'agent ou l'écran des clés API. Envoyez Authorization: Bearer YOUR_API_KEY. La clé n'est affichée qu'une fois, reste stockée sous forme de hash et diffère du jeton MCP du compte.

Chat idempotent

POST /v1/agents/{slug}/chat exige un en-tête Idempotency-Key de 8 à 128 caractères autorisés. Créez une nouvelle valeur pour chaque tour distinct et réutilisez-la seulement pour réessayer exactement la même requête.

Contexte API réutilisable

Omettez sessionId pour démarrer une conversation API, puis conservez la valeur renvoyée avec la réponse et réutilisez-la. Les identifiants des sessions web, builder et canaux visibles dans l'historique sont en lecture seule.

Sessions, messages et prospects

Listez les sessions persistées, lisez les messages d'une session et récupérez les prospects. Les routes GET paginées renvoient 20 éléments par défaut et acceptent une limite de 1 à 100 ainsi qu'un curseur.

Limites et statuts explicites

Le chat exige un message, utilise ses 4 000 premiers caractères, accepte un sessionId de 128 caractères maximum et limite le corps à 64 000 octets. Les statuts distinguent validation, clé, crédits, disponibilité, pause, taille, débit et erreur serveur.

Le même système d'agent géré

Les réponses utilisent les instructions, le modèle, les connaissances RAG, les compétences, les outils et les protections de l'agent publié. Les requêtes consomment les crédits du propriétaire et peuvent renvoyer usage.credits.

Comment appeler un agent IMFA depuis votre serveur

Publiez d'abord l'agent, protégez sa clé dans une variable serveur et concevez les nouvelles tentatives pour préserver l'idempotence et la continuité.

1. Créez et publiez l'agent géré

   Définissez instructions, connaissances RAG, modèle, compétences, outils et protections dans IMFA. Testez les questions réalistes et publiez explicitement avant d'utiliser l'API REST.

2. Générez et protégez la clé limitée

   Ouvrez la vue API ou https://www.imfa.app/app/api-keys, générez la clé manuellement et gardez-la dans une variable serveur telle que IMFA_API_KEY. Ne la placez jamais dans le navigateur, une application mobile, un dépôt public, les journaux ou les messages.

3. Envoyez la requête serveur idempotente

   Appelez fetch('https://site.imfa.app/v1/agents/{slug}/chat') en POST avec Authorization: Bearer plus la clé serveur, Content-Type: application/json, un Idempotency-Key unique et un JSON avec message et sessionId facultatif. Conservez reply, sessionId et usage.credits.

API IMFA, API de modèle brute ou développement personnalisé

Le bon choix dépend de la couche que votre équipe veut posséder. IMFA expose un agent client déjà géré, tandis qu'une API de modèle fournit des primitives de génération.

Une API de modèle offre un contrôle maximal

Choisissez un fournisseur direct si vous voulez gérer prompts, ingestion et recherche RAG, sessions, politiques d'outils, authentification, limites, canaux, observabilité, facturation, déploiement, sécurité et maintenance.

Les agents de code construisent le logiciel

Codex et Claude Code peuvent créer vos applications et intégrations. Ils peuvent aussi gérer IMFA via MCP, alors que votre serveur de production utilise la clé REST distincte et limitée à l'agent.

IMFA gère le cycle de vie de l'agent

Choisissez IMFA si votre application doit appeler un agent dont les connaissances, règles, canaux, sessions, prospects, modèles, protections, publication et usage sont réunis dans une interface.

Cinq endpoints REST pour un agent publié

L'URL de base est https://site.imfa.app/v1. Chaque requête exige la clé Bearer limitée à l'agent et le chat doit venir d'un serveur de confiance.

Lister l'agent disponible

GET /v1/agents renvoie l'agent accessible à la clé afin que le serveur confirme sa cible publiée.

Discuter avec l'agent

POST /v1/agents/{slug}/chat envoie un message et renvoie reply, un sessionId réutilisable, usage.credits et l'état de répétition si nécessaire.

Lire les conversations

GET /v1/agents/{slug}/sessions liste les conversations et GET /v1/agents/{slug}/sessions/{sessionId}/messages lit les messages d'une session.

Récupérer les prospects

GET /v1/agents/{slug}/leads renvoie les prospects capturés avec le même contrat de pagination par curseur.

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

Réponses précises sur l'authentification, l'usage serveur, l'idempotence, les sessions, le RAG, les crédits et les limites de débit.

Puis-je appeler l'API d'agent directement depuis le navigateur ?

Non. La clé consomme les crédits du propriétaire et doit rester sur un serveur de confiance. L'API n'est pas destinée au navigateur et n'ouvre pas un CORS public large. Le navigateur doit appeler votre propre endpoint serveur protégé.

Comment authentifier une requête API IMFA ?

Générez manuellement une clé REST limitée à l'agent dans sa vue API ou l'écran des clés, puis envoyez Authorization: Bearer YOUR_API_KEY depuis le serveur. Un jeton MCP est un identifiant différent et ne remplace pas cette clé.

Comment poursuivre la même conversation API ?

Omettez sessionId lors du premier appel. Conservez la valeur renvoyée et ajoutez-la au corps suivant. Seul un identifiant renvoyé par le chat API continue ce contexte; les sessions web et canaux sont en lecture seule.

Pourquoi Idempotency-Key est-il obligatoire ?

Il permet de répéter exactement une requête sans transformer un nouvel essai réseau en nouveau tour. Utilisez une valeur de 8 à 128 caractères différente par message et réutilisez-la seulement pour la même requête.

L'API utilise-t-elle mon RAG et mes outils ?

Oui. Elle appelle l'agent publié avec ses instructions, son modèle, ses connaissances RAG, ses compétences, ses outils et ses protections. Le résultat dépend toujours de la configuration publiée, des crédits et des limites du service.

Que faire en cas de limite de débit ou de crédits épuisés ?

L'API peut renvoyer 402 si les crédits sont épuisés ou 429 si le débit est limité. Pour 429, attendez la durée Retry-After. Gérez tous les statuts et sachez qu'une erreur interne peut encore fournir un sessionId.