Contact Sales

All fields are required

Holy Guacamole: A Voice AI Drive-Thru You Can Actually… | SignalWire
Developers

Holy Guacamole: A Voice AI Drive-Thru You Can Actually Build (and Scale)

Code-powered AI prompting for more reliable applications

Start for free Talk to an Expert

Live demo: https://holyguacamole.signalwire.me

Source code: GitHub repo

How to build better drive-thru voice AI

Fast food drive-thrus are a tough problem for AI systems. You’re dealing with ambient noise, unpredictable phrasing, and complex menu logic. Yet most implementations rely on simple prompt engineering and think that will be good enough.

Holy Guacamole is SignalWire’s example of how to do drive-thru AI correctly. It’s a developer-first reference application built with SignalWire’s Python Agents SDK. The entire interaction is driven by your application logic, not the LLM. That means deterministic behavior, production-grade control, and a significantly better customer experience.

This demo acts as a blueprint for building scalable, voice-first systems using SignalWire’s Call Fabric architecture the correct way, carrying context, managing state, implementing proper guardrails, and planning ahead for business logic failures.

Core features

  • Voice-first interaction using SignalWire's Agents SDK

  • Real-time frontend order display via WebRTC

  • Intelligent menu matching with TF-IDF, aliases, and fallback algorithms

  • Automatic combo detection handled entirely in code

  • Production-grade protections like rate limiting, max value enforcement, and error handling

The backend handles all state transitions, menu matching, and business logic. The AI agent is simply an interface for natural language understanding and response generation, tightly controlled by application logic.

Code-powered AI prompting

Instead of relying on LLMs to remember instructions, the Holy Guacamole model demonstrates a more effective method of prompting: enforcing rules through structured functions.

Traditional approach (unreliable)

prompt = """You are a drive-thru assistant..."""

This relies on the LLM to behave correctly, remember constraints, and apply logic on its own.

Code-driven approach (reliable)


This guarantees predictable outcomes regardless of LLM behavior.

Project setup

The application is written in Python and built on the SignalWire Agents SDK.

git clone https://github.com/signalwire/sigmond-holyguacamole.git
cd sigmond-holyguacamole
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Start the application locally:

python holy_guacamole.py

Instructions for deploying with Dokku or other production environments are in the repository.

State machine overview

Example: Greeting state

The conversation flows through structured states:


Each state includes:

  • Allowed function calls

  • Next valid transitions

  • Defined goals and business rules

Transitions are controlled by the backend, never left to the LLM.

SWAIG functions: Structured interactions

SWAIG functions define all operations the AI agent can invoke. Each is explicitly defined, typed, and safely handled.

Example: add_item


These functions handle validation, pricing, real-time UI updates, and business logic, all outside the LLM’s control.

Menu matching logic

The backend uses a multi-algorithm approach to interpret what users want:

  1. TF-IDF vector similarity for fast matching

  2. Alias mapping for exact matches

  3. Fallback string matching when others fail


The combination allows the system to handle natural phrasing without sacrificing accuracy.

Combo detection

No AI prompt is needed to upsell a combo. Instead, detection happens entirely in code:


The function returns a suggestion that the LLM simply relays. No reasoning or memory required.

Real-time event handling frontend integration

The frontend uses SignalWire Call Fabric Browser SDK for media and user event delivery over WebRTC. Events are handled in JavaScript:


This ensures low-latency UI updates and a smooth ordering experience.

Advanced features

  • Order protection: Limits on total quantity, item types, and maximum order value

  • Natural language totals: Converts prices to spoken words (e.g., “thirteen dollars and fifty cents”)

  • Multi-item parsing: Handles complex inputs like “two tacos and three burritos”

  • Error recovery: Offers suggestions or categories if an item isn’t found

  • Reusable state machine structure

  • Real-time visual feedback via swml_user_event()

Real-time UI updates via events

Event flow:

Customer → AI Agent → Backend Logic → swml_user_event() → Frontend Event Handler → UI Update

Consistent event types like item_added, combo_upgraded, order_completed, etc., ensure frontend sync.

Start building a production-ready, customer-facing voice AI agent

Holy Guacamole is a blueprint for building real-time, voice-controlled AI experiences that are actually maintainable in production. It demonstrates how to:

  • Control the LLM with code

  • Enforce business logic outside the model

  • Use SignalWire’s Programmable Unified Communications platform to power intelligent audio apps

  • Scale deterministic AI logic that works across edge cases

This is production-ready architecture for anyone serious about voice automation.

Ready to build your own? Sign up for a free account, and bring your questions to our community of developers on Discord.

Related Articles