AVA AI Voice Agent for Asterisk: A Modular Bridge Between PBX and LLM

The Problem: Voice Agents Stuck Inside Proprietary PBX Walled Gardens

Asterisk and FreePBX give you call control, but wiring an AI voice agent into that stack usually means proprietary integrations or hand-rolled glue. AVA targets this gap: it is an open-source Python project that connects Asterisk to speech-to-text, large language model, and text-to-speech providers using AudioSocket and RTP. The intended user is someone who already runs Asterisk or FreePBX and wants to add an AI-driven conversational layer without replacing the PBX. The README frames it as a modular pipeline architecture, so you can mix providers rather than lock into one vendor. That is a real problem for PBX admins who have existing SIP trunks and dialplan logic they do not want to rewrite.

How It Works: AudioSocket, ARI, and a Pipeline of Swappable Providers

The architecture is visible in the README's references to AudioSocket, ARI, and a modular pipeline. AudioSocket handles the RTP media path between Asterisk and the AI engine. ARI, the Asterisk REST Interface, is used for origination and call control; the v7.5.6 release notes mention ARI origination using a documented variables object to pass outbound lead context, routing, identity, and AudioSocket metadata. The AI engine, named ai_engine, runs as a Docker container and exposes a health endpoint on port 15000. The pipeline is not a single monolithic model; you select STT, LLM, and TTS providers per agent, and you can override the provider per call via the AI_PROVIDER channel variable. The README also references 'golden baselines' validated for enterprise deployment, but it does not list them, so you cannot verify what those baselines are without reading the docs.

Getting It Running: Preflight, Docker Compose, and a Dialplan Snippet

The quick start is concrete. Clone the repository, run sudo ./preflight.sh --apply-fixes to create the .env file and generate a JWT_SECRET, then start the admin UI with docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui. The UI listens on port 3003, and the first login uses a one-time password printed to the container logs, which you retrieve with docker compose logs admin_ui | grep -i password. After that, you start ai_engine and check its health with curl http://localhost:15000/health. For the PBX side, the README shows a dialplan snippet for FreePBX's extensions_custom.conf: set AI_AGENT to a slug like sales-agent, optionally set AI_PROVIDER to override, then call Stasis(asterisk-ai-voice-agent). You can generate a current snippet with agent dialplan --agent <slug>. There is also an interactive CLI through ./install.sh and agent setup, with legacy aliases like agent init and agent doctor still present. The Setup Wizard in the UI generates the dialplan for you, so you can avoid the CLI if you prefer.

Transport Modes: The Compatibility Matrix Is the Real Gate

The README insists that transport selection is configuration-dependent, not strictly a matter of pipelines versus full agents. It points to a docs/Transport-Mode-Compatibility.md file as the validated matrix. This is a critical detail: AudioSocket and RTP can behave differently depending on your Asterisk version, codec negotiation, and network topology. The release notes for v7.5.6 mention that 'Full Local negotiates call-scoped support so older servers and malformed overrides fail closed.' That suggests transport compatibility is not universal and that older Asterisk servers may need specific configuration. The README does not tell you which transports work with which Asterisk versions, so you must read that matrix before committing. If you skip this step, you may find calls dropping or media not flowing.

Configuration and Security: Fail-Closed Intentions, Open Ports

Configuration lives in a .env file with API keys for your chosen providers. The preflight script generates a JWT_SECRET, which is good, because a hardcoded secret would be a dealbreaker. The README explicitly warns that the Admin UI is accessible on the network and tells you to restrict port 3003 via firewall, VPN, or reverse proxy. That is a real security boundary, not boilerplate. The v7.5.6 release notes also say that outbound lead context is delivered or the call fails closed, custom_vars is bounded and redacted from diagnostics, and hangup intent markers can be scoped per agent. These are thoughtful fail-closed behaviors. But the README also notes that the first login password is printed to logs, so you must change it immediately. The security posture is reasonable for a self-hosted tool, but it assumes you are comfortable managing network exposure.

Limitations and Failure Modes: Not a Managed Service, and Docs Are the Arbiter

The biggest limitation is that AVA is not a managed service. You run it yourself, and the README points to a separate commercial product, AVA Operator, for managing multiple PBXs. That means if you need centralized management across many customer installations, the core project alone may not suffice. Another failure mode is transport incompatibility: the README says older servers and malformed overrides fail closed, which is safe but means a misconfigured AI_PROVIDER or an outdated Asterisk version could result in no call at all. The health endpoint can return 'degraded' if a subsystem is unhealthy, so a healthy status is not guaranteed. Also, the README mentions 'golden baselines' but does not enumerate them in the snippet you have, so you cannot assess whether they match your use case. The project has a demo site and a Discord, but the README does not provide concrete performance numbers or latency measurements, so any claim about production readiness must come from your own testing.

Alternatives and the Open-Source Landscape

A direct alternative is building your own Asterisk AI integration using ARI and a generic WebSocket or REST bridge to an LLM provider. That approach gives you full control but requires you to handle audio streaming, session state, and provider failover yourself. Another alternative is a commercial voice agent platform that integrates with SIP trunks, but those are typically closed-source and per-minute priced. The key difference with AVA is that it is MIT-licensed and provider-agnostic, so you can swap STT, LLM, and TTS without rewriting the dialplan. However, the README does not compare itself to any specific open-source rival, so you would need to evaluate projects like Asterisk's own AI modules or other GitHub voice agent projects on your own. The commercial AVA Operator is not an alternative but a complement, so do not confuse the two.

Maintenance and Upgrade Cost: Frequent Releases, In-Place Updates

The release history shows active maintenance: v7.5.4 on 2026-07-31, v7.5.5 on 2026-08-08, and v7.5.6 on 2026-08-26. The v7.5.6 notes explicitly state it is an in-place feature and reliability release that does not migrate databases, reassign agents, or change audio profiles. That is good news for upgrade cost, but it also implies other releases might require migration. The README does not provide an upgrade guide in the snippet you have, so you must check docs/ROADMAP.md and the installation guide for upgrade procedures. The license is MIT, which means you can fork and modify freely, but you must retain the license notice. The commercial AVA Operator is a separate product, so its licensing is not covered by the MIT core. For maintenance, you will need to monitor the ai_engine logs and the health endpoint, and you must keep the .env file secure since it holds API keys.

Editorial conclusion

Adopt AVA if you run Asterisk/FreePBX and want a self-hosted voice agent with provider flexibility, especially if you value the MIT license and the admin UI for non-CLI users. Do not adopt it if you need a turnkey managed service, because the README points to a separate commercial product for multi-installation management, and the core requires Docker, a generated JWT secret, and manual dialplan work. Before deploying, verify the transport compatibility matrix for your exact Asterisk version and media path, confirm the health endpoint returns healthy, and test a call with the Setup Wizard while watching ai_engine logs. The project's frequent releases (v7.5.4 to v7.5.6 in under a month) suggest active maintenance, but you must check the docs for database migration or upgrade steps, as v7.5.6 claims no migration but future releases may differ.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes