AGI (Asterisk Gateway Interface)
Asterisk's protocol for handing call control to an external script - the backbone of VICIdial's dial plan.
AGI stands for Asterisk Gateway Interface: the protocol Asterisk uses to hand control of a call to an external program mid-call. The script reads commands on standard input, writes responses back, and can play audio, collect digits, set variables and change where the call goes next.
Why it matters in VICIdial
VICIdial is, to a first approximation, a set of AGI scripts and cron daemons wrapped around Asterisk. The dial plan does very little by itself; at the decision points it calls out to Perl scripts in /usr/share/astguiclient/ that own the actual logic. VD_amd.agi is a good example - the dial plan hands an answered call to it, and it decides human or machine and sets the call's onward path.
FastAGI is the network variant, invoked as agi://host:port/script. Instead of forking a process per call, Asterisk opens a socket to a long-running listener. On a dialer placing thousands of calls an hour that difference is not academic - process-per-call AGI at that volume will show up as load average long before anything else does.
Writing your own
Custom AGI is the supported way to extend VICIdial without patching it:
- Look up an account in your own database and set variables the agent screen can read
- Branch a call menu on data rather than on a keypress
- Apply routing logic the built-in configuration cannot express
- Write to an external system at a specific point in the call
Scripts go in /usr/share/astguiclient/, are referenced from your own dial-plan context, and must be executable by the Asterisk user.
Two things to get right
AGI runs inside the call. A script that blocks on a slow HTTP request holds the caller in silence for exactly as long as it takes, so anything that reaches off-box needs a short timeout and a defined fallback.
And keep your work in your own context. VICIdial regenerates its dial-plan files, so edits made inside the generated blocks are overwritten on the next rebuild.