Overview
The Calendar Assistant is a powerful calendar management tool built using the Agno framework that helps users schedule, manage, and organize their appointments through Cal.com integration. It provides natural language interaction for all calendar operations with automatic timezone handling.
Features
Find Available Slots
Query available time slots between specific dates
Create Bookings
Schedule new appointments with ease
Manage Bookings
View and manage existing appointments
Reschedule
Update appointment times seamlessly
Cancel Bookings
Cancel appointments when needed
Timezone Support
Automatic timezone handling for all operations
Prerequisites
Cal.com Account
Create an account at Cal.com with API access
Nebius API Key
Get your API key from Nebius
Installation
Getting API Credentials
Cal.com API Key
Cal.com API Key
- Go to cal.com/settings/developer/api-keys
- Click “Create New API Key”
- Copy the generated key
- Add it to your
.envfile asCALCOM_API_KEY
Event Type ID
Event Type ID
- Go to your Cal.com event types settings
- Select the event type you want to use
- Copy the Event Type ID from the URL or settings
- Add it to your
.envfile asCALCOM_EVENT_TYPE_ID
Nebius API Key
Nebius API Key
- Visit Nebius Token Factory
- Sign up or log in
- Generate a new API key
- Add it to your
.envfile asNEBIUS_API_KEY
Implementation
Agent Configuration
The calendar assistant is built using Agno with Cal.com integration:Example Booking Flow
Usage
The calendar assistant can help you with various scheduling tasks:Check Available Slots
Query available time slots between specific dates:Dates must be in YYYY-MM-DD format
Create Bookings
Book appointments with specific details:Manage Existing Bookings
View, reschedule, or cancel bookings:Date & Time Formats
The assistant uses specific formats for dates and times:| Format | Example | Usage |
|---|---|---|
| Date | 2024-03-22 | For querying available slots |
| DateTime | 2024-03-22T21:30:00+05:30 | For creating bookings |
| Timezone | +05:30 | Offset from UTC |
Timezone Support
The assistant automatically handles timezone conversions. The default timezone is set to “Asia/Kolkata” but can be modified:Common Timezone Formats
Common Timezone Formats
America/New_York- Eastern Time (US)America/Los_Angeles- Pacific Time (US)Europe/London- GMT/BSTAsia/Kolkata- Indian Standard TimeAsia/Tokyo- Japan Standard TimeAustralia/Sydney- Australian Eastern Time
Available Operations
get_available_slots
Parameters:
start_date: Start date (YYYY-MM-DD)end_date: End date (YYYY-MM-DD)
create_booking
Parameters:
start_time: Start time (YYYY-MM-DDTHH:MM:SS+TZ)name: Attendee nameemail: Attendee email
get_upcoming_bookings
Parameters:
email: User email
reschedule_booking
Parameters:
booking_uid: Unique booking IDnew_start_time: New start timereason: Reason for rescheduling
cancel_booking
Parameters:
booking_uid: Unique booking IDreason: Cancellation reason
Error Handling
The application includes comprehensive error handling:Missing API Keys
Missing API Keys
The application will exit with an error message if required API keys are not set in the environment.
Invalid Date Formats
Invalid Date Formats
The agent will prompt for correct date format if an invalid format is provided.
Booking Conflicts
Booking Conflicts
The agent will check for conflicts and suggest alternative time slots.
API Connection Issues
API Connection Issues
Network errors are caught and displayed to the user with helpful messages.
Best Practices
Always Check Availability
Check available slots before attempting to create a booking
Verify Bookings
Use get_upcoming_bookings to verify successful booking creation
Include Reasons
Provide clear reasons when rescheduling or canceling
Confirm Details
Always confirm booking details with users before making changes
Troubleshooting
Next Steps
Cal.com Docs
Explore Cal.com API documentation
Agno Framework
Learn more about Agno
Advanced Features
Add recurring bookings and reminders
Multi-calendar
Integrate multiple calendar services