Voice AI Agent for Appointment Booking

An automated Voice AI agent handles appointment scheduling over the phone, checks real-time availability against a clinic calendar, confirms the booking only after explicit patient agreement, and delivers booking reference IDs.

What it does

Greets the caller and gathers patient name, phone number, preferred date/time, and appointment type
Respects all information given upfront in a single utterance (never re-asking details already provided)
Queries open slots from the calendar in real-time (never inventing availability)
Confirms details explicitly before writing to the calendar
Reads back the confirmed booking reference ID over the phone
Optionally delivers an instant Telegram confirmation with event IDs
Delivers a polite goodbye and disconnects cleanly

This sample

Amy at HealthFirst Clinic on AgentDuet with Gemini Live and Google Calendar (or an in-memory calendar backend). Optional Telegram confirmation. Full source: agentduet-samples / appointment-booking.

State flow: NEW → LIVE (answer()) → Gemini Live bidirectional scheduling loop → disconnect() / close()

Prerequisites

Python 3.12+
Get an API key and connector UUID at agentduet.com
Google Gemini API key (Google AI Studio, Gemini Live)
Optional: Google Calendar API service-account JSON (Google Cloud Console)
Optional: Telegram bot token and chat ID for confirmation messages

Tutorial

Step 1: Clone the sample

$ git clone https://github.com/AgentDuet/agentduet-samples.git
$ cd agentduet-samples/use-cases/appointment-booking

Step 2: Install

$ python3.12 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt

Step 3: Configure `.env`

$ cp .env.example .env

AGENTDUET_API_KEY=your-connector-api-key
AGENTDUET_CONNECTOR_UUID=your-connector-uuid
GEMINI_API_KEY=your-gemini-key
# Google Calendar (skip these to use the in-memory demo calendar)
GOOGLE_CALENDAR_CREDENTIALS=./calendar-service-account.json
GOOGLE_CALENDAR_ID=primary
BUSINESS_TZ=UTC
# Optional confirmation
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

Share the target calendar with the service account email (Make changes to events).

Step 4: Run

$ python main.py

Step 5: Place a call and test

Call your connector number. Amy should greet as HealthFirst. Try:

Caller says	Expected
“Hi, I’m Claudia from HealthFirst. General checkup tomorrow at 10 AM. My number is +65 XXXXXXXX.”	Acknowledge; check slots; confirm details; book
“Hi, I’m Joy. Specialist next Monday at 2 PM, +65 XXXXXXXX.”	Fill only missing pieces; confirm before book
“I’m Alex - book me something this week.”	Ask for appointment type / time / phone (+65 XXXXXXXX)

After a successful booking, Amy reads back the booking ID and concludes the call. If Telegram is configured, the booking confirmation arrives in chat.

How it works

Gemini Live streams PCM audio bidirectionally over WebSockets. Structured tool calls handle calendar operations and call lifecycle. When a slot is confirmed, the calendar backend writes the appointment and returns a verified booking ID. Once the booking is read back and acknowledged, the agent speaks its closing greeting and disconnects cleanly.

Key APIs

Piece	Role
Gemini Live	Real-time speech reasoning and structured tool execution
Google Calendar API	Source of truth for slot availability and booking persistence
`call.caller.audio_stream()`	Captures caller microphone audio
`call.send_audio(chunk)`	Delivers synthesized agent voice
`call.clear_send_audio_buffer()`	Zero-latency barge-in handling
`call.disconnect()`	Clean call hangup upon booking completion