Skip to content
Phone Guides

Asterisk AGI and FastAGI application design

Use AGI when a dialplan path needs an external program to participate in channel handling. Decide how that program fails before connecting it to callers. The caller's available time is different from the time a background data job can take.

Source-reviewed, 19 October 2026. Prepared from the cited documentation. No AGI application has been independently tested by Phone Guides. Scope: Asterisk 22 AGI/FastAGI design; exact commands require the installed branch reference.

Select the execution model

Local AGI runs a program under the Asterisk service's execution environment. FastAGI connects to a network service. Choose according to ownership, deployment and failure isolation rather than assuming that moving the same logic across a network removes its effect on the call.

The official AGI overview explains the dialplan/program relationship. The branch-22 AGI application reference is the source for invocation and execution details. Treat libraries listed in an overview as candidates whose present maintenance still needs checking.

Keep protocol output separate from diagnostics

Read the supplied environment and exchange commands/responses according to the AGI protocol. Do not write ordinary debug messages into the channel used for protocol responses. Keep application diagnostics on a separate controlled log path, with subscriber inputs and credentials redacted.

Use the version-specific AGI command reference for each command and response meaning. A successful program launch does not establish that a later command completed or that the channel remains available.

Follow a local AGI exchange

Start with a local script that sets a fixed channel variable and makes no network or database request. That isolates program execution and the AGI conversation from a business-service dependency. The branch-22 SET VARIABLE command defines the command used here.

This original Python 3 example reads the initial AGI environment through its blank-line terminator, sends one command and checks a successful result. It deliberately does not log environment values, accept caller text or place another call:


#!/usr/bin/env python3
import re
import sys


def fail():
    print("AGI demonstration did not complete", file=sys.stderr)
    raise SystemExit(1)


for _ in range(256):
    line = sys.stdin.readline(8193)
    if not line or len(line) > 8192:
        fail()
    if line in ("\n", "\r\n"):
        break
else:
    fail()

print('SET VARIABLE PG_AGI_RESULT "ready"', flush=True)
reply = sys.stdin.readline(8193)
if not re.fullmatch(r"200 result=1\s*", reply):
    fail()

Save it as pg-agi-ready.py in the installation's actual AGI directory. Confirm that the service can execute it, that Python 3 is available to its execution environment, and that untrusted users cannot replace the program. Resolve the interpreter path according to your distribution; an interactive shell's environment can differ from the service's.

An isolated dialplan entry can call it like this:


[pg-agi-demo]
exten => 6098,1,Set(PG_AGI_RESULT=unset)
 same => n,AGI(pg-agi-ready.py)
 same => n,NoOp(AGI status=${AGISTATUS}; result=${PG_AGI_RESULT})
 same => n,Hangup()

The number and context are illustrative. Inspect for an existing collision and grant access only from the intended internal context before adding a route to it. This entry does not answer the call or play audio; it shows the script invocation and result boundary. For a successful run, inspect both AGISTATUS and the fixed variable. The AGI application reference defines status meanings; a program's own nonzero exit code should not be assumed to map to a particular AGI status without checking.

This is a one-command demonstration, not a general AGI client. It does not parse arbitrary multi-line responses, implement FastAGI networking or provide a complete hangup/cancellation framework. Production work should use a maintained protocol implementation selected for the actual language and task. A local fixture check of this script is not an Asterisk execution result.

Bound an external dependency

Dependency decision What to document
External request Allowed destination, data and authentication
Timing Connection/read limits within the caller's permitted wait
Failure result Safe fallback route or caller treatment
Retries Which operations can repeat without duplicate side effects
Hangup How pending work is cancelled or safely completed
Execution privilege Files, network destinations and operations the program may use

Do not give a lookup script broad filesystem or PBX-management access as a convenience. For FastAGI, restrict the service to the intended Asterisk clients and protect the network path according to its deployment requirements. Do not assume that the application protocol itself supplies every transport protection you need.

Keep input out of commands

Validate caller-entered digits and external values against the task's accepted set before using them in file paths, database queries or command parameters. Separate a record identifier from display text. A legitimate caller can still supply values the program should not interpret as executable instructions.

Return a defined outcome to the dialplan. An unavailable database should not silently route a caller as if an account had been verified. Use IVR service integration for the larger transaction boundary.

Reader checks

On your own deployment, check normal completion, invalid input, a dependency timeout, malformed response and caller hangup during pending work. Verify that diagnostics do not corrupt the protocol stream and that the fallback is reachable only with the intended permissions.

Preserve application and dialplan versions together for reversal. If the task needs asynchronous management events or direct bridge/media ownership, compare AGI, AMI and ARI before expanding an AGI script into a different control model.

Return to Asterisk documentation.