google-workspace-tools

Google Workspace tools for Vercel AI SDK. Provides tool definitions that AI agents can use to interact with Google Workspace APIs.

Currently supports Gmail and Google Calendar.

Install

npm install google-workspace-tools

ai (Vercel AI SDK v6+) is a peer dependency — your project must already have it installed.

Usage

All Gmail tools at once

import { createGmailTools } from 'google-workspace-tools/gmail';

const tools = createGmailTools({ accessToken: '...' });
// tools.searchEmails, tools.getEmail, tools.sendEmail, etc.

Individual tools

import { createGmailClient, createSearchEmailsTool, createGetEmailTool } from 'google-workspace-tools/gmail';

const gmail = createGmailClient({ accessToken: '...' });
const tools = {
  searchEmails: createSearchEmailsTool(gmail),
  getEmail: createGetEmailTool(gmail),
};

Auth

createGmailClient (and createGmailTools) accept a GmailAuthConfig:

| Field | Required | Description | |-------|----------|-------------| | accessToken | Yes | OAuth2 access token with Gmail scopes | | refreshToken | No | Refresh token for automatic token renewal | | clientId | No | OAuth2 client ID (needed for refresh) | | clientSecret | No | OAuth2 client secret (needed for refresh) |

Available Tools

| Tool | Description | |------|-------------| | searchEmails | Search messages using Gmail query syntax | | getEmail | Get full content of a message by ID | | getThread | Get all messages in a thread | | sendEmail | Send a new email | | replyToEmail | Reply to an existing message (auto-threads) | | draftEmail | Create a draft email | | listLabels | List all Gmail labels | | modifyLabels | Add or remove labels on a message | | trashEmail | Move a message to trash |

Calendar

All Calendar tools at once

import { createCalendarTools } from 'google-workspace-tools/calendar';

const tools = createCalendarTools({ accessToken: '...' });
// tools.listCalendars, tools.listEvents, tools.getEvent, etc.

Individual tools

import { createCalendarClient, createListEventsTool, createGetEventTool } from 'google-workspace-tools/calendar';

const calendar = createCalendarClient({ accessToken: '...' });
const tools = {
  listEvents: createListEventsTool(calendar),
  getEvent: createGetEventTool(calendar),
};

Calendar Auth

createCalendarClient (and createCalendarTools) accept a CalendarAuthConfig:

| Field | Required | Description | |-------|----------|-------------| | accessToken | Yes | OAuth2 access token with Calendar scopes | | refreshToken | No | Refresh token for automatic token renewal | | clientId | No | OAuth2 client ID (needed for refresh) | | clientSecret | No | OAuth2 client secret (needed for refresh) |

Available Calendar Tools

| Tool | Description | |------|-------------| | listCalendars | List all calendars accessible by the user | | listEvents | List events with optional time range and search | | getEvent | Get full details of an event by ID | | createEvent | Create a new calendar event | | updateEvent | Update an existing event (partial update) | | deleteEvent | Delete a calendar event | | findFreeBusy | Query free/busy information for calendars |

Development

Unit tests use Vitest and run directly against the source files. All tools normalize API failures to consistent, operation-specific error messages.

pnpm test
pnpm typecheck
pnpm build

License

MIT