Executes an Asterisk Gateway Interface-compliant program on the current channel. AGI programs allow external programs (written in almost any language) to control the telephony channel by playing audio, reading DTMF digits, and so on. Asterisk communicates with the AGI program on STDIN and STDOUT. The specified arguments are passed to the AGI program.

The program must be set as executable in the underlying filesystem. The program path is relative to the Asterisk AGI directory, which by default is /var/lib/asterisk/agi-bin/.

If you want to run an AGI when no channel exists (such as in an h extension), use the DeadAGI() application instead. You may want to use the FastAGI() application if you want to do AGI processing across the network.

If you want access to the inbound audio stream from within your AGI program, use EAGI() instead of AGI(). Inbound audio can then be read in on file descriptor 3.

If the channel hangs up prematurely, the process initiated by the AGI command will be sent a HUP signal to tell it that the channel has hung up. If your program does not catch this signal, it will be terminated. You can override this behavior by setting the channel variable AGISIGHUP to 0:

; call the demo AGI program
exten => 123,1,AGI(agi-test)
exten => 123,2,EAGI(eagi-test)

See Also

DeadAGI(), FastAGI(), Chapter 9, The Asterisk Gateway Interface (AGI)