> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/tools/google_calendar.md).

# google\_calendar

[Google Calendar](https://calendar.google.com/) is Google’s industry-leading scheduling service that simplifies event management, meeting coordination, and task planning. Integrated across the Google ecosystem, it enables users to create, manage, and share events effortlessly.

With Google Calendar, you can:

* **Create and manage events** — Schedule meetings, reminders, and appointments.
* **Send invites** — Automatically notify participants via email or calendar updates.
* **Use natural language** — Quickly create events like *“Team sync tomorrow at 3 PM”*.
* **Manage multiple calendars** — Organize events across different calendars.
* **View and search events** — Quickly locate scheduled activities with advanced filters.

In Agent Forge, the Google Calendar integration allows agents to automate scheduling: creating and retrieving events, inviting attendees, and managing schedules programmatically.\
This makes it ideal for AI-driven workflows such as automated meeting scheduling, task coordination, and availability tracking.

## Setup Instructions

To use Google Calendar tools, you’ll need:

1. A **Google account** with Calendar access.
2. A valid **OAuth access token** for the Google Calendar API (see your integration setup in Agent Forge).
3. The correct **calendar permissions** — if your email lacks edit access to a calendar, event creation may fail.

{% hint style="info" %}
**Note:**\
Sometimes, you may encounter an error when creating or editing events — especially if your Google account does not have permission to modify that specific calendar.\
Ensure that:

* The authenticated account owns or has “Make changes to events” permission for the target calendar.
* The calendar is not read-only (e.g., shared with “View only” access).
* The OAuth token was generated for the correct user.
  {% endhint %}

## Usage Instructions

Once configured, the integration supports:

* Creating and modifying events.
* Listing upcoming or past events.
* Retrieving event details.
* Sending or updating invitations automatically.

Email invitations are sent asynchronously and depend on both the recipient’s Calendar settings and your account’s permissions.

## Tools

### `google_calendar_create`

Create a new event in Google Calendar.

#### Input

| Parameter       | Type   | Required | Description                                                      |
| --------------- | ------ | -------- | ---------------------------------------------------------------- |
| `accessToken`   | string | Yes      | OAuth token for Google Calendar API                              |
| `calendarId`    | string | No       | Calendar ID (defaults to `primary`)                              |
| `summary`       | string | Yes      | Event title                                                      |
| `description`   | string | No       | Event description                                                |
| `location`      | string | No       | Event location                                                   |
| `startDateTime` | string | Yes      | Start time in RFC3339 format (e.g., `2025-06-03T10:00:00-08:00`) |
| `endDateTime`   | string | Yes      | End time in RFC3339 format                                       |
| `timeZone`      | string | No       | Time zone (e.g., `America/Los_Angeles`)                          |
| `attendees`     | array  | No       | Array of attendee email addresses                                |
| `sendUpdates`   | string | No       | How to send updates (`all`, `externalOnly`, or `none`)           |

#### Output

| Parameter  | Type   | Description                |
| ---------- | ------ | -------------------------- |
| `content`  | string | Operation response content |
| `metadata` | json   | Event metadata             |

### `google_calendar_list`

List events from a Google Calendar.

#### Input

| Parameter     | Type    | Required | Description                         |
| ------------- | ------- | -------- | ----------------------------------- |
| `accessToken` | string  | Yes      | OAuth token                         |
| `calendarId`  | string  | No       | Calendar ID (defaults to `primary`) |
| `timeMin`     | string  | No       | Start boundary (RFC3339 timestamp)  |
| `timeMax`     | string  | No       | End boundary (RFC3339 timestamp)    |
| `orderBy`     | string  | No       | Sort order (`startTime`, `updated`) |
| `showDeleted` | boolean | No       | Include deleted events              |

#### Output

| Parameter  | Type   | Description                |
| ---------- | ------ | -------------------------- |
| `content`  | string | Operation response content |
| `metadata` | json   | Event metadata             |

#### Screenshot

### `google_calendar_get`

Retrieve details of a specific event.

#### Input

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `accessToken` | string | Yes      | OAuth token                         |
| `calendarId`  | string | No       | Calendar ID (defaults to `primary`) |
| `eventId`     | string | Yes      | ID of the event                     |

#### Output

| Parameter  | Type   | Description    |
| ---------- | ------ | -------------- |
| `content`  | string | Event data     |
| `metadata` | json   | Event metadata |

#### Screenshot

### `google_calendar_quick_add`

Create events using natural language text.

#### Input

| Parameter     | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `accessToken` | string | Yes      | OAuth token                                        |
| `calendarId`  | string | No       | Calendar ID (defaults to `primary`)                |
| `text`        | string | Yes      | Text such as “Lunch with Sarah at noon tomorrow”   |
| `attendees`   | array  | No       | Array or comma-separated string of attendee emails |
| `sendUpdates` | string | No       | Update mode (`all`, `externalOnly`, or `none`)     |

#### Output

| Parameter  | Type   | Description            |
| ---------- | ------ | ---------------------- |
| `content`  | string | Response text          |
| `metadata` | json   | Created event metadata |

#### Screenshot

### `google_calendar_invite`

Add or update attendees for an existing event.

#### Input

| Parameter         | Type    | Required | Description                                    |
| ----------------- | ------- | -------- | ---------------------------------------------- |
| `accessToken`     | string  | Yes      | OAuth token                                    |
| `calendarId`      | string  | No       | Calendar ID (defaults to `primary`)            |
| `eventId`         | string  | Yes      | Event ID                                       |
| `attendees`       | array   | Yes      | Array of emails to invite                      |
| `sendUpdates`     | string  | No       | Update mode (`all`, `externalOnly`, or `none`) |
| `replaceExisting` | boolean | No       | Replace existing attendees (default `false`)   |

#### Output

| Parameter  | Type   | Description                |
| ---------- | ------ | -------------------------- |
| `content`  | string | Operation response content |
| `metadata` | json   | Updated event metadata     |

{% hint style="warning" %}
**Tip:**\
If event creation fails with a `403` or “Insufficient permissions” error, check whether:

* You are authenticated with the correct Google account.
* The calendar belongs to a shared workspace or organization requiring elevated access.
* The target calendar allows programmatic edits via API.
  {% endhint %}

## Notes

* **Category:** `tools`
* **Type:** `google_calendar`
* Requires OAuth access with appropriate scopes (`https://www.googleapis.com/auth/calendar`).
* Event creation or editing might fail if your account does not have sufficient calendar permissions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://whitepaper.aitech.io/agentforge/tools/google_calendar.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.