When calling an AGI from inside your dialplan, you can pass variables to your AGI via the AGI() application call. The AGI() application takes parameters in the following format (note the ';' is only necessary in AEL:

AGI(command|ARG1|ARG2|ARGn);

The additional arguments are useful when passing in non-channel variables such as those you set in your dialplan or via Read(). But, when Asterisk executes your AGI, it automatically passes in channel variables associated with the channel executing the AGI. Table 1 below lists variables common to all channels.

The Perl Asterisk::AGI module provides the ReadParse method to read the channel variables passed along by Asterisk into a hash. The following code shows the creation of the new AGI object and the method call to fill a new hash with the available channel variables.

#!/usr/bin/env perl

use Asterisk::AGI;
use strict;
use warnings;

my $agi       = new Asterisk::AGI;
my %chan_vars = $agi->ReadParse();

It's important to note that Asterisk::AGI strips the leading 'agi_' characters from all the variables that passed in. Thus, to get the Caller*ID number you need to reference $chan_vars{'callerid'}.

Table 1: Common Asterisk Channel Variables

For more information on AGI programming, see Nir Simionovich's book, Asterisk Gateway Interface 1.4 and 1.6 Programming.