Asterisk AGI development: dynamic call logic, done right

Asterisk AGI (Asterisk Gateway Interface) is the oldest and still one of the most practical ways to put real business logic inside a phone system. When a call hits the AGI() application in the dialplan, Asterisk hands control to an external program that can query a database, call a CRM API, play prompts, collect DTMF digits and decide where the call goes next. Voxivra has been building Asterisk AGI applications since the early days of the platform, and we still use AGI in production whenever it is the right tool.

How AGI works under the hood

AGI is a simple, line-based protocol. When a channel enters AGI(), Asterisk first sends a block of agi_* variables (caller ID, called number, channel name, context, unique ID and so on), followed by a blank line. The program then sends commands such as ANSWER, STREAM FILE, GET DATA, SET VARIABLE or EXEC, and Asterisk replies to each one with a result line (200 result=...).

Two properties matter for design:

• AGI is synchronous. Each command blocks until Asterisk answers it, and the channel is “owned” by the script while it runs. This makes the logic easy to read, but a slow API call means a caller listening to silence.
• The dialplan stays in charge. When the script exits, the call resumes at the next dialplan priority. The AGISTATUS variable tells you whether the script succeeded, failed or saw a hangup.

AGI, FastAGI and EAGI

For anything beyond a handful of concurrent calls, we use FastAGI. Forking an interpreter for every call costs CPU and memory on the Asterisk host, and it prevents connection reuse to your databases. A FastAGI service runs on its own, can be deployed behind a load balancer and can be updated without touching Asterisk.

A typical FastAGI pattern

Here is a simplified dialplan that sends an inbound call to a FastAGI routing service, then uses the variables it returns:

[inbound]
exten => _X.,1,Answer()
 same => n,Set(TIMEOUT(absolute)=3600)
 same => n,AGI(agi://10.0.10.20:4573/route?lang=en)
 same => n,GotoIf($["${AGISTATUS}" != "SUCCESS"]?fallback,s,1)
 same => n,Goto(${ROUTE_CONTEXT},${ROUTE_EXTEN},1)

[fallback]
exten => s,1,Playback(please-hold)
 same => n,Queue(general)

The FastAGI service looks up the caller in the CRM, checks business hours and open tickets, then sets ROUTE_CONTEXT and ROUTE_EXTEN with SET VARIABLE. If the service is unreachable, the dialplan falls back to a general queue instead of dropping the call. That fallback branch is not optional in our projects: the phone system must keep working when an application server does not.

What we build with Asterisk AGI

• Data-driven routing: identify the caller by number or account ID, then route by customer tier, language, open case or assigned agent.
• Dynamic IVR menus: menus generated from a database rather than hard-coded, so business teams can change options without editing the dialplan. See our custom IVR service for the broader picture.
• Self-service flows: balance or order status lookups, PIN verification, appointment confirmation, all over DTMF.
• CRM and ERP integration: creating call records, popping customer files to agents and logging outcomes, as described on our CRM and ERP integration page.
• Legacy modernisation: rewriting old per-call scripts into maintainable FastAGI services with tests.

Engineering practices that keep AGI reliable

AGI is easy to write and easy to get wrong. The issues we fix most often in audits are predictable, so we design against them from day one.

Timeouts everywhere

Every external call inside an AGI handler gets a strict timeout, typically well under the time a caller will tolerate in silence. If the CRM does not answer in time, the script returns a safe default and the call moves on. For lookups that can be slow, we play a short prompt or music while waiting, or pre-fetch data earlier in the flow.

Hangup handling

Callers hang up mid-script. A robust handler detects the hangup (an error result or HANGUP notification), stops issuing channel commands and still finishes its bookkeeping, such as writing the call record. Post-call work that does not need the channel is moved to the h extension or a hangup handler, or pushed to a queue.

Stateless services

A FastAGI server should not hold call state in memory between requests if you want to run several instances. We keep state in the dialplan variables, a database or a cache, which makes horizontal scaling and rolling updates straightforward.

Observability

Each AGI request logs the Asterisk unique ID (agi_uniqueid), so a call can be traced from the dialplan through the application logs to the CRM. We add metrics for latency and error rates per handler, which turns “the IVR is slow” into a precise diagnosis.

Security

FastAGI has no built-in authentication or encryption. The service must only listen on a private network or be restricted by firewall to the Asterisk hosts. We never expose port 4573 to the internet. More on this in our VoIP security expertise.

When Voxivra recommends AGI (and when not)

We recommend AGI, and specifically FastAGI, when:

• you already have a working dialplan and want to add decisions or lookups without rewriting the call flow;
• the interaction is mostly prompts and DTMF, with a linear, step-by-step logic;
• your team is comfortable with the dialplan and wants to keep it as the source of truth.

We usually recommend Asterisk ARI instead when the application needs to control several channels and bridges at once, react to asynchronous events, or stream audio to speech recognition for a conversational voicebot. AGI’s blocking model is not designed for real-time, full-duplex audio. Many of our deployments combine both: AGI for routing and simple self-service, ARI for the AI-driven parts. We compare the two in detail in our article Asterisk AGI vs ARI.

How we work on AGI projects

1. Review of your current dialplan, scripts and call volumes.
2. Design of the handlers, data sources, timeouts and fallback paths.
3. Implementation of the FastAGI service, with automated tests that simulate the AGI protocol.
4. Load testing with SIP traffic generators before go-live.
5. Deployment and support, including monitoring and documentation for your team.

If you have an existing AGI codebase that has grown hard to maintain, or a new call flow to build, describe your setup to us and we will tell you frankly whether AGI is the right fit.