AVA (AI Voice Agent for Asterisk)

Tool calling allows AI agents to perform real-world actions during a conversation instead of only responding with text. This capability enables tasks such as:

• Call Transfers: Moving callers to human agents or specific departments.
• Email Management: Sending call summaries and transcripts via email.
• Graceful Hangups: Ending calls with appropriate farewell messages.

The system is provider-agnostic, meaning tools written for the agent can be used across different AI providers (like OpenAI, Deepgram, or Google Gemini) without code changes. It is designed to be type-safe and easy to extend.

The Admin UI provides several key management capabilities:

• Dashboard: Monitor system health, container status, and metrics.
• Providers: Configure AI providers such as OpenAI, Deepgram, or Local providers.
• Pipelines: Create modular STT→LLM→TTS (Speech-to-Text to Large Language Model to Text-to-Speech) pipelines.
• Contexts: Define conversation contexts and personas.
• Models: Manage local AI models (download/delete).
• Setup Wizard: A guided interface for initial configuration.

Note: Heavy pages like the Wizard, Raw YAML Editor, Terminal, Logs, and Models are lazy-loaded to optimize performance.

The toolkit consists of the following files:

• Makefile.ide: Contains wrapper targets for rapid linting, testing, and container operations.
• README.md: Documentation for the toolkit.

Choose a configuration based on your priority (cost, privacy, or speed):

Recommended Use Cases:

• OpenAI Realtime: Quick deployment, high budget for API costs, 5-50 concurrent calls.
• Deepgram Voice Agent: Deepgram ecosystem users, complex reasoning needs, 5-50 concurrent calls.
• Local Hybrid: Privacy-critical (HIPAA/GDPR), cost-sensitive, 5-20 concurrent calls.

The v7.5.1 hotfix focuses on Admin UI service replacement, Apply-versus-Restart classification, and response-scoped transcripts for OpenAI Realtime and Grok assistants.

Important Constraints:

• This hotfix does not change audio profiles, provider media transports, resampling, or fresh-install defaults.
• It does not require database migrations or audio-profile migrations.
• It does not change encoding, VAD, or provider-default paths.
• Existing audio-profile assignments and historical Call History rows are preserved and not rewritten during updates.

The project is optimized for Linux hosts that either run Asterisk/FreePBX locally or can reach an Asterisk/FreePBX host over the network.

Important: macOS and Windows are considered development-only environments and are not targeted as production hosts for Asterisk. ARM-based hosts are considered Tier 3 (best-effort) and are intended for testing only.

Baseline Requirements

To run the project, you must meet these minimum requirements:

• Docker + Docker Compose v2
• x86_64 Linux host (for Tier 1/2 support)
• Asterisk ARI must be reachable with credentials configured in your .env file.

The microsoft_calendar tool enables an AI voice agent to interact with Outlook calendars via Microsoft Graph. It supports listing events, finding free appointment slots, creating bookings, and deleting bookings.

Key V1 Characteristics

• Authentication: Uses device-code OAuth. This means no redirect URLs, client secrets, or public HTTPS endpoints are required. The operator authorizes the app by visiting microsoft.com/devicelogin and entering a code provided in the Admin UI.
• Account Support: Supports Microsoft 365 work or school accounts (single-tenant Entra ID).
• Unsupported: Personal Outlook.com accounts are NOT supported in V1.
• Permissions: Uses delegated permissions, meaning the tool acts on behalf of the signed-in user.
• Multi-account: V1 supports only one connected account per deployment (accounts.default).

When the system detects docker.mode == "rootless", the following logic applies to system actions and suggestions:

1. Permissions: Omit usermod -aG docker suggestions.
2. Service Management: Use systemctl --user start docker instead of sudo systemctl start docker.
3. Paths: Suggest user-writable paths (e.g., ~/aava-media) instead of system paths like /mnt/....
4. Low Ports: If using ports < 1024, you must enable unprivileged ports via sysctl: sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0

Each Golden Baseline documentation file follows a standardized format to ensure you have all the information needed for deployment. When reviewing a case study, expect to find:

• Validated production configuration: Settings that have been tested in real-world scenarios.
• Performance metrics: Validation results such as response latency.
• Critical settings: Explanations of specific parameters and their impact on the agent.
• Complete YAML configuration: The full configuration files required to implement the baseline.
• Lessons learned and troubleshooting: Practical insights and common issues encountered during deployment.
• Deployment recommendations: Guidance on how to roll out the specific configuration.