Chapter 9. The Asterisk Gateway Interface (AGI)

Table of Contents

Fundamentals of AGI Communication
What Are STDIN, STDOUT, and STDERR?
The Standard Pattern of AGI Communication
Calling an AGI Script from the Dialplan
Writing AGI Scripts in Perl
The Perl AGI Library
Creating AGI Scripts in PHP
The PHP AGI Library
Writing AGI Scripts in Python
The Python AGI Library
Debugging in AGI
Debugging from the Operating System
Using Asterisk’s agi debug Command
Conclusion

Even he, to whom most things that most people would think were pretty smart were pretty dumb, thought it was pretty smart.

--Douglas Adams, The Salmon of Doubt

The Asterisk Gateway Interface, or AGI, provides a standard interface by which external programs may control the Asterisk dialplan. Usually, AGI scripts are used to do advanced logic, communicate with relational databases (such as PostgreSQL or MySQL), and access other external resources. Turning over control of the dialplan to an external AGI script enables Asterisk to easily perform tasks that would otherwise be difficult or impossible.

This chapter covers the fundamentals of AGI communication. It will not teach you how to be a programmer—rather, we’ll assume that you’re already a competent programmer, so that we can show you how to write AGI programs. If you don’t know how to do computer programming, this chapter probably isn’t for you, and you should skip ahead to the next chapter.

Over the course of this chapter, we’ll write a sample AGI program in each of the Perl, PHP, and Python programming languages. Note, however, that because Asterisk provides a standard interface for AGI scripts, these scripts can be written in almost any modern programming language. We’ve chosen to highlight Perl, PHP, and Python because they’re the languages most commonly used for AGI programming.