Asterisk AI语音智能体

Start ai_engine (required for health checks)

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

📊 Requirements

Platform Requirements

Note: ARM64 (Apple Silicon, Raspberry Pi) is not currently supported. See Supported Platforms for the full compatibility matrix.

Minimum System Requirements

Software Requirements

• Docker + Docker Compose v2
• Asterisk 18+ with ARI enabled
• FreePBX (recommended) or vanilla Asterisk

4. Verify Installation

GPU users: If you have an NVIDIA GPU for local AI inference, see docs/LOCAL_ONLY_SETUP.md for the GPU compose overlay (docker-compose.gpu.yml) before building.

```bash

🔧 Advanced Setup (CLI)

For users who prefer the command line or need headless setup.

Option B: Manual Setup

```bash

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.

---

Getting Started

• Docs Index
• FreePBX Integration Guide
• Installation Guide

🔧 Build Something New

🚀 Quick Start

Get the Admin UI running in 2 minutes.

For a complete first successful call walkthrough (dialplan + transport selection + verification), see: - Installation Guide - Transport Compatibility

HTTP Tools (Pre/In/Post-Call) Example

```yaml

📖 Guides

🎥 Demo

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!

Option A: Interactive CLI

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

Configure Asterisk Dialplan

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()

7 Golden Baseline Configurations

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

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

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

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

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

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

7. xAI Grok Voice Agent (Realtime, μ-law Native) - xAI realtime voice with five named voices (eve/ara/rex/sal/leo) or a custom cloned voice; μ-law @ 8 kHz both directions, no resampling (<2s response). - Config: config/ai-agent.golden-grok.yaml - Best for: xAI ecosystem, telephony-native low-latency audio.

Fully Local (Optional)

AVA also supports a Fully Local mode (100% on-premises, no cloud APIs). Three topologies are supported:

GPU setup uses docker-compose.gpu.yml overlay with CUDA-enabled llama.cpp. Community-validated: RTX 4090 achieves ~1.0s E2E.

• See: docs/LOCAL_ONLY_SETUP.md (canonical guide for all local topologies)
• Hardware guidance: docs/HARDWARE_REQUIREMENTS.md

⚙ Configuration

Three-File Configuration

• config/ai-agent.yaml - Golden baseline configs (git-tracked, upstream-managed).
• config/ai-agent.local.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.
• .env - Secrets and API keys (git-ignored).

Example .env:

OPENAI_API_KEY=sk-your-key-here
DEEPGRAM_API_KEY=your-key-here
ASTERISK_ARI_USERNAME=asterisk
ASTERISK_ARI_PASSWORD=your-password

Optional: Metrics (Bring Your Own Prometheus)

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.

---

Configuration & Operations

• Configuration Reference
• Transport Compatibility
• Tuning Recipes
• Supported Platforms
• Local Profiles
• Monitoring Guide

🏠 Self-Hosted LLM with Ollama (No API Key Required)

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

```yaml

🩺 Agent CLI Tools

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

---

Email Integration

• Automatic Call Summaries: Admins receive full transcripts and metadata.
• Caller-Requested Transcripts: "Email me a transcript of this call."