What AGI is and how VICIdial uses it

When a call lands on Asterisk, the Dialplan decides what happens next. Most of the time that means simple steps: answer, play a prompt, route to an agent. But for anything more complex — looking up a lead, routing by a database value, monitoring a live session — Asterisk needs to hand control to an external program. That handoff mechanism is AGI, the Asterisk Gateway Interface AGI (Asterisk Gateway Interface).

In VICIdial, AGI scripts are designed to allow application-level control of selected features, extending or replacing what the raw dialplan alone can do. Each script is a program — typically a Perl script with a .agi extension — that Asterisk spawns as a child process when the dialplan reaches an AGI() application call. The script reads from and writes to Asterisk over stdin/stdout using a simple line-based protocol. Asterisk blocks on the current extension step while the script runs, then resumes when the script exits.

This matters because the native dialplan is a fixed list of steps: it can answer, play a file, dial a number, and branch on a pressed digit, but it cannot make decisions that depend on the contents of the VICIdial database. AGI is the bridge — when a call needs a decision driven by live data, the dialplan hands off to a script that can query MySQL, talk to the VICIdial API (application programming interface), and then tell Asterisk what to do. The script becomes a temporary, programmable extension of the dialplan for that one step.

How Asterisk executes an AGI script

flowchart TD
  A[Inbound call arrives] --> B[Asterisk reads extensions.conf]
  B --> C{Dialplan step is AGI?}
  C -- No --> D[Run native Asterisk app]
  C -- Yes --> E[Spawn agi script as child process]
  E --> F[Script reads channel vars from Asterisk]
  F --> G[Script queries DB or VICIdial API]
  G --> H[Script sends commands back to Asterisk]
  H --> I[Asterisk executes commands on live call]
  I --> J[Script exits]
  J --> K[Dialplan resumes next step]

In the dialplan, an AGI step looks like any other extension line. The AGI() application takes the script name first, then any arguments, runs it, waits, and moves to the next priority when it finishes. A minimal example that hands an inbound call to the DID router reads like this:

[trunkinbound]
exten => _X.,1,AGI(agi-DID_route.agi)

Here _X. matches any dialed number, and the AGI line passes the call to agi-DID_route.agi, which reads the called number and decides where the call goes. The script does the database work; Asterisk just executes what it returns.

The agi-*.agi script family

VICIdial ships a collection of AGI scripts covering common scenarios. Each one is named for the task it handles. agi-DID_route.agi routes inbound calls by looking up the DID (direct inward dialing) in VICIdial's database and sending the call to the matching in-group or call menu. agi-AGENT_dial_in.agi lets an Agent dial in from any phone to attach to their active VICIdial session — useful for remote agents or softphone failovers. agi-dtmf.agi plays DTMF tones read from the caller ID field, which supports automated outbound dialing that needs to navigate phone trees.

Other scripts handle three-way call coordination: agi-3way_press_agent.agi and agi-3way_press_outside.agi work together so an outside agent must press 1 to accept a transfer before the call bridges. The agent_monitor.agi script lets a supervisor dial in and silently listen to a live Agent session without the agent knowing. Additional utility scripts cover call-card PIN lookups, Canadian PRI caller ID name injection, and call waiting.

Two ways to invoke an AGI in VICIdial

Most AGI scripts can be invoked in two ways. The first is directly in the dialplan via an exten => line in extensions.conf. The second is through a Call menu, VICIdial's in-database equivalent of a dialplan context. A call menu can have an AGI field that names the script and its arguments, letting you configure behavior without editing extensions.conf. Some scripts — like agent_monitor.agi — still require entries in the System Settings "Custom Dialplan Entry" field; the call menu alone is not enough.

Arguments are passed to AGI scripts as positional parameters separated by triple dashes. For example, agent_monitor.agi,USER---N---LISTEN------TEST--TEST2---N sets the lookup method, logging, and monitoring mode in that order. Each script documents which position corresponds to which setting. Empty positions between dashes keep that argument at its default, which is why you sometimes see a run of dashes with nothing in between.

When does an operator care about this? Mostly when inbound routing sends every trunk call through agi-DID_route.agi, or when a feature like supervisor monitoring tells you to add a custom dialplan entry — that entry exists to invoke an AGI. It also matters when something breaks, because an AGI failure shows up in the Asterisk logs as a script error rather than a normal hangup. You rarely write these scripts, but recognising them turns a confusing log line into an obvious next step.

For a full reference on how the IVR (interactive voice response) and call menus connect to AGI scripts, see the next article in this series. To understand how AGI sits alongside the HTTP-based API functions, visit the VICIdial API and AGI overview. For a comparison that helps you decide which tool to reach for, read the Non-Agent API vs Agent API breakdown. If you would rather skip the setup and get a VICIdial box with AGI scripts already in place, see VICIfast plans.