VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk AGI and FastAGI: bound synchronous call control and external dependencies

Choose local AGI, FastAGI, EAGI or AsyncAGI deliberately; constrain process, network and hangup behavior; and keep launch, protocol, application and call outcomes separate.

Reviewed 2026-10-10Official current Asterisk AGI overview, Asterisk 23 AGI and EAGI application references, AGI command index, VERBOSE command, AsyncAGI AMI action and events, ASYNCAGI BREAK command and deprecated DeadAGI reference reviewed October 10, 2026; no host, process, executable, service account, FastAGI server, DNS or SRV record, TCP path, AMI session, channel, script, command, audio stream or call was inspected or testedAdvancedDocumentation based · not lab tested

Choose AGI only when the dialplan should wait

AGI connects the dialplan to an external program and is generally synchronous: channel operations wait while the program is active. Put a duration budget, failure branch and observable result around that wait. A database, HTTP API, model or other remote dependency inside the script becomes part of the live call path even when Asterisk can launch the script successfully.

Use the smallest interface that matches ownership. Local or FastAGI fits a bounded dialplan step; AsyncAGI lets AMI queue AGI commands and correlate results; ARI fits an application that owns live channel state. Interface choice does not by itself supply authorization, retries, idempotency or proof of the caller-visible outcome.

Select the execution model explicitly

Local AGI(command,args) starts a process and communicates through standard input and output; when the command is not a full path, Asterisk resolves it under astagidir. FastAGI uses an agi:// TCP URI, while hagi:// adds an SRV lookup for _agi._tcp. EAGI behaves like AGI but provides incoming audio out of band on file descriptor 3. None of those forms is interchangeable with agi:async, which is driven through AMI actions and events.

Record the chosen form, exact target and installed branch in the change plan. Do not infer encrypted transport from an AGI URI, and do not revive DeadAGI: the current application reference marks it deprecated and directs operators to AGI.

Define a strict protocol and input contract

Allowlist the script, arguments, channel variables, AGI commands and writable dialplan functions the workflow actually needs. Treat caller-controlled digits, names, URLs and identifiers as untrusted data, and never turn them into an arbitrary EXEC, shell command, file path or dialplan target. Keep credentials out of arguments and routine traces.

Standard output belongs to the AGI dialogue, so keep application logging on a separate sink or use bounded AGI VERBOSE messages. Parse every command response before issuing the next command and attach a safe transaction ID to logs. A process that stays alive while emitting unrelated output, waiting on its own input or failing to consume responses can hold the channel without completing useful work.

Bound local process and filesystem ownership

Resolve the effective astagidir, executable or interpreter path, owner, mode, service identity, working directory, environment and dependency versions from the running Asterisk instance. A script that succeeds in an administrator shell has not proved it can start with Asterisk’s identity, environment, file limits or path.

Give the service account only the files and destinations it requires. Bound runtime, child processes, memory and external calls; return a deliberate dialplan result on failure; and make cleanup safe after termination. Do not widen directory permissions or run Asterisk as a more privileged user to hide an unresolved launch boundary.

Bound FastAGI network and hangup behavior

For FastAGI, inventory the exact URI, name-resolution path, optional SRV record, address, port, route, allowlist, server listener, script selector and downstream dependencies. Define connection and request timeouts plus a dialplan fallback. A reachable TCP port proves neither that the requested service ran nor that its AGI commands produced the intended call result.

Hangup is a separate lifecycle. The AGI application reference says local AGI normally receives SIGHUP, while FastAGI receives a HANGUP indication inline; dialplan execution can remain in AGI until the process exits or the connection closes. Change AGISIGHUP or AGIEXITONHANGUP only for an explicit cleanup model, then test caller hangup during each blocking operation.

Accept launch, dialogue, application and call outcome separately

Capture AGISTATUS immediately after the application and interpret its documented values—SUCCESS, FAILURE, NOTFOUND and HANGUP—as the AGI application result, not proof of a downstream business outcome. For AsyncAGI, preserve channel identity and a unique command ID so AsyncAGIExec results can be matched to the queued AMI action; ASYNCAGI BREAK deliberately returns control to the previous source, usually the dialplan.

Acceptance should cover success, missing executable, invalid input, refused or unavailable FastAGI service, slow downstream dependency, malformed dialogue, caller hangup mid-command and the unaffected-call path. Correlate the dialplan branch, AGI command responses, application record and caller-visible outcome, then remove temporary traces. No AGI execution or call was tested for this guide.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

Asterisk

Understand the programmable PBX and follow the Asterisk 22 LTS documentation baseline.

Explore topic →
Guide · Current Asterisk interface documentation reviewed September 30, 2026; implementation must be checked against the installed branch and integration library

Asterisk AMI, ARI and AGI: choose the control boundary

Separate management events, synchronous dialplan work and application-owned call control before exposing an integration.

Read guide →
Guide · Asterisk 22 LTS

Asterisk dialplan: contexts, patterns and loaded-call evidence

Build a restricted Asterisk 22 call path, then prove its context, match, priorities and runtime behavior separately.

Read guide →
Guide · Current Asterisk logging, runtime command, logger.conf, debug-collection, call-identifier and console-verbosity documentation reviewed September 30, 2026; no process, logger, trace, storage path or call tested

Asterisk logging without permanent debug overload

Map configured destinations, console levels, call identifiers and a bounded protocol trace without leaving sensitive debug collection active.

Read guide →
Guide · Asterisk CDR, CEL, Local Channel and AMI v2 documentation reviewed October 6, 2026; no PBX, channel, call, Local pair, optimization event, CDR, CEL event, backend, database, report, billing calculation or retention workflow was tested

Asterisk CDR and CEL: which record answers the question?

Choose a CDR summary or CEL event chronology deliberately, preserve channel relationships and prove the selected record path before using it for billing or operations.

Read guide →
Troubleshooting · Official current Asterisk AGI overview, Asterisk 23 AGI and EAGI application references, AGI command index, VERBOSE command, AsyncAGI AMI action and events, ASYNCAGI BREAK command and deprecated DeadAGI reference reviewed October 10, 2026; no host, process, executable, service account, FastAGI server, DNS or SRV record, TCP path, AMI session, channel, script, command, audio stream or call was inspected or tested

Asterisk AGI script fails or hangs: launch, protocol, dependency and hangup proof

Trace one call through the dialplan application, process or FastAGI connection, AGI dialogue, application result and post-AGI branch without blind retries.

Read guide →
Troubleshooting · Current Asterisk ARI overview, configuration, getting-started, Stasis application, res_ari and outbound-WebSocket documentation reviewed October 6, 2026; exact running branch, build options, modules, configuration, credentials, application process, proxy, WebSocket, dialplan, channel and call require runtime verification

Asterisk ARI Stasis application is not registered: control-path diagnosis

Trace HTTP service, ARI user, WebSocket ownership, exact application name and Stasis lifecycle when a channel immediately leaves an ARI application.

Read guide →