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

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 doctor, and agent troubleshoot remain available as hidden aliases in CLI v6.4.0.

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)
 ; Optional per-call overrides:
 ; - AI_PROVIDER selects a provider/pipeline (otherwise uses default_provider from ai-agent.yaml)
 ; - AI_CONTEXT selects a context/persona (otherwise uses default context)
 same => n,Set(AI_PROVIDER=google_live)
 same => n,Set(AI_CONTEXT=sales-agent)
 same => n,Stasis(asterisk-ai-voice-agent)
 same => n,Hangup()

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

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 at http://<engine-host>:15000/metrics. 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 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> # Post-call RCA (use Call History to find call_id)
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."