# Show HN: Self-hosted voice AI agent for Asterisk/FreePBX > Source: > Published: 2026-07-13 02:51:34+00:00 The most powerful, flexible open-source AI voice agent for Asterisk/FreePBX. Featuring a **modular pipeline architecture** that lets you mix and match STT, LLM, and TTS providers, plus **6 production-ready golden baselines** validated for enterprise deployment. [🚀 Quick Start](#-quick-start)[🎉 What's New](#-whats-new)[🌟 Why Asterisk AI Voice Agent?](#-why-asterisk-ai-voice-agent)[✨ Features](#-features)[🎥 Demo](#-demo)[🛠️ AI-Powered Actions](#-ai-powered-actions)[🩺 Agent CLI Tools](#-agent-cli-tools)[⚙️ Configuration](#-configuration)[🏗️ Project Architecture](#-project-architecture)[📊 Requirements](#-requirements)[🗺️ Documentation](#-documentation)[🤝 Contributing](#-contributing)[💬 Community](#-community)[📝 License](#-license) Get the **Admin UI running in 2 minutes**. For a complete **first successful call** walkthrough (dialplan + transport selection + verification), see: ``` # Clone repository git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git cd AVA-AI-Voice-Agent-for-Asterisk # Run preflight with auto-fix (creates .env, generates JWT_SECRET) sudo ./preflight.sh --apply-fixes ``` Important:Preflight creates your`.env` file and generates a secure`JWT_SECRET` . Always run this first! ``` # Start the Admin UI container docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui ``` Open in your browser: **Local:**`http://localhost:3003` **Remote server:**`http://:3003` **Default Login:** On first start, a one-time admin password is printed to the container logs. Retrieve it with: ``` docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password ``` You must change it at first login. Restrict port 3003 via firewall, VPN, or reverse proxy for production use. Follow the **Setup Wizard** to configure your providers and make a test call. ⚠️ Security:The Admin UI is accessible on the network. Restrict port 3003 via firewall, VPN, or reverse proxy for production use. GPU users:If you have an NVIDIA GPU for local AI inference, seefor the GPU compose overlay ([docs/LOCAL_ONLY_SETUP.md]`docker-compose.gpu.yml` ) before building. ``` # Start ai_engine (required for health checks) docker compose -p asterisk-ai-voice-agent up -d --build ai_engine # Check ai_engine health curl http://localhost:15000/health # Expected: {"status":"healthy"} ("degraded" is also possible if a subsystem is unhealthy) # View logs for any errors docker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20 ``` The wizard will generate the necessary dialplan configuration for your Asterisk server. Transport selection is configuration-dependent (not strictly “pipelines vs full agents”). Use the validated matrix in: For users who prefer the command line or need headless setup. ``` ./install.sh agent setup ``` Note: Legacy commands `agent init` ,`agent quickstart` ,`agent doctor` ,`agent troubleshoot` , and`agent demo` remain as hidden compatibility aliases. New workflows should use the visible commands documented in[.]`docs/CLI_TOOLS_GUIDE.md` ``` # Configure environment cp .env.example .env # Edit .env with your API keys # Start services docker compose -p asterisk-ai-voice-agent up -d ``` Add this to your FreePBX (`extensions_custom.conf` ): ``` js [from-ai-agent] exten => s,1,NoOp(Asterisk AI Voice Agent) ; AI_AGENT selects an operator-managed agent by slug. same => n,Set(AI_AGENT=sales-agent) ; Optional: override that agent's configured provider/pipeline for this call. ; same => n,Set(AI_PROVIDER=google_live) same => n,Stasis(asterisk-ai-voice-agent) same => n,Hangup() ``` Notes: - Use `AI_AGENT` to select an operator-managed agent. Its configured target is authoritative unless`AI_PROVIDER` is intentionally set as a per-call override. - Generate a current snippet with `agent dialplan --agent ` . - See `docs/FreePBX-Integration-Guide.md` for channel variable precedence and examples. **Health check:** ``` agent check ``` **View logs:** ``` docker compose -p asterisk-ai-voice-agent logs -f ai_engine ``` **v7.3.2 — stabilization release 🛡️** v7.3.2 is a stabilization-only patch release built from the supervised AudioSocket and ExternalMedia validation cycle. **No new providers**— scope is limited to reliability, deployment safety, documentation, and contributor-facing CI.** Grok ExternalMedia repaired**— clean barge-in, cancelled-output quarantine, named-instance runtime inheritance, complete replacement turns, and exact inactivity announcements through xAI`force_message` .**AudioSocket and modular pipelines hardened**— terminal playback, pipeline producer ownership, talk-detect echo, and inactivity-grace regressions are covered by focused tests and supervised calls.**Updater and provider-failure recovery hardened**— safer ownership, rollback/stash handling, readiness validation, and an opt-in dialplan redirect.** PR quality gates expanded**— Admin backend/frontend checks and CLI cross-compilation now run before merge. Release evidence and remaining gates are tracked in the [v7.3.2 validation matrix](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/baselines/golden/v7.3.2-validation-matrix.md). **v7.3.1 — Silence watchdog & safe call endings ☎️** **AVA now protects silent calls and finishes every terminal message before disconnecting.** **30-second inbound inactivity protection by default**— AVA asks “Are you still there?”, waits 15 seconds for a reply, then speaks a configurable final warning and ends the call. Outbound agents remain opt-in.**The agent keeps its configured voice**— check-ins and final warnings are synthesized by the active Google Live, OpenAI Realtime, Grok, Deepgram, ElevenLabs, local full-agent, or pipeline voice.**Transport-safe hangup**— watchdog and`hangup_call` farewells drain AudioSocket or ExternalMedia/RTP streaming buffers and ARI file playback before ARI disconnects the caller. Fixed sleeps no longer clip long final sentences.**Deepgram and ElevenLabs lifecycle fixes**— Deepgram control frames no longer split greetings, and ElevenLabs response-completion plus hosted-silence handling keeps AVA's watchdog authoritative.**Global and per-agent controls**— configure defaults under** Advanced Settings → Voice Activity Detection → Caller Inactivity**, then optionally override them per agent. Call History labels watchdog endings as** No input timeout**. See [Caller inactivity configuration](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Configuration-Reference.md#caller-inactivity-no_input), [ElevenLabs setup](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Provider-ElevenLabs-Setup.md#ava-caller-inactivity-compatibility-v731), and the full [v7.3.1 changelog](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md#731---2026-07-09). **v7.3.0 — Per-agent voices 🎙️** **Voice now belongs to agents.** Configure one provider, create multiple agents that share it — each with its own voice. **Provider-aware voice picker** in the Agent form: a dropdown of OpenAI's 10 GA voices, suggestions + custom clone IDs for Grok, Google Live's 30 prebuilt voices, Deepgram's Aura models — the control adapts to the agent's selected AI Engine.**Safe by default**— the provider-level voice becomes the*default voice*; agents without one behave exactly as before. Unrecognized values (OpenAI/Google/Deepgram catalogs are validated) log a warning and fall back — a bad voice value never fails a call.**Observable**— every call logs the resolved voice and its source, and Call History shows "Voice: marin (from agent)" per call.- Agent voice changes apply instantly — no engine restart. Thanks @foytech for seeding this feature (#497). Full guide: [docs/VOICE_SELECTION.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/VOICE_SELECTION.md). **v7.2.0 — Live-status dashboard 📡** Real-time system status for the Admin UI — pushed, not polled. **Live-status hub**— a single`/api/live-status` snapshot endpoint plus an SSE stream (`/api/live-status/stream` ) aggregates AI Engine health, Local AI connectivity, active sessions, audio directories, platform checks, and Asterisk ARI into one normalized status feed.**Push-first**—`ai_engine` and`local_ai_server` push their own readiness to the Admin UI (`POST /api/live-status/publish` , authenticated with`LIVE_STATUS_PUSH_TOKEN` ), so the dashboard converges in sub-second time after a restart instead of waiting on staggered polls. Legacy`/api/system/*` probes remain as fallback/enrichment.**Configurable**—`LIVE_STATUS_POLL_INTERVAL_SECONDS` (default 30 s, min 2 s) and`LIVE_STATUS_INITIAL_PROBE_TIMEOUT_SECONDS` (default 2 s), read live from`.env` . Full notes in [CHANGELOG.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md). **v7.1.1 — Dashboard reliability & Admin UI polish 🛠️** A focused quality release across the Admin UI — no call-path changes. **Dashboard reliability**— the Asterisk status pill no longer flaps on a transient ARI blip: it reads the engine's authoritative, reconnect-supervised ARI state and applies hysteresis. The system endpoints the Dashboard polls every 5s no longer block the admin event loop, the heaviest is TTL-cached, polling backs off on errors, failed polls surface in the error banner, and a single bad poll no longer flashes cards to "Loading…".**No more "Loading configuration…" flash**— ~11 config pages now seed from a shared stale-while-revalidate cache of the config document, so revisiting a settings page is instant.**Accessibility (WCAG AA)**— form labels programmatically associated with inputs, a focus-trapping modal, a navigation landmark + "skip to content" link, accessible names on icon-only buttons, non-colour status cues on the topology, a visible dark-mode toggle on-state, and light-mode contrast fixes. Debug`console.log` s (including one that leaked the auth token to the browser console) were removed.**Prompt editor**— configured tool names are colour-coded by their in-call status (enabled / global / not-enabled) as you type.** Fix (#436)**— a canonical`google_live: { type: full }` provider can be edited and saved again. Full notes in [CHANGELOG.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md). **v7.0.0 — the Agents release 🎯** The biggest release yet: **manage your AI agents from the Admin UI, not a config file.** **🤖 Agents tab**— create, edit, and manage agents in the UI. Start from a template (receptionist, after-hours, appointment booker, and more), set the prompt and provider, and copy a ready-to-paste dialplan snippet. (Voice is configured on the provider, not per agent.)**📊 Multi-agent dashboard**— live KPIs (active agents, active calls, calls routed, transfers), per-agent stats, and routing breakdowns at a glance.**☎️ New**— route a call to an agent by name. Your existing`AI_AGENT` dialplan variable`AI_CONTEXT` dialplans keep working unchanged.**🔄 Automatic migration**— your existing contexts move into a local agents database on first start. Nothing to do, and rollback is one command.**🔒 Security hardening**— no more`admin` /`admin` : a one-time admin password is generated and must be changed at first login. Config exports no longer bundle your`.env` by default. [Upgrade Notes](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md) before upgrading from 6.x. **v6.5.4 (2026-05-25) — OpenAI Realtime GA cleanup across every code path** Follow-up to the v6.5.3 hotfix. v6.5.3 only flipped `config/ai-agent.yaml` ; v6.5.4 brings the rest of the codebase in line: **Pydantic defaults** in`src/config.py` now default to`api_version: ga` +`model: gpt-realtime` (so fresh wizard installs are correct).**Admin UI "Add Provider" template** for OpenAI Realtime no longer seeds the sunset preview model.**Model dropdown** removes the 5 sunset preview options and adds 3 new GA models —`gpt-realtime-1.5` (best audio-in/audio-out quality),`gpt-realtime-2` (reasoning voice model, GPT-5-class), and`gpt-realtime-mini` (cost-optimized) — alongside the existing`gpt-realtime` .**Legacy preview values in operator YAML** now render in a "Custom (legacy — will not connect)" optgroup with a yellow warning banner above the form so the broken state is visible without silently swapping the operator's config.**Engine** emits a one-shot warning when`api_version: beta` is detected in config (exactly once per provider lifetime, not per reconnect attempt).**Docs**: full rewrite of`docs/Provider-OpenAI-Setup.md` model section + fix to`docs/TROUBLESHOOTING_GUIDE.md` . **v6.5.3 hotfix (2026-05-25) — OpenAI Realtime restored** OpenAI sunset the Realtime **Beta** API on 2026-05-12 and removed the `gpt-4o-realtime-preview-2024-12-17` model on 2026-05-07. Shipped `config/ai-agent.yaml` still pinned `api_version: beta` + that preview model, so every operator using OpenAI Realtime hit `error.code: beta_api_shape_disabled` and the WebSocket closed immediately. **Two-line config flip — no code change required**. The provider's GA wire-protocol path has shipped since v6.0.0; v6.5.3 just makes it the default everyone gets: `api_version: ga` (was`beta` )`model: gpt-realtime` (was`gpt-4o-realtime-preview-2024-12-17` ) If you have an `ai-agent.local.yaml` that explicitly pins `api_version: beta` , remove the override or change it to `ga` . Refs: [OpenAI deprecations](https://developers.openai.com/api/docs/deprecations), [gpt-realtime](https://platform.openai.com/docs/models/gpt-realtime). **v6.5.2 (2026-05-24) — xAI Grok + multi-instance full-agent providers** - Fifth full-agent realtime provider — structurally parallel to OpenAI Realtime and Google Live, built on a multi-instance foundation from day one - μ-law @ 8 kHz caller input with no input resampling; observed xAI output is PCM16 @ 24 kHz and AAVA converts it to the configured Asterisk transport format - Five named voices ( `eve` ,`ara` ,`rex` ,`sal` ,`leo` ) plus custom voice ID free-text for cloned voices - Custom function-tools identical to OpenAI Realtime; xAI-native tools ( `web_search` ,`x_search` ,`file_search` ,`mcp` ) accepted via YAML`extra_tools` escape hatch - Conservative long-session warning at 28 minutes for compatibility with older xAI limits; xAI's current Voice Agent model page lists a 120-minute maximum session - Setup guide: [docs/Provider-Grok-Setup.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Provider-Grok-Setup.md) - Run multiple instances of the same full-agent provider type with isolated credentials (e.g. `acme_google_live` +`globex_google_live` both using`type: google_live` ) - Per-instance credential files at `/app/project/secrets/providers//{api-key,agent-id,vertex-json}` — the new per-provider Vertex upload path does NOT mutate`.env` - Route via `AI_PROVIDER` channel var,`contexts..provider:` YAML, or DID-based dispatch with Asterisk`Gosub` - Setup guide: [docs/Multi-Instance-Full-Agent-Providers.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Multi-Instance-Full-Agent-Providers.md) **Breaking for multi-instance setups:** short aliases`AI_PROVIDER=openai` ,`AI_PROVIDER=google` ,`provider: deepgram_agent` now fail validation — use exact provider instance keys instead. Single-instance setups using the canonical block names are unaffected. - Uniform per-instance credentials paste-style uploader across all full-agent provider forms (Grok, OpenAI Realtime, Deepgram, Google Live, ElevenLabs Agent) - EnvPage adds a new "Per-Instance Provider Credentials" status section so operators can audit credential file presence without SSH - Dashboard System Topology rebuilt: tri-state per-component health with 2-strike debounce (transient probe blips no longer flip dots red), responsive provider grid, multi-instance sub-rows grouped by provider type, Asterisk + AI Engine cards stretched to match Providers height - Backend probe timeouts bumped (ai_engine 1.5s → 5s; local_ai_server 2.5s → 5s) to stop legitimate localhost probes timing out under load - ~260 inline help tooltips backfilled across provider forms, Setup Wizard, and System pages — new `HelpTooltip` is viewport-aware (flips placement to keep popovers visible in scrolled modals) - Browser playback for compact `.ulaw` recordings (Asterisk's 8 kHz μ-law output, ~10× smaller than PCM WAV) via server-side`audioop.ulaw2lin` WAV wrapping — no transcode dependency - Uppercase `.WAV` , compressed WAV, and`.gsm` recordings transcode via`sox` ;`AAVA_RECORDING_TRANSCODE_TIMEOUT_SEC` env var (default 120s) governs the timeout - 💻 CPU-demo profile end-to-end — Faster-Whisper `tiny.en` + Piper + Qwen 0.5B wired through the Admin UI; runtime Device/Compute selectors with CPU/`float16` gating; Filler Audio and LLM/TTS Overlap runtime toggles - 🛡️ Local provider hot-path hardening — `send_audio()` no longer blocks on per-frame reconnect;`asyncio.Lock` serializes`_reconnect()` against`_send_loop` 's on-`ConnectionClosed` path - 🎨 Faster-Whisper verify path tolerates the runtime CUDA→CPU fallback so working CPU/int8 configurations no longer get rolled back as "verification failed" - 🔧 Local LLM tool-gated response (#368) — new WS protocol message types `tool_context` /`tool_result` v2; per-WebSocket fail-closed sync prevents cross-call ACL/policy/prompt leakage on reused connections - ☁️ Gemini 3.1 Flash Live verified compatible (no engine changes); Vertex AI mode is the production answer for #351 barge-in - 🎤 Deepgram Flux v2 + nova-3 default flip; Admin UI surfaces "Flux Turn-Detection Tuning" panel for flux-* models - 🩺 Admin UI HTTP-tool-test guard now reads `.env` first so Environment-page edits to`AAVA_HTTP_TOOL_TEST_*` take effect without a container restart (#370) For older releases, expand **Previous Versions** below. Full release notes in [CHANGELOG.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md). **Previous Versions** - 🗓️ Microsoft Calendar — Outlook / Microsoft 365 integration via device-code OAuth, Graph free/busy, per-context account binding, Tools UI Connect/Verify/Disconnect - 📅 Google Calendar — multi-account / per-context binding (#338), JSON upload + auto-discover, Domain-Wide Delegation, native free/busy mode - 🎯 Reschedule reliability — server-side `event_id` resolution + 400/404 fallback eliminates LLM-id-hallucination duplicate bookings - 🔧 Date/time prompt placeholders ( `{today}` ,`{current_date}` , etc.) so models stop reasoning with stale years - OpenAI Realtime duplicate-events fix (per- `response_id` async-event gating); per-context`tool_overrides` now actually take effect on OpenAI Realtime / Deepgram / Google Live; Google Live 30-voice catalog (#349) - ⚡ Streaming LLM→TTS overlap — sentence-boundary token streaming, sub-2s perceived latency on pipelines - Pipeline filler audio (instant "One moment please" acknowledgment) configurable via Admin UI - Qwen 2.5-1.5B Instruct recommended for CPU; ~15-30 tok/s vs Phi-3's ~0.8 tok/s - Direct PCM→µ-law conversion in all 5 TTS backends (10-50ms saved per response) - Preflight hardening — Buildx detection, RAM/disk/network checks, GPU install gated behind `--apply-fixes` - 📞 Attended transfer with three screening modes: `basic_tts` ,`ai_briefing` ,`caller_recording` - ExternalMedia RTP streaming delivery; provider-agnostic transfer-target tool guidance - 🗣️ Russian speech backends: Sherpa Offline STT (VAD-gated), T-one STT, Silero TTS (multi-language) - 🎧 Admin UI: fullscreen dashboard panels, per-message conversation timestamps, JSONPath `[*]` HTTP-tool wildcards - Microsoft Azure Speech Service STT & TTS pipeline adapters (REST batch, WebSocket streaming, SSML) - MiniMax LLM M2.7 via OpenAI-compatible API with tool-calling - Call Recording Playback in Admin UI Call Details modal - Azure SSRF prevention, PII logging discipline, input validation hardening - Backend enable/rebuild flow, model lifecycle UX, GPU ergonomics, CPU-first onboarding - Structured local tool gateway, hangup guardrails, tool-call parsing robustness `agent check --local` /`--remote` CLI verification - Operator config overrides ( `ai-agent.local.yaml` ), live agent transfer tool - Experimental ViciDial community-tested configuration notes, Asterisk config discovery in Admin UI - OpenAI Realtime GA API, Email system overhaul, NAT/GPU support - Pre-call HTTP lookups, in-call HTTP tools, and post-call webhooks (Milestone 24) - Deepgram Voice Agent language configuration - ExternalMedia RTP greeting cutoff fix **🌍 Pre-flight Script**: System compatibility checker with auto-fix mode.**🔧 Admin UI Fixes**: Models page, providers page, dashboard improvements.**🛠️ Developer Experience**: Code splitting, ESLint + Prettier. **🎤 New STT Backends**: Kroko ASR, Sherpa-ONNX.**🔊 Kokoro TTS**: High-quality neural TTS.**🔄 Model Management**: Dynamic backend switching from Dashboard.**📚 Documentation**: LOCAL_ONLY_SETUP.md guide. **🖥️ Admin UI**: Modern web interface ([http://localhost:3003](http://localhost:3003)).**🎙️ ElevenLabs Conversational AI**: Premium voice quality provider.**🎵 Background Music**: Ambient music during AI calls. **🔧 Complete Tool Support**: Works across ALL pipeline types.**📚 Documentation Overhaul**: Reorganized structure.**💬 Discord Community**: Official server integration. **🤖 Google Live API**: Gemini 2.0 Flash integration.**🚀 Interactive Setup**:`agent init` wizard (`agent quickstart` remains available for backward compatibility). **🔧 Tool Calling System**: Transfer calls, send emails.**🩺 Agent CLI Tools**:`doctor` ,`troubleshoot` ,`demo` . | Feature | Benefit | |---|---| Asterisk-Native | Works directly with your existing Asterisk/FreePBX - no external telephony providers required. | Truly Open Source | MIT licensed with complete transparency and control. | Modular Architecture | Choose cloud, local, or hybrid - mix providers as needed. | Production-Ready | Battle-tested baselines with Call History-first debugging. | Cost-Effective | Local Hybrid costs ~$0.001-0.003/minute (LLM only). | Privacy-First | Keep audio local while using cloud intelligence. | - **OpenAI Realtime**(Recommended for Quick Start)- Modern cloud AI with natural conversations (<2s response). - Config: `config/ai-agent.golden-openai.yaml` *Best for: Enterprise deployments, quick setup.* - **Deepgram Voice Agent**(Enterprise Cloud)- Advanced Think stage for complex reasoning (<3s response). - Config: `config/ai-agent.golden-deepgram.yaml` *Best for: Deepgram ecosystem, advanced features.* - **Google Live API**(Multimodal AI)- Gemini Live (Flash) with multimodal capabilities (<2s response). - Config: `config/ai-agent.golden-google-live.yaml` *Best for: Google ecosystem, advanced AI features.* - **ElevenLabs Agent**(Premium Voice Quality)- ElevenLabs Conversational AI with premium voices (<2s response). - Config: `config/ai-agent.golden-elevenlabs.yaml` *Best for: Voice quality priority, natural conversations.* - **Local Hybrid**(Privacy-Focused)- Local STT/TTS + Cloud LLM (OpenAI). Audio stays on-premises. - Config: `config/ai-agent.golden-local-hybrid.yaml` *Best for: Audio privacy, cost control, compliance.* - **Telnyx AI Inference**(Cost-Effective Multi-Model)- Local STT/TTS + Telnyx LLM with 53+ models (GPT-4o, Claude, Llama). - OpenAI-compatible API with competitive pricing. - Config: `config/ai-agent.golden-telnyx.yaml` *Best for: Model flexibility, cost optimization, multi-provider access.* - **xAI Grok Voice Agent**(Realtime Voice)- xAI realtime voice with five named voices ( `eve` /`ara` /`rex` /`sal` /`leo` ) or a custom cloned voice; μ-law @ 8 kHz caller input and observed PCM16 @ 24 kHz output converted for Asterisk. - Config: `config/ai-agent.golden-grok.yaml` *Best for: xAI ecosystem, telephony-native low-latency audio.* - xAI realtime voice with five named voices ( **MiniMax LLM**(High-Performance Cost-Effective)- Local STT/TTS + MiniMax M3 LLM with enhanced reasoning and coding. - OpenAI-compatible API with tool-calling support. - Models: `MiniMax-M3` (default, latest flagship),`MiniMax-M2.7` (previous flagship),`MiniMax-M2.7-highspeed` (low-latency). - Activate: set `MINIMAX_API_KEY` in`.env` , then configure`providers.minimax_llm` in`config/ai-agent.yaml` (see the`minimax_llm` section with`enabled: true` ). *Best for: Long-context conversations, cost-effective high-performance LLM.* AVA also supports a **Fully Local** mode (100% on-premises, no cloud APIs). Three topologies are supported: | Topology | Latency | Best For | |---|---|---| CPU-Only | 5-15s/turn | Privacy, testing | GPU (same box) | 0.5-2s/turn | Production local | Split-Server (remote GPU) | 1-3s/turn | PBX on VPS + GPU box | GPU setup uses `docker-compose.gpu.yml` overlay with CUDA-enabled llama.cpp. Community-validated: RTX 4090 achieves ~1.0s E2E. - See: (canonical guide for all local topologies)[docs/LOCAL_ONLY_SETUP.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/LOCAL_ONLY_SETUP.md) - Hardware guidance: [docs/HARDWARE_REQUIREMENTS.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/HARDWARE_REQUIREMENTS.md) Run your own local LLM using [Ollama](https://ollama.ai) - perfect for privacy-focused deployments: ``` # In ai-agent.yaml active_pipeline: local_hybrid pipelines: local_hybrid: stt: local_stt llm: ollama_llm tts: local_tts ``` **Features:** **No API key required**- fully self-hosted on your network** Tool calling support**with compatible models (Llama 3.2, Mistral, Qwen)- Local Vosk STT + Your Ollama LLM + Local Piper TTS - Complete privacy - all processing stays on-premises **Requirements:** - Mac Mini, gaming PC, or server with Ollama installed - 8GB+ RAM (16GB+ recommended for larger models) - See [docs/OLLAMA_SETUP.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/OLLAMA_SETUP.md)for setup guide **Recommended Models:** | Model | Size | Tool Calling | |---|---|---| `llama3.2` | 2GB | ✅ Yes | `mistral` | 4GB | ✅ Yes | `qwen2.5` | 4.7GB | ✅ Yes | **Tool Calling System**: AI-powered actions (transfers, emails) work with any provider.** Agent CLI Tools**:`setup` ,`check` ,`rca` ,`update` ,`version` commands (legacy aliases:`init` ,`doctor` ,`troubleshoot` ).**Modular Pipeline System**: Independent STT, LLM, and TTS provider selection.** Dual Transport Support**: AudioSocket (default in`config/ai-agent.yaml` ) and ExternalMedia RTP (both supported — see the transport matrix).**Streaming-First Downstream**: Streaming playback when possible, with automatic fallback to file playback for robustness.** High-Performance Architecture**: Separate`ai_engine` and`local_ai_server` containers.**Observability**: Built-in** Call History**for per-call debugging + optional`/metrics` scraping.**State Management**: SessionStore for centralized, typed call state.** Barge-In Support**: Interrupt handling with configurable gating. Modern web interface for configuration and system management. **Quick Start:** ``` docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui # Access at: http://localhost:3003 # Retrieve one-time password: docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password ``` **Key Features:** **Setup Wizard**: Visual provider configuration.** Dashboard**: Real-time system metrics, container status, and Asterisk connection indicator.** Asterisk Setup**: Live ARI status, module checklist, config audit with guided fix commands.** Live Logs**: WebSocket-based log streaming.** YAML Editor**: Monaco-based editor with validation. Experience our production-ready configurations with a single phone call: **Dial: (925) 736-6718** **Press 4**→ xAI Grok Realtime (NEW in v6.5.2)** Press 5**→ Google Live API (Multimodal AI with Gemini 2.0)** Press 6**→ Deepgram Voice Agent (Enterprise cloud with Think stage)** Press 7**→ OpenAI Realtime API (Modern cloud AI, most natural)** Press 8**→ Local Hybrid Pipeline (Privacy-focused, audio stays local)** Press 9**→ ElevenLabs Agent (Santa voice with background music)** Press 10**→ Fully Local Pipeline (100% on-premises, CPU-based) Your AI agent can perform real-world telephony actions through tool calling. ``` Caller: "Transfer me to the sales team" Agent: "I'll connect you to our sales team right away." [Transfer to sales queue with queue music] ``` **Supported Destinations:** **Extensions**: Direct SIP/PJSIP endpoint transfers.** Queues**: ACD queue transfers with position announcements.** Ring Groups**: Multiple agents ring simultaneously. **Cancel Transfer**: "Actually, cancel that" (during ring).** Hangup Call**: Ends call gracefully with farewell.** Voicemail**: Routes to voicemail box. **Automatic Call Summaries**: Admins receive full transcripts and metadata.** Caller-Requested Transcripts**: "Email me a transcript of this call." | Tool | Description | Status | |---|---|---| `transfer` | Transfer to extensions, queues, or ring groups | ✅ | `cancel_transfer` | Cancel in-progress transfer (during ring) | ✅ | `hangup_call` | End call gracefully with farewell message | ✅ | `leave_voicemail` | Route caller to voicemail extension | ✅ | `send_email_summary` | Auto-send call summaries to admins | ⚙️ Disabled by default | `request_transcript` | Caller-initiated email transcripts | ⚙️ Disabled by default | ``` # In ai-agent.yaml tools: pre_call_lookup: kind: generic_http_lookup phase: pre_call enabled: true is_global: false post_call_webhook: kind: generic_webhook phase: post_call enabled: true is_global: false in_call_tools: intent_router: kind: in_call_http_lookup enabled: true is_global: false contexts: default: pre_call_tools: - pre_call_lookup tools: - intent_router - hangup_call post_call_tools: - post_call_webhook ``` Production-ready CLI for operations and setup. **Installation:** ``` curl -sSL https://raw.githubusercontent.com/hkjarral/Asterisk-AI-Voice-Agent/main/scripts/install-cli.sh | bash ``` **Commands:** ``` agent setup # Interactive setup wizard (recommended) agent setup --list-targets # List configured providers and pipelines without changes agent check # Standard diagnostics report (share this output when asking for help) agent check --local # Verify local AI server (STT, LLM, TTS) on this host agent check --remote # Verify local AI server on a remote GPU machine agent update # Pull latest code + rebuild/restart as needed agent rca --call --no-llm # Deterministic post-call RCA agent config validate # Validate provider, pipeline, transport, and audio configuration agent dialplan --agent default # Generate an AI_AGENT dialplan snippet agent version # Version information ``` - Golden baseline configs (git-tracked, upstream-managed).`config/ai-agent.yaml` - Operator overrides (git-ignored). Any keys here are deep-merged on top of the base file at startup; all Admin UI and CLI writes go here so upstream updates never conflict.`config/ai-agent.local.yaml` - Secrets and API keys (git-ignored).`.env` **Example .env:** ``` OPENAI_API_KEY=sk-your-key-here DEEPGRAM_API_KEY=your-key-here ASTERISK_ARI_USERNAME=asterisk ASTERISK_ARI_PASSWORD=your-password ``` The engine exposes Prometheus-format metrics on its health/metrics HTTP endpoint at `/metrics` (port `15000` ). This endpoint binds to `127.0.0.1` by default, so it is only reachable from the engine host — scrape it locally, or set the health endpoint `host` to `0.0.0.0` (and firewall it) to expose it to an external Prometheus. Per-call debugging is handled via **Admin UI → Call History**. Two-container architecture for performance and scalability: (Lightweight orchestrator): Connects to Asterisk via ARI, manages call lifecycle.`ai_engine` (Optional): Runs local STT/LLM/TTS models (Vosk, Faster Whisper, Whisper.cpp, Sherpa, Kroko, Piper, Kokoro, MeloTTS, llama.cpp).`local_ai_server` ``` php graph LR A[Asterisk Server] <-->|ARI, RTP| B[ai_engine] B <-->|API| C[AI Provider] B <-->|WS| D[local_ai_server] style A fill:#f9f,stroke:#333,stroke-width:2px style B fill:#bbf,stroke:#333,stroke-width:2px style C fill:#bfb,stroke:#333,stroke-width:2px style D fill:#fbf,stroke:#333,stroke-width:2px ``` | Requirement | Details | |---|---| Architecture | x86_64 (AMD64) only | OS | Linux with systemd | Supported Distros | Ubuntu 20.04+, Debian 11+, RHEL/Rocky/Alma 8+, Fedora 38+, Sangoma Linux | Note:ARM64 (Apple Silicon, Raspberry Pi) is not currently supported. See[Supported Platforms]for the full compatibility matrix. | Type | CPU | RAM | GPU | Disk | |---|---|---|---|---| Cloud (OpenAI/Deepgram) | 2+ cores | 4GB | None | 1GB | Local Hybrid (cloud LLM) | 4+ cores | 8GB+ | None | 2GB | Fully Local (CPU) | 4+ cores (2020+) | 8-16GB | None | 5GB | Fully Local (GPU) | 4+ cores | 8-16GB | RTX 3060+ | 10GB | - Docker + Docker Compose v2 - Asterisk 18+ with ARI enabled - FreePBX (recommended) or vanilla Asterisk The `preflight.sh` script handles initial setup: - Seeds `.env` from`.env.example` with your settings - Prompts for Asterisk config directory location - Sets `ASTERISK_UID` /`ASTERISK_GID` to match host permissions (fixes media access issues) - Re-running preflight often resolves permission problems [Configuration Reference](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Configuration-Reference.md)[Transport Compatibility](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Transport-Mode-Compatibility.md)[Tuning Recipes](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Tuning-Recipes.md)[Supported Platforms](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/SUPPORTED_PLATFORMS.md)[Local Profiles](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/LOCAL_PROFILES.md)[Monitoring Guide](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/MONITORING_GUIDE.md) —[Outbound Calling](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/OUTBOUND_CALLING.md)`Alpha` — scheduled campaigns, voicemail drop, consent gate—[FreeSWITCH (FS-PBX) Setup](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/FS-PBX-Setup-Instructions.md)`Community` — community-maintained guide—[ViciDial Setup](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Vicidial-Setup.md)`Community` — community-tested configuration notes `Alpha` = usable but still hardening. `Community` = contributed and community-validated, not maintainer-tested on every release. Features without a label are stable. - What's next, planned milestones, and how to get involved[Roadmap](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/ROADMAP.md)[Developer Documentation](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/README.md)[Architecture Deep Dive](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/architecture-deep-dive.md)[Contributing Guide](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CONTRIBUTING.md)- Completed milestones 1-24[Milestone History](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/MILESTONE_HISTORY.md) **You don't need to be a developer to contribute.** File feature ideas, report bugs with logs attached, improve documentation, or share your dialplan recipes — these are as valuable as code. If you do want to write code, see the Contributing Guide below. ``` git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git cd AVA-AI-Voice-Agent-for-Asterisk ``` Then load ** AVA.mdc** into your AI coding assistant (Claude, Cursor, Windsurf, Codex, Copilot, …) — it carries the project map, engineering guardrails, and contribution workflow — and tell it what you want to build or fix. | Guide | For | |---|---| | Full contribution guidelines and workflow | | Dev environment setup in ~15 minutes | | Code standards for all contributions | | What to work on next | | Area | Guide | Reference | |---|---|---| | Full-Agent Provider | | [Implementation deep-dives](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/references)[Pipeline Development](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/pipeline-development.md)[Example pipelines](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/examples/pipelines)[Tool Development](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/tool-development.md)[Tool Calling Guide](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/TOOL_CALLING_GUIDE.md)[Developer Onboarding](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/DEVELOPER_ONBOARDING.md)- Project overview and first tasks[Developer Quickstart](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/quickstart.md)- Set up your dev environment[Developer Documentation](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/README.md)- Full contributor docs hkjarral | Architecture, Code **Abhishek** Telnyx LLM Provider **turgutguvercin** NumPy Resampler **Scarjit** Code **egorky** Azure STT/TTS Provider **alemstrom** Docs — PBX Setup **gcsuri** Code — Google Calendar **octo-patch** MiniMax LLM Provider **neilruaro-camb** CAMB AI TTS Provider **aoi-dev-0411** Transcript Search, Health Badges **exaland** Outbound .ULAW Compatibility **YosefAdPro** Agents API/OpenAPI See [CONTRIBUTORS.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CONTRIBUTORS.md) for the full list — contributions are recognized there, in release notes, and on Discord. - Support and discussions[Discord Server](https://discord.gg/ysg8fphxUe)[GitHub Issues](https://github.com/hkjarral/Asterisk-AI-Voice-Agent/issues)- Bug reports[GitHub Discussions](https://github.com/hkjarral/Asterisk-AI-Voice-Agent/discussions)- General chat This project is licensed under the MIT License. See the [LICENSE](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/LICENSE) file for details. Asterisk AI Voice Agent is **free and open source**. If it's saving you money, consider supporting development: Your support funds: - 🐛 Faster bug fixes and issue responses - ✨ New provider integrations and features - 📚 Better documentation and tutorials If you find this project useful, please also give it a ⭐️!