Asterisk AGI (Asterisk Gateway Interface) est la plus ancienne interface de programmation d’Asterisk, et l’une des plus pratiques pour intégrer une vraie logique métier dans un système téléphonique. Lorsqu’un appel atteint l’application AGI() du dialplan, Asterisk confie le contrôle à un programme externe qui peut interroger une base de données, appeler l’API d’un CRM, diffuser des messages, recueillir des touches DTMF et décider de la suite de l’appel. Voxivra conçoit des applications Asterisk AGI depuis les débuts de la plateforme, et nous l’utilisons encore en production chaque fois qu’elle est le bon outil.
Le fonctionnement de l’AGI
L’AGI est un protocole texte, ligne par ligne. Quand un canal entre dans AGI(), Asterisk envoie d’abord un bloc de variables agi_* (numéro appelant, numéro composé, nom du canal, contexte, identifiant unique, etc.), suivi d’une ligne vide. Le programme envoie ensuite des commandes comme ANSWER, STREAM FILE, GET DATA, SET VARIABLE ou EXEC, et Asterisk répond à chacune par une ligne de résultat (200 result=...).
Deux caractéristiques orientent la conception :
- L’AGI est synchrone. Chaque commande bloque jusqu’à la réponse d’Asterisk, et le script « possède » le canal pendant son exécution. La logique est lisible, mais un appel d’API lent se traduit par un silence pour l’appelant.
- Le dialplan garde la main. À la fin du script, l’appel reprend à la priorité suivante. La variable
AGISTATUSindique si le script a réussi, échoué ou constaté un raccrochage.
AGI, FastAGI et EAGI
| Variante | Transport | Usage type |
|---|---|---|
| AGI | Nouveau processus local par appel (stdin/stdout) | Petits scripts, faible volume |
| FastAGI | TCP vers un service permanent (agi://hôte:4573) |
Production, pools de connexions, serveurs applicatifs séparés |
| EAGI | Comme l’AGI, avec l’audio entrant sur le descripteur 3 | Anciens essais de reconnaissance vocale ; ARI est souvent préférable aujourd’hui |
Au-delà de quelques appels simultanés, nous utilisons FastAGI. Lancer un interpréteur à chaque appel consomme processeur et mémoire sur le serveur Asterisk et empêche de réutiliser les connexions aux bases de données. Un service FastAGI tourne de façon autonome, peut être placé derrière un répartiteur de charge et mis à jour sans toucher à Asterisk.
Un schéma FastAGI typique
Voici un dialplan simplifié qui confie un appel entrant à un service de routage FastAGI, puis exploite les variables renvoyées :
[inbound]
exten => _X.,1,Answer()
same => n,Set(TIMEOUT(absolute)=3600)
same => n,AGI(agi://10.0.10.20:4573/route?lang=fr)
same => n,GotoIf($["${AGISTATUS}" != "SUCCESS"]?fallback,s,1)
same => n,Goto(${ROUTE_CONTEXT},${ROUTE_EXTEN},1)
[fallback]
exten => s,1,Playback(please-hold)
same => n,Queue(general)Le service FastAGI recherche l’appelant dans le CRM, vérifie les heures d’ouverture et les dossiers en cours, puis définit ROUTE_CONTEXT et ROUTE_EXTEN avec SET VARIABLE. Si le service est injoignable, le dialplan bascule vers une file d’attente générale au lieu de couper l’appel. Dans nos projets, cette branche de secours n’est jamais facultative : la téléphonie doit continuer de fonctionner quand un serveur applicatif tombe.
Ce que nous réalisons avec Asterisk AGI
- Routage basé sur les données : identification de l’appelant par numéro ou numéro de compte, puis acheminement selon le niveau de service, la langue, le dossier ouvert ou l’agent attitré.
- Menus SVI dynamiques (serveur vocal interactif) générés depuis une base de données plutôt que codés en dur, pour que les équipes métier modifient les options sans toucher au dialplan. Voir notre service de SVI sur mesure.
- Libre-service : consultation de solde ou de commande, vérification de NIP, confirmation de rendez-vous, le tout en DTMF.
- Intégration CRM et ERP : création de fiches d’appel, remontée de la fiche client à l’agent, journalisation des résultats, comme décrit sur notre page intégration CRM et ERP.
- Modernisation : réécriture d’anciens scripts lancés à chaque appel en services FastAGI testés et maintenables.
Les pratiques qui rendent l’AGI fiable
L’AGI est facile à écrire et facile à mal écrire. Les problèmes que nous corrigeons en audit sont prévisibles ; nous les évitons dès la conception.
Des délais d’expiration partout
Chaque appel externe dans un gestionnaire AGI a un délai strict, bien inférieur à ce qu’un appelant tolère en silence. Si le CRM ne répond pas à temps, le script renvoie une valeur par défaut sûre et l’appel continue. Pour les requêtes potentiellement lentes, nous diffusons un court message ou une musique d’attente, ou nous préchargeons les données plus tôt dans le parcours.
La gestion du raccrochage
Les appelants raccrochent en plein script. Un gestionnaire robuste détecte le raccrochage, cesse d’envoyer des commandes au canal et termine malgré tout ses traitements, comme l’écriture de la fiche d’appel. Le travail post-appel qui n’a pas besoin du canal est déplacé dans l’extension h, un gestionnaire de raccrochage ou une file de messages.
Des services sans état
Pour exécuter plusieurs instances d’un serveur FastAGI, celui-ci ne doit pas conserver l’état des appels en mémoire. Nous gardons l’état dans les variables du dialplan, une base de données ou un cache, ce qui simplifie la mise à l’échelle horizontale et les mises à jour progressives.
L’observabilité
Chaque requête AGI journalise l’identifiant unique Asterisk (agi_uniqueid), ce qui permet de suivre un appel du dialplan jusqu’au CRM. Nous ajoutons des métriques de latence et de taux d’erreur par gestionnaire : « le SVI est lent » devient un diagnostic précis.
La sécurité
FastAGI n’offre ni authentification ni chiffrement. Le service doit écouter uniquement sur un réseau privé ou être restreint par pare-feu aux serveurs Asterisk. Nous n’exposons jamais le port 4573 à Internet. Plus de détails dans notre expertise en sécurité VoIP.
Quand Voxivra recommande l’AGI, et quand l’éviter
Nous recommandons l’AGI, et plus précisément FastAGI, lorsque :
- vous avez déjà un dialplan fonctionnel et souhaitez y ajouter des décisions ou des recherches sans réécrire le parcours d’appel ;
- l’interaction repose surtout sur des messages et du DTMF, avec une logique linéaire, étape par étape ;
- votre équipe maîtrise le dialplan et veut qu’il reste la référence.
Nous privilégions plutôt Asterisk ARI lorsque l’application doit piloter plusieurs canaux et ponts à la fois, réagir à des événements asynchrones ou diffuser l’audio vers la reconnaissance vocale d’un voicebot conversationnel. Le modèle bloquant de l’AGI n’est pas conçu pour l’audio bidirectionnel en temps réel. Beaucoup de nos déploiements combinent les deux : AGI pour le routage et le libre-service simple, ARI pour les parties pilotées par l’IA. Nous comparons les deux approches dans l’article Asterisk : AGI ou ARI ?.
Notre démarche sur un projet AGI
- Revue de votre dialplan, de vos scripts et de vos volumes d’appels.
- Conception des gestionnaires, des sources de données, des délais et des chemins de secours.
- Développement du service FastAGI, avec des tests automatisés qui simulent le protocole AGI.
- Tests de charge avec des générateurs de trafic SIP avant la mise en service.
- Déploiement et support, avec supervision et documentation pour votre équipe.
Si votre code AGI est devenu difficile à maintenir, ou si vous avez un nouveau parcours d’appel à construire, présentez-nous votre environnement : nous vous dirons franchement si l’AGI est la bonne option.