FastAGI

Implements the Asterisk Gateway Interface (AGI) over TCP sockets. This can help alleviate CPU load on your telephony server by relocating resource hungry scripts to another networked server. In order to instruct Asterisk to attempt a network connection, you must supply the hostname or IP address of the server where your FastAGI service is hosted and preface it with agi://:

  exten => 5551212,1,AGI(agi://192.168.0.2)

Note that the agi:// syntax can be used with both the AGI and DeadAGI dialplan commands, while EAGI is currently not supported. The previous example instructs Asterisk to make a network connection to a host running on a local network server when the 5551212 extension is matched. By default, Asterisk attempts to connect to the specified server over port 4573. The port can also be specified should you choose to host the AGI service on another port:

  exten => 5551212,1,AGI(agi://192.168.0.2:8675)

A request may also be specified in the FastAGI call, so that you can host multiple AGIs in a single network location. This request allows the FastAGI service to differentiate between different locations in the dialplan. For example:

  exten => 5551212,1,AGI(agi://192.168.0.2/GetCallerRecord)

and:

  exten => 5551212,1,AGI(agi://192.168.0.2/CallerWantsCustomerService)

The request portion of these calls will be received by the FastAGI service as the agi_network_script AGI variable. Asterisk will also include the agi_network AGI variable. For example, the FastAGI in the previous example would receive something like this when called by Asterisk:

  agi_network: yes
  agi_network_script: /CallerWantsCustomerService

Passing Arguments to FastAGI

Asterisk 1.6.x

In Asterisk 1.6.x, arguments passed to the AGI command are passed through to the FastAGI as AGI variables. For example, calling a FastAGI with the following:

  exten => 5551212,1,AGI(agi://192.168.0.2/CallerWantsCustomerService,${EXTEN},${UNIQUEID},${CALLERID(name)})

will result in the following AGI variables being passed to the FastAGI service:

  agi_network: yes
  agi_network_script: /CallerWantsCustomerService
  agi_arg_1: 5551212
  agi_arg_2: 1171048538.5875
  agi_arg_3: Mark Spencer

The method described below for both Asterisk 1.2 and 1.4 is also still supported.

Asterisk 1.2 & 1.4

With Asterisk 1.2 through 1.4, when using standard AGI, you can pass variables on the command line to your local scripts. This is not possible with FastAGI, however, but can be simulated using agi_network_script and a query syntax similar to that used by HTTP. For example:

exten => 5551212,1,AGI(agi://192.168.0.2/GetCallerRecord?extension=${EXTEN})

It is the responsibility of your FastAGI framework to parse this information out of the agi_network_script variable. Some FastAGI implementations already do this for you, so be sure to check the documentation for your particular framework.

Error Handling

Asterisk 1.4 & 1.6.x

As of Asterisk 1.4 a new channel variable, AGISTATUS, is set to SUCCESS upon successful execution of an AGI. If there was a problem connecting to the FastAGI service, the channel variable is set to FAILURE, allowing the dialplan to perform alternate steps as not to interrupt the call flow. If the calling channel hangs up during execution of the AGI, AGISTATUS is set to HANGUP.

Asterisk 1.2

Under Asterisk 1.2, if a request to a FastAGI service failed for any reason, the channel is hung up. There is a patch that addresses this problem by having Asterisk look for an n+101 priority in the event of a FastAGI failure, but this code is not included in Asterisk by default.

Availability

The FastAGI feature was introduced with Asterisk 1.0.

Examples

Included in the Asterisk distribution, "fastagi-test" is a sample FastAGI service implemented in Perl. This sample can be found under the "agi" folder in your Asterisk source directory. You can use this service as is, or simply use it as a template for your own implementation.

There are some other examples here:

Performance Improvements over AGI

Using Asterisk's standard AGI mechanism, everytime the AGI command is encountered in the dialplan Asterisk has to execute a command line process, which is a relatively expensive operation. Opening a network connection on the other hand, while still requiring overhead, is significantly faster than executing a local process. Another important factor to consider when deciding between local AGIs and networked FastAGIs is the fact that a networked FastAGI service is running constantly, thus eliminating the per-request overhead of building up and tearing down a new process each time. You will even see some improvement when converting your existing AGIs into FastAGIs and running them on the same server as your phone system, though this is not always feasible or recommended.

FastAGI Servers

.NET

Asterisk.NET - A .NET implementation of FastAGI. Also includes Manager API functions.
NAsterisk - A .NET implementation of FastAGI. Allows you to create a listening service as well as write scripts using any .NET language.

ActiveX

AstOCX - An easy to use Windows ActiveX Control that lets you do your call control on the Windows platform.

Erlang

ErlAst - A multi-threaded FastAGI server written in Erlang which lets you do your call control in Erlang.

Haskell

Haskell AGI Support for basic AGI and FastAGI.

Java

Asterisk-java - Includes a FastAGI server and allows you to write your AGI scripts in Java. It also now supports the Asterisk Manager API.
Jast Agi
OrderlyCalls (successor to JAGIServer) offers full support for FastAGI and Manager in an easy-to-use Named Service environment. Includes Web Deployer for developing integrated VOIP-HTML applications.

Object Pascal

AsterPas Multi-Threaded, FastAGI Script Server supports full AGI commands, many traditional object pascal constructs such as TStringList as well as built in classes for database access (MySQL(4-5), FirebirdSQL(1.5-2) and SQLite 3), Weather, Cepstral TTS, CallFile and more.

Perl

Asterisk::FastAGI - Allows you to easily write FastAGI scripts in Perl.

PHP

http://gattolino.blogspot.com/2009/03/asterisk-fastagi-server-in-php.html - FastAGI server in PHP as a daemon.

Python

FATS - FATS is a Twisted and Fast Asterisk's Telephony Services. Async and threaded support.
StarPy - StarPy is a Python + Twisted protocol that provides access to the Asterisk Manager Interface (AMI) and Fast Asterisk Gateway Interface (FastAGI). Together these allow you write both command-and-control interfaces (used, for example to generate new calls) and to customize user interactions from the dial-plan.

Ruby

RAGI - RAGI is a general-purpose library for creating AGI applications with Ruby. It also includes a threaded, fault-tolerant and flexible FastAGI server powered by Webrick.

AGI enhancements

asterisk-agi-audiotx

This is an extension module for the Asterisk Gateway Interface (AGI) that adds commands to allow the transfer of audio files to and from Asterisk via the AGI session. This is useful when using FastAGI from a remote host; sounds recorded by Asterisk may be retrieved by remote FastAGI-providing service, for example, or sound files required by the remote service may be dynamically added to the Asterisk server.
This module adds the following AGI commands:

PUT SOUNDFILE <soundfile> <size>
GET SOUNDFILE <soundfile>
ISEXISTING SOUNDFILE <soundfile>

voip-info.org

Asterisk FastAGI

Page Contents