Google Calendar

Enable Agno agents to list, create, update, and delete Google Calendar events and find free time slots.

Prerequisites

Enable the Calendar API and create a Desktop OAuth client using the Google Calendar Python quickstart. Save the downloaded client JSON as credentials.json in the directory where you run Python, or pass its path through credentials_path. The toolkit creates token.json after consent; this is the reusable user token, not the client-credentials file.

from agno.agent import Agent
from agno.tools.google.calendar import GoogleCalendarTools

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------


agent = Agent(
    tools=[
        GoogleCalendarTools(
            # credentials_path="credentials.json",  # Path to your downloaded OAuth credentials
            # token_path="token.json",  # Path to your downloaded OAuth credentials
            oauth_port=8080,  # port used for oauth authentication
            allow_update=True,
        )
    ],
    instructions=[
        """
    You are a scheduling assistant.
    You should help users to perform these actions in their Google calendar:
        - get their scheduled events from a certain date and time
        - create events based on provided details
        - update existing events
        - delete events
        - find available time slots for scheduling
    """
    ],
    add_datetime_to_context=True,
)

# Example 1: List calendar events

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response("Give me the list of tomorrow's events", markdown=True)

    # Example 2: Create an event
    # agent.print_response(
    #     "create an event tomorrow from 9am to 10am, make the title as 'Team Meeting' and description as 'Weekly team sync'",
    #     markdown=True,
    # )

    # Example 3: Find available time slots
    # agent.print_response(
    #     "Find available 1-hour time slots for tomorrow between 9 AM and 5 PM",
    #     markdown=True,
    # )

    # Example 4: List available calendars
    # agent.print_response(
    #     "List all my calendars",
    #     markdown=True,
    # )

    # Example 5: Update an event
    # agent.print_response(
    #     "update the 'Team Meeting' event to run from 5pm to 7pm and change description to 'Extended team sync'",
    #     markdown=True,
    # )

    # Example 6: Delete an event
    # agent.print_response("delete the 'Team Meeting' event", markdown=True)

    # # Example 7: Find available time slots for a specific calendar
    # agent.print_response(
    #     "Find available 1-hour time slots for this week between 9 AM and 5 PM in the Appointments calendar",
    #     markdown=True,
    # )

    # Example 9: Find available slots using locale-based working hours
    # agent.print_response(
    #     "Find available 60-minute slots for the next 3 days", markdown=True
    # )

The first run lists events, but allow_update=True also exposes create/update/delete tools. Setting it to False does not disable those defaults: use create_event=False, update_event=False, delete_event=False and remove allow_update=True for a reader.

For a different calendar, set its ID with GoogleCalendarTools(calendar_id="..."); a prompt naming “Appointments” does not change this configuration. Use timestamps with offsets and follow result pagination. find_available_slots uses heuristic working hours and ignores all-day events; confirm scheduling candidates with check_availability.

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno google-api-python-client google-auth-httplib2 google-auth-oauthlib openai

Export your OpenAI API key

export OPENAI_API_KEY="your_openai_api_key_here"

Run the example

Save the code above as googlecalendar_tools.py, then run:

python googlecalendar_tools.py

Full source: cookbook/91_tools/googlecalendar_tools.py