What is an AGI File?

An AGI file is a script used with Asterisk, an open-source telephony platform, through the Asterisk Gateway Interface (AGI). These files are plain text scripts that allow external programs to interact with and control the Asterisk dialplan-the logic Asterisk uses to handle phone calls.

AGI scripts are commonly used to automate telephony processes, such as accessing databases, integrating with CRMs, logging call activity, or building Interactive Voice Response (IVR) systems.

By using AGI scripts, Asterisk can hand off control of a call to an external program that performs more complex tasks than the dialplan alone can handle.

AGI File Format and Structure

AGI files are plain text scripts written in languages like:

  • Python
  • Perl
  • PHP
  • C
  • Bash (Bourne Shell)
  • Pascal

These files typically begin with a shebang (#!) that tells the system how to run the file, for example:

#!/usr/bin/env python3

They are saved with the .agi extension, for example: googletts.agi - a popular AGI script that uses Google Text-to-Speech.

Where Are AGI Files Used?

AGI files are placed in the Asterisk AGI directory, usually:

/var/lib/asterisk/agi-bin/

They are invoked in the dialplan (in extensions.conf) like this:

exten => 123,1,AGI(googletts.agi,"Hello, this is a test.")

Standard Pattern of AGI Communication

When Asterisk executes an AGI script, it sends environment variables to the script over standard input. These variables describe the context of the call:

agi_request: test.py
agi_channel: Zap/1-1
agi_language: en
agi_callerid:
agi_context: default
agi_extension: 123
agi_priority: 2

A blank line marks the end of this header. After that, the script can begin sending and receiving instructions via standard input/output.

Programming language for AGI Script Files

AGI scripts can typically be written in Perl, PHP, C, Pascal, or Bourne Shell.

Sample AGI Script in Python

Here’s a basic example of an AGI script written in Python:

#!/usr/bin/env python3
import sys

# Read AGI environment variables
def read_agi_env():
    env = {}
    while True:
        line = sys.stdin.readline().strip()
        if line == "":
            break
        key, value = line.split(":", 1)
        env[key.strip()] = value.strip()
    return env

# Respond with a message
def main():
    agi_env = read_agi_env()
    sys.stdout.write('VERBOSE "Hello from AGI script!" 1\n')
    sys.stdout.flush()

if __name__ == "__main__":
    main()

This script simply reads the AGI environment and prints a message back to the Asterisk CLI.

Common Use Cases for AGI Scripts

  • Database Access (e.g., MySQL, PostgreSQL)
  • Text-to-Speech using tools like googletts.agi
  • Dynamic IVR Menus
  • Call Logging
  • Caller Authentication
  • CRM or Helpdesk Integration

What is AGI in Asterisk?

AGI stands for Asterisk Gateway Interface. It allows external scripts to control how Asterisk handles a call.

What is an AGI file?

An AGI file is a script that interfaces with Asterisk to perform programmable actions during a call.

What language can I use for AGI scripts?

Common options include Python, Perl, PHP, and Bash. Python is often favored for clarity and built-in libraries.

What is googletts.agi?

googletts.agi is a popular script that uses Google Text-to-Speech to read text aloud during a call.

What is AGI script format?

It is a plain text file that responds to commands from Asterisk via standard input/output. It must be executable and placed in the AGI directory.

What is a .g file?

Although not directly related, some users confuse .g files with .agi files. .g may refer to grammar files used in speech recognition or other domains, not Asterisk.

References