Show HN: Self-hosted voice AI agent for Asterisk/FreePBX

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🎉 What's New🌟 Why Asterisk AI Voice Agent?✨ Features🎥 Demo🛠️ AI-Powered Actions🩺 Agent CLI Tools⚙️ Configuration🏗️ Project Architecture📊 Requirements🗺️ Documentation🤝 Contributing💬 Community📝 License

Get the Admin UI running in 2 minutes.

For a complete first successful call walkthrough (dialplan + transport selection + verification), see:

git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd AVA-AI-Voice-Agent-for-Asterisk

sudo ./preflight.sh --apply-fixes

Important:Preflight creates your.env

file and generates a secureJWT_SECRET

. Always run this first!

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://<server-ip>: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.

docker compose -p asterisk-ai-voice-agent up -d --build ai_engine

curl http://localhost:15000/health

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

, andagent demo

remain as hidden compatibility aliases. New workflows should use the visible commands documented in[.]docs/CLI_TOOLS_GUIDE.md

cp .env.example .env

docker compose -p asterisk-ai-voice-agent up -d

Add this to your FreePBX (extensions_custom.conf

):

[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 unlessAI_PROVIDER

is intentionally set as a per-call override. - Generate a current snippet with agent dialplan --agent <slug>

. - 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 xAIforce_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.

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 andhangup_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, ElevenLabs setup, and the full v7.3.1 changelog.

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 thedefault 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.

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

andlocal_ai_server

push their own readiness to the Admin UI (POST /api/live-status/publish

, authenticated withLIVE_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) andLIVE_STATUS_INITIAL_PROBE_TIMEOUT_SECONDS

(default 2 s), read live from.env

.

Full notes in 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 "…".No more " 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. Debugconsole.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 canonicalgoogle_live: { type: full }

provider can be edited and saved again.

Full notes in 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 existingAI_AGENT

dialplan variableAI_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 moreadmin

/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 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 insrc/config.py

now default toapi_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), andgpt-realtime-mini

(cost-optimized) — alongside the existinggpt-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 whenapi_version: beta

is detected in config (exactly once per provider lifetime, not per reconnect attempt).Docs: full rewrite ofdocs/Provider-OpenAI-Setup.md

model section + fix todocs/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

(wasbeta

)model: gpt-realtime

(wasgpt-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, 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 YAMLextra_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

• Run multiple instances of the same full-agent provider type with isolated credentials (e.g. acme_google_live

+globex_google_live

both usingtype: google_live

) - Per-instance credential files at /app/project/secrets/providers/<provider_key>/{api-key,agent-id,vertex-json}

— the new per-provider Vertex upload path does NOT mutate.env

• Route via AI_PROVIDER

channel var,contexts.<name>.provider:

YAML, or DID-based dispatch with AsteriskGosub

• Setup guide: docs/Multi-Instance-Full-Agent-Providers.md Breaking for multi-instance setups: short aliasesAI_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 up 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-sideaudioop.ulaw2lin

WAV wrapping — no transcode dependency - Uppercase .WAV

, compressed WAV, and.gsm

recordings transcode viasox

;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 toAAVA_HTTP_TOOL_TEST_*

take effect without a container restart (#370)

For older releases, expand Previous Versions below. Full release notes in 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-contexttool_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).🎙️ 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 configureproviders.minimax_llm

inconfig/ai-agent.yaml

(see theminimax_llm

section withenabled: 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 - Hardware guidance: docs/HARDWARE_REQUIREMENTS.md

Run your own local LLM using Ollama - perfect for privacy-focused deployments:

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.mdfor 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 inconfig/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**: Separateai_engine

andlocal_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

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

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 <ip> # Verify local AI server on a remote GPU machine
agent update              # Pull latest code + rebuild/restart as needed
agent rca --call <call_id> --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

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 ReferenceTransport CompatibilityTuning RecipesSupported PlatformsLocal ProfilesMonitoring Guide

—Outbound CallingAlpha

— scheduled campaigns, voicemail drop, consent gate—FreeSWITCH (FS-PBX) SetupCommunity

— community-maintained guide—ViciDial SetupCommunity

— 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 involvedRoadmapDeveloper DocumentationArchitecture Deep DiveContributing Guide- Completed milestones 1-24Milestone History

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-divesPipeline DevelopmentExample pipelinesTool DevelopmentTool Calling GuideDeveloper Onboarding- Project overview and first tasksDeveloper Quickstart- Set up your dev environmentDeveloper Documentation- 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 for the full list — contributions are recognized there, in release notes, and on Discord.

• Support and discussionsDiscord ServerGitHub Issues- Bug reportsGitHub Discussions- General chat

This project is licensed under the MIT License. See the 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 ⭐️!

source & further reading

github.com — original article