Google Calendar

​

Prerequisites

​

Install dependencies

uv pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

​

Setup Google Project and OAuth

1. Enable Google Calendar API
   • Go to Google Cloud Console.
   • Select Project and Enable.
2. Go To API & Service -> OAuth Consent Screen
3. Select User Type
   • If you are a Google Workspace user, select Internal.
   • Otherwise, select External.
4. Fill in the app details (App name, logo, support email, etc).
5. Select Scope
   • Click on Add or Remove Scope.
   • Search for Google Calendar API (Make sure you’ve enabled Google Calendar API otherwise scopes won’t be visible).
   • Select scopes accordingly
     • For read-only access: Select /auth/calendar.readonly
     • For full access: Select /auth/calendar
   • Save and continue.
6. Adding Test User
   • Click Add Users and enter the email addresses of the users you want to allow during testing.
   • NOTE : Only these users can access the app’s OAuth functionality when the app is in “Testing” mode. Any other users will receive access denied errors.
   • To make the app available to all users, you’ll need to move the app’s status to “In Production”. Before doing so, ensure the app is fully verified by Google if it uses sensitive or restricted scopes.
   • Click on Go back to Dashboard.
7. Generate OAuth 2.0 Client ID
   • Go to Credentials.
   • Click on Create Credentials -> OAuth Client ID
   • Select Application Type as Desktop app.
   • Download JSON.
8. Using Google Calendar Tool
   • Pass the path of downloaded credentials as credentials_path to Google Calendar tool.
   • Optional: Set the token_path parameter to specify where the tool should create the token.json file.
   • The token.json file is used to store the user’s access and refresh tokens and is automatically created during the authorization flow if it doesn’t already exist.
   • If token_path is not explicitly provided, the file will be created in the default location which is your current working directory.
   • If you choose to specify token_path, please ensure that the directory you provide has write access, as the application needs to create or update this file during the authentication process.

​

Service Account Authentication (Alternative)

1. Create a service account at IAM & Admin > Service Accounts in Google Cloud Console
2. Download the JSON key file
3. For accessing another user’s calendar, configure domain-wide delegation in Google Workspace Admin Console
4. Set environment variables:

export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service-account-key.json
export GOOGLE_DELEGATED_USER=user@yourdomain.com  # Optional for Calendar

​

Example

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.google.calendar import GoogleCalendarTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[GoogleCalendarTools()],
    add_datetime_to_context=True,
    markdown=True,
)

agent.print_response("What meetings do I have tomorrow?", stream=True)

​

Quick Start Example

# Minimal example with OAuth
from agno.agent import Agent
from agno.tools.google.calendar import GoogleCalendarTools

# OAuth authentication (browser-based)
agent = Agent(
    tools=[GoogleCalendarTools(
        credentials_path="path/to/credentials.json"
    )],
    instructions=["You help users manage their Google Calendar."],
)

# Service account authentication (no browser needed)
agent = Agent(
    tools=[GoogleCalendarTools(
        service_account_path="path/to/service-account.json",
        delegated_user="user@domain.com"  # Optional
    )],
)

​

Toolkit Params

​

Toolkit Functions

​

Reading Events

​

Scheduling & Availability

​

Creating & Managing Events

​

Cookbook Examples

​

Tips for Using Google Calendar Tools

1. Date/Time Formats: All dates use ISO format (YYYY-MM-DDTHH:MM:SS). Always specify timezone when creating events.
2. Working with Attendees: Use check_availability before scheduling meetings with multiple people to find suitable times.
3. Natural Language Events: Use quick_add_event for simple event creation from natural language descriptions.
4. Event Search: Use search_events for full-text search across event titles, descriptions, locations, and attendees.
5. Authentication:
   • Use OAuth for user-facing applications (requires browser)
   • Use service accounts for server/bot deployments (no browser needed)
6. Calendar IDs: Use “primary” for the user’s main calendar, or get specific calendar IDs using list_calendars.

​

Developer Resources

• Source Code
• Cookbook Examples