CalendarTool

CalendarTool lets your agent read, create, and delete Google Calendar events. It can also find open time slots and add guests to existing events — useful for scheduling assistants and booking workflows.

Installation

Install the Google dependencies:

pip install --pre "agentor[google]"

This installs google-api-python-client and the related auth libraries.

Authentication

CalendarTool requires a Google OAuth2 Credentials object with access to the Google Calendar API. You are responsible for obtaining and refreshing credentials before passing them in.

Create OAuth credentials

Set up an OAuth 2.0 client in the Google Cloud Console. Enable the Google Calendar API for your project and download your client credentials.

Run the OAuth flow

Use google-auth-oauthlib to complete the consent flow and obtain a Credentials object. The example below shows one way to do this.

Pass credentials to CalendarTool

Provide the resulting Credentials object when creating the tool.

Constructor

from agentor.tools import CalendarTool

tool = CalendarTool(credentials=creds)

google.oauth2.credentials.Credentials

required

A valid Google OAuth2 credentials object with the https://www.googleapis.com/auth/calendar scope. Can be loaded from a stored token using Credentials.from_authorized_user_info() or obtained through an OAuth flow.

str

Optional API key for MCP use.

Methods

list_events

List calendar events within a time window. Automatically paginates to fetch all matching events.

@capability
def list_events(
    self,
    start_time: str,
    end_time: str,
    calendar_id: str = "primary",
    limit: int = 20,
    query: Optional[str] = None,
) -> str

str

required

Start of the time window in ISO 8601 format with timezone (e.g., 2025-06-01T09:00:00Z or 2025-06-01T09:00:00+05:30).

str

required

End of the time window in ISO 8601 format with timezone.

str

default:"primary"

Google Calendar ID. Use "primary" for the user’s main calendar.

int

default:"20"

Maximum number of events to return (1–2500).

str

Free-text search query to filter events by title, description, or location.

Returns: A JSON string containing an array of event objects.

create_event

Create a new calendar event.

@capability
def create_event(
    self,
    title: str,
    start_time: str,
    end_time: str,
    calendar_id: str = "primary",
    description: Optional[str] = None,
    location: Optional[str] = None,
) -> str

str

required

Event title (the summary field in Google Calendar).

str

required

Event start time in ISO 8601 format with timezone.

str

required

Event end time in ISO 8601 format with timezone.

str

default:"primary"

Google Calendar ID.

str

Optional event description.

str

Optional event location.

Returns: A JSON string containing the created event object.

find_free_slots

Find available time slots in a calendar within a given window. This checks existing events and returns gaps that are long enough for the requested meeting duration.

@capability
def find_free_slots(
    self,
    start_time: str,
    end_time: str,
    meeting_minutes: int = 30,
    calendar_id: str = "primary",
    limit: int = 10,
) -> str

str

required

Start of the search window in ISO 8601 format with timezone.

str

required

End of the search window in ISO 8601 format with timezone.

int

default:"30"

Minimum duration for a free slot, in minutes. Must be greater than 0.

str

default:"primary"

Google Calendar ID.

int

default:"10"

Maximum number of free slots to return.

Returns: A JSON string containing window_start, window_end, meeting_minutes, and a free_slots array.

delete_event

Delete a calendar event by its ID.

@capability
def delete_event(
    self,
    event_id: str,
    calendar_id: str = "primary",
) -> str

str

required

The Google Calendar event ID to delete.

str

default:"primary"

Google Calendar ID.

Returns: A JSON string with a success status and message.

add_guests

Add guests to an existing calendar event. Duplicate emails are automatically skipped.

@capability
def add_guests(
    self,
    event_id: str,
    guest_emails: list,
    calendar_id: str = "primary",
    send_notifications: bool = True,
) -> str

str

required

The Google Calendar event ID.

list

required

A list of email addresses to add as attendees.

str

default:"primary"

Google Calendar ID.

bool

default:"True"

Whether to send email invitations to the new guests.

Returns: A JSON string with the updated event, including the full attendee list and the count of newly added guests.

Usage

Basic setup

from google.oauth2.credentials import Credentials
from agentor import Agentor
from agentor.tools import CalendarTool

# Load credentials from a saved token
creds = Credentials.from_authorized_user_file("credentials.json")

agent = Agentor(
    name="Calendar Agent",
    model="gpt-4o-mini",
    tools=[CalendarTool(credentials=creds)],
    instructions="Use the calendar tool to help with scheduling.",
)

result = agent.run("What events do I have tomorrow?")
print(result.final_output)

Finding free time

from agentor.tools import CalendarTool

calendar = CalendarTool(credentials=creds)

# Find 60-minute open slots this week
slots = calendar.find_free_slots(
    start_time="2025-06-02T09:00:00Z",
    end_time="2025-06-06T17:00:00Z",
    meeting_minutes=60,
)
print(slots)

Creating an event

result = calendar.create_event(
    title="Team standup",
    start_time="2025-06-03T10:00:00-04:00",
    end_time="2025-06-03T10:30:00-04:00",
    description="Daily sync",
    location="Zoom",
)
print(result)

Full OAuth example

The example below shows a complete flow that handles first-time consent and token refresh. It mirrors the pattern from the Agentor examples folder.

import os
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from agentor import Agentor
from agentor.tools import CalendarTool

SCOPES = ["https://www.googleapis.com/auth/calendar"]
CREDS_FILE = "credentials.json"

def get_credentials():
    """Load saved credentials or run the OAuth consent flow."""
    if os.path.exists(CREDS_FILE):
        creds = Credentials.from_authorized_user_file(CREDS_FILE)
        if creds.valid:
            return creds
        if creds.expired and creds.refresh_token:
            creds.refresh(Request())
            with open(CREDS_FILE, "w") as f:
                f.write(creds.to_json())
            return creds

    flow = InstalledAppFlow.from_client_config(
        {
            "installed": {
                "client_id": os.environ["GOOGLE_CLIENT_ID"],
                "client_secret": os.environ["GOOGLE_CLIENT_SECRET"],
                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
                "token_uri": "https://oauth2.googleapis.com/token",
                "redirect_uris": ["http://localhost:8000"],
            }
        },
        scopes=SCOPES,
    )
    creds = flow.run_local_server(port=8000, access_type="offline", prompt="consent")
    with open(CREDS_FILE, "w") as f:
        f.write(creds.to_json())
    return creds

creds = get_credentials()

agent = Agentor(
    name="Calendar Agent",
    model="gpt-4o-mini",
    tools=[CalendarTool(credentials=creds)],
    instructions="Help with scheduling and event management.",
)

result = agent.run("What events do I have this week?")
print(result.final_output)

Never commit OAuth credentials or token files to version control. Store them securely and add credentials.json to your .gitignore.

Datetime format

All datetime parameters must be in ISO 8601 format with a timezone offset. The tool rejects values without a timezone.

Format	Example
UTC	`2025-06-01T09:00:00Z`
UTC offset	`2025-06-01T14:30:00+05:30`
Negative offset	`2025-06-01T09:00:00-04:00`

Error handling

The tool returns error strings (prefixed with Error:) instead of raising exceptions, so your agent can read and react to issues:

Missing credentials — raises ValueError at construction time
Missing google-api-python-client — raises ImportError at construction time
Invalid datetime — returns Error: Invalid datetime format...
API errors — returns Error: with the underlying exception message

Source reference

src/agentor/tools/google_calendar.py:17

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Installation

Authentication

Constructor

Methods

list_events

create_event

find_free_slots

delete_event

add_guests

Usage

Basic setup

Finding free time

Creating an event

Full OAuth example

Datetime format

Error handling

Source reference

​Installation

​Authentication

​Constructor

​Methods

​list_events

​create_event

​find_free_slots

​delete_event

​add_guests

​Usage

​Basic setup

​Finding free time

​Creating an event

​Full OAuth example

​Datetime format

​Error handling

​Source reference

Installation

Authentication

Constructor

Methods

list_events

create_event

find_free_slots

delete_event

add_guests

Usage

Basic setup

Finding free time

Creating an event

Full OAuth example

Datetime format

Error handling

Source reference