Skip to main content

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. Calendar Assistant

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

1

Python 3.x

Ensure Python 3.x is installed on your system
2

Cal.com Account

Create an account at Cal.com with API access
3

Nebius API Key

Get your API key from Nebius

Installation

1

Clone the Repository

git clone https://github.com/Arindam200/awesome-ai-apps.git
cd awesome-ai-apps/simple_ai_agents/cal_scheduler_agent
2

Install Dependencies

Using pip:
pip install -r requirements.txt
Or using uv (recommended):
uv sync
3

Configure Environment

Create a .env file with your credentials:
CALCOM_API_KEY="your_calcom_api_key"
CALCOM_EVENT_TYPE_ID="your_event_type_id"
NEBIUS_API_KEY="your_nebius_api_key"

Getting API Credentials

  1. Go to cal.com/settings/developer/api-keys
  2. Click “Create New API Key”
  3. Copy the generated key
  4. Add it to your .env file as CALCOM_API_KEY
  1. Go to your Cal.com event types settings
  2. Select the event type you want to use
  3. Copy the Event Type ID from the URL or settings
  4. Add it to your .env file as CALCOM_EVENT_TYPE_ID
  1. Visit Nebius Token Factory
  2. Sign up or log in
  3. Generate a new API key
  4. Add it to your .env file as NEBIUS_API_KEY

Implementation

Agent Configuration

The calendar assistant is built using Agno with Cal.com integration:
from datetime import datetime, timedelta
import os
from agno.agent import Agent
from agno.models.nebius import Nebius
from agno.tools.calcom import CalComTools
from dotenv import load_dotenv

load_dotenv()

INSTRUCTIONS = f"""You're a scheduling assistant. Today is {datetime.now()}.
You can help users by:
    - Finding available time slots using get_available_slots(start_date, end_date)
    - Creating new bookings using create_booking(start_time, name, email)
    - Managing existing bookings using get_upcoming_bookings(email)
    - Rescheduling bookings using reschedule_booking(booking_uid, new_start_time, reason)
    - Cancelling bookings using cancel_booking(booking_uid, reason)

IMPORTANT STEPS for booking:
1. First check available slots using get_available_slots
2. Then create booking using create_booking with the exact start_time, name, and email
3. Finally verify the booking was created using get_upcoming_bookings

Remember:
- Dates should be in YYYY-MM-DD format
- Times should be in YYYY-MM-DDTHH:MM:SS+TZ format
- Always confirm details before making changes
"""

# Create the CalCom tools instance
calcom_tools = CalComTools(
    user_timezone="Asia/Kolkata",
    api_key=os.environ['CALCOM_API_KEY'],
    event_type_id=os.environ.get('CALCOM_EVENT_TYPE_ID')
)

# Create the agent
agent = Agent(
    name="Calendar Assistant",
    instructions=[INSTRUCTIONS],
    model=Nebius(
        id="Qwen/Qwen3-30B-A3B",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    tools=[calcom_tools],
    show_tool_calls=True,
    tool_choice="auto",
    markdown=True,
)

Example Booking Flow

def book_example_call():
    # Get today's date and tomorrow's date
    today = datetime.now().strftime("%Y-%m-%d")
    tomorrow = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d")
    
    # First, check available slots
    print("Checking available slots...")
    agent.print_response(f"""
    Please check available slots between {today} and {tomorrow}
    """)
    
    # Then book a specific slot
    print("\nAttempting to book a call...")
    agent.print_response("""
    Please book a call with these details:
    - Start Time: 2025-03-22T21:30:00+05:30
    - Name: John Doe
    - Email: [email protected]
    
    After booking, please verify the booking exists.
    """)

if __name__ == "__main__":
    book_example_call()

Usage

The calendar assistant can help you with various scheduling tasks:

Check Available Slots

Query available time slots between specific dates:
agent.print_response("""
Please check available slots between 2024-03-20 and 2024-03-21
""")
Dates must be in YYYY-MM-DD format

Create Bookings

Book appointments with specific details:
agent.print_response("""
Please book a call with these details:
- Start Time: 2024-03-22T21:30:00+05:30
- Name: John Doe
- Email: [email protected]
""")
Start time must be in YYYY-MM-DDTHH:MM:SS+TZ format with timezone offset

Manage Existing Bookings

View, reschedule, or cancel bookings:
agent.print_response("""
Show me upcoming bookings for [email protected]
""")

Date & Time Formats

The assistant uses specific formats for dates and times:
FormatExampleUsage
Date2024-03-22For querying available slots
DateTime2024-03-22T21:30:00+05:30For creating bookings
Timezone+05:30Offset from UTC

Timezone Support

The assistant automatically handles timezone conversions. The default timezone is set to “Asia/Kolkata” but can be modified:
calcom_tools = CalComTools(
    user_timezone="America/New_York",  # Change timezone here
    api_key=os.environ['CALCOM_API_KEY'],
    event_type_id=os.environ.get('CALCOM_EVENT_TYPE_ID')
)
  • America/New_York - Eastern Time (US)
  • America/Los_Angeles - Pacific Time (US)
  • Europe/London - GMT/BST
  • Asia/Kolkata - Indian Standard Time
  • Asia/Tokyo - Japan Standard Time
  • Australia/Sydney - Australian Eastern Time

Available Operations

get_available_slots

Parameters:
  • start_date: Start date (YYYY-MM-DD)
  • end_date: End date (YYYY-MM-DD)
Returns: List of available time slots

create_booking

Parameters:
  • start_time: Start time (YYYY-MM-DDTHH:MM:SS+TZ)
  • name: Attendee name
  • email: Attendee email
Returns: Booking confirmation

get_upcoming_bookings

Parameters:
  • email: User email
Returns: List of upcoming bookings

reschedule_booking

Parameters:
  • booking_uid: Unique booking ID
  • new_start_time: New start time
  • reason: Reason for rescheduling
Returns: Updated booking details

cancel_booking

Parameters:
  • booking_uid: Unique booking ID
  • reason: Cancellation reason
Returns: Cancellation confirmation

Error Handling

The application includes comprehensive error handling:
The application will exit with an error message if required API keys are not set in the environment.
The agent will prompt for correct date format if an invalid format is provided.
The agent will check for conflicts and suggest alternative time slots.
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

1

Verify API Keys

Ensure all API keys are correctly set in your .env file
2

Check Date Formats

Verify dates and times follow the required format
3

Test Connection

Test your Cal.com API connection separately
4

Review Timezone

Confirm timezone settings match your location

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

Build docs developers (and LLMs) love