> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar

> List, create, get, and delete Google Calendar events.

# Google Calendar

List, create, get, and delete events on Google Calendar. Uses the same OAuth2 pattern as the Gmail toolkit.

<Info>
  Requires: `npm install googleapis`
</Info>

***

## Quick Start

```typescript theme={null}
import { Agent, openai, GoogleCalendarToolkit } from "@agentium/core";

const calendar = new GoogleCalendarToolkit({
  credentialsPath: "./credentials.json",
  tokenPath: "./token.json",
});

const agent = new Agent({
  name: "scheduler",
  model: openai("gpt-4o"),
  instructions: "Help manage the user's calendar. Schedule and look up events.",
  tools: [...calendar.getTools()],
});

const result = await agent.run("What meetings do I have today?");
```

***

## Config

<ParamField body="credentialsPath" type="string">
  Path to OAuth2 credentials JSON. Falls back to `GOOGLE_CALENDAR_CREDENTIALS_PATH` env var.
</ParamField>

<ParamField body="tokenPath" type="string">
  Path to saved token JSON. Falls back to `GOOGLE_CALENDAR_TOKEN_PATH` env var.
</ParamField>

<ParamField body="authClient" type="any">
  Pre-authenticated OAuth2 client (if you handle auth yourself).
</ParamField>

<ParamField body="calendarId" type="string" default="primary">
  Calendar ID to operate on.
</ParamField>

***

## Tools

| Tool                    | Description                                                                |
| ----------------------- | -------------------------------------------------------------------------- |
| `calendar_list_events`  | List upcoming events. Supports time range filters.                         |
| `calendar_create_event` | Create a new event with title, time, location, description, and attendees. |
| `calendar_get_event`    | Get details of a specific event by ID.                                     |
| `calendar_delete_event` | Delete an event by ID.                                                     |

***

## Environment Variables

```bash theme={null}
export GOOGLE_CALENDAR_CREDENTIALS_PATH="./credentials.json"
export GOOGLE_CALENDAR_TOKEN_PATH="./token.json"
```

See the [Gmail toolkit setup guide](/toolkits/gmail) for OAuth2 credential instructions — the process is identical.

***

## Tool Usage Examples

### List Today's Events

```typescript theme={null}
const result = await agent.run("What meetings do I have today?");

// The agent calls calendar_list_events with:
// { timeMin: "2026-02-26T00:00:00Z", timeMax: "2026-02-26T23:59:59Z" }
//
// Response:
// "You have 3 meetings today:
//  - 10:00 AM — Sprint Planning (Conference Room A)
//  - 1:00 PM — 1:1 with Manager (Zoom)
//  - 3:30 PM — Design Review (Conference Room B)"
```

### Create Event

```typescript theme={null}
const result = await agent.run(
  "Schedule a 30-minute meeting with sarah@company.com tomorrow at 2 PM " +
  "titled 'Quick Sync'. Add a Zoom link in the description."
);

// The agent calls calendar_create_event with:
// {
//   summary: "Quick Sync",
//   start: { dateTime: "2026-02-27T14:00:00+05:30" },
//   end: { dateTime: "2026-02-27T14:30:00+05:30" },
//   attendees: [{ email: "sarah@company.com" }],
//   description: "Join via Zoom: https://..."
// }
```

### Check Availability

```typescript theme={null}
const result = await agent.run("Am I free next Monday afternoon?");

// The agent calls calendar_list_events for Monday's time range
// and reports availability gaps
```