Google Workspace

Connect your agents to Google Workspace for Gmail, Drive, Calendar, Docs, and Sheets access.

Available Tools

Gmail

Tool	Description
`gmail_search`	Search emails by query
`gmail_read`	Read email content
`gmail_send`	Send new email
`gmail_reply`	Reply to email
`gmail_forward`	Forward email
`gmail_label`	Apply labels
`gmail_archive`	Archive emails
`gmail_delete`	Delete emails

Google Drive

Tool	Description
`drive_list`	List files and folders
`drive_search`	Search files
`drive_read`	Read file content
`drive_create`	Create new file
`drive_update`	Update file content
`drive_share`	Share file with users
`drive_move`	Move file to folder
`drive_delete`	Delete file

Google Calendar

Tool	Description
`calendar_list`	List calendars
`calendar_events`	List events
`calendar_create`	Create event
`calendar_update`	Update event
`calendar_delete`	Delete event
`calendar_availability`	Check availability

Google Docs

Tool	Description
`docs_read`	Read document content
`docs_create`	Create new document
`docs_update`	Update document
`docs_append`	Append to document

Google Sheets

Tool	Description
`sheets_read`	Read spreadsheet data
`sheets_write`	Write to cells
`sheets_append`	Append rows
`sheets_create`	Create spreadsheet

Connecting

Required Scopes

Select scopes based on what you need:

// Read-only access
scopes: [
  'gmail.readonly',
  'drive.readonly',
  'calendar.readonly'
]

// Full access
scopes: [
  'gmail.modify',
  'drive',
  'calendar',
  'documents',
  'spreadsheets'
]

OAuth Setup

const connection = await client.integrations.connect({
  integrationId: 'google-workspace',
  scopes: ['gmail.modify', 'drive', 'calendar'],
  redirectUrl: 'https://your-app.com/oauth/callback'
});

// Redirect user
window.location.href = connection.authUrl;

Service Account (Admin)

For admin operations without user interaction:

await client.integrations.connectServiceAccount({
  integrationId: 'google-workspace',
  credentials: {
    type: 'service_account',
    project_id: 'your-project',
    private_key: process.env.GOOGLE_PRIVATE_KEY,
    client_email: 'service@your-project.iam.gserviceaccount.com'
  },
  adminEmail: 'admin@your-domain.com', // For domain-wide delegation
  scopes: ['admin.directory.user', 'admin.directory.group']
});

Tool Examples

Gmail Search

// In agent system prompt or tool call
const emails = await tools.gmail_search({
  query: 'from:support@company.com is:unread',
  maxResults: 10
});

// Returns
{
  messages: [
    {
      id: 'msg-123',
      threadId: 'thread-456',
      from: 'support@company.com',
      to: 'user@example.com',
      subject: 'Your ticket #1234',
      snippet: 'We have received your request...',
      date: '2024-01-15T10:30:00Z',
      labels: ['INBOX', 'UNREAD']
    }
  ],
  resultCount: 10,
  nextPageToken: 'token...'
}

Gmail Send

const result = await tools.gmail_send({
  to: 'customer@example.com',
  cc: 'team@company.com',
  subject: 'Re: Your inquiry',
  body: 'Thank you for reaching out...',
  isHtml: false
});

// Returns
{
  success: true,
  messageId: 'msg-789',
  threadId: 'thread-456'
}

Drive Search

const files = await tools.drive_search({
  query: 'type:spreadsheet name:Q4 Budget',
  maxResults: 5
});

// Returns
{
  files: [
    {
      id: 'file-123',
      name: 'Q4 Budget 2024.xlsx',
      mimeType: 'application/vnd.google-apps.spreadsheet',
      createdTime: '2024-01-01T00:00:00Z',
      modifiedTime: '2024-01-15T10:00:00Z',
      owners: [{ email: 'finance@company.com' }],
      webViewLink: 'https://docs.google.com/spreadsheets/d/...'
    }
  ]
}

Drive Read

const content = await tools.drive_read({
  fileId: 'file-123',
  mimeType: 'text/plain' // Convert to plain text
});

// Returns
{
  content: 'File content here...',
  metadata: {
    name: 'document.docx',
    size: 12345,
    mimeType: 'application/vnd.google-apps.document'
  }
}

Calendar Events

const events = await tools.calendar_events({
  calendarId: 'primary',
  timeMin: '2024-01-15T00:00:00Z',
  timeMax: '2024-01-22T00:00:00Z'
});

// Returns
{
  events: [
    {
      id: 'event-123',
      summary: 'Team Meeting',
      start: { dateTime: '2024-01-16T10:00:00Z' },
      end: { dateTime: '2024-01-16T11:00:00Z' },
      attendees: [
        { email: 'alice@company.com', responseStatus: 'accepted' },
        { email: 'bob@company.com', responseStatus: 'tentative' }
      ],
      location: 'Conference Room A',
      meetLink: 'https://meet.google.com/xxx-xxx-xxx'
    }
  ]
}

Calendar Create

const event = await tools.calendar_create({
  calendarId: 'primary',
  summary: 'Project Kickoff',
  description: 'Initial planning meeting',
  start: '2024-01-20T14:00:00Z',
  end: '2024-01-20T15:00:00Z',
  attendees: ['alice@company.com', 'bob@company.com'],
  sendNotifications: true
});

// Returns
{
  id: 'event-456',
  htmlLink: 'https://calendar.google.com/event?eid=...',
  meetLink: 'https://meet.google.com/xxx-xxx-xxx'
}

Sheets Read

const data = await tools.sheets_read({
  spreadsheetId: 'sheet-123',
  range: 'Sheet1!A1:D10'
});

// Returns
{
  values: [
    ['Name', 'Email', 'Department', 'Start Date'],
    ['Alice', 'alice@company.com', 'Engineering', '2023-01-15'],
    ['Bob', 'bob@company.com', 'Sales', '2023-03-01']
  ],
  metadata: {
    spreadsheetId: 'sheet-123',
    sheetTitle: 'Sheet1',
    rowCount: 3,
    columnCount: 4
  }
}

Sheets Write

await tools.sheets_write({
  spreadsheetId: 'sheet-123',
  range: 'Sheet1!A11',
  values: [
    ['Charlie', 'charlie@company.com', 'Marketing', '2024-01-15']
  ]
});

Google Admin

For IT administration tasks (user provisioning, group management, license assignment), you need Admin SDK access.

Prerequisites

Before using Admin SDK tools, you must:

Enable the Admin SDK API in Google Cloud Console:
- Go to Google Cloud Console
- Navigate to APIs & Services > Library
- Search for "Admin SDK API" and enable it
- Also enable "Groups Settings API" if managing group settings

Set up Domain-Wide Delegation (for service accounts):

In Google Admin Console, go to Security > API controls > Domain-wide delegation
Add your service account client ID

Add required scopes:

https://www.googleapis.com/auth/admin.directory.user
https://www.googleapis.com/auth/admin.directory.group
https://www.googleapis.com/auth/admin.directory.user.security
https://www.googleapis.com/auth/apps.licensing

Grant Admin Privileges:
- The service account must impersonate a super admin user
- Use the adminEmail field when connecting

Admin Tools

Tool	Description
`google_admin_create_user`	Create new user
`google_admin_list_users`	List domain users
`google_admin_update_user`	Update user properties
`google_admin_suspend_user`	Suspend user account
`google_admin_create_group`	Create group
`google_admin_add_to_group`	Add member to group
`google_admin_list_skus`	List available licenses
`google_admin_assign_license`	Assign license to user
`google_admin_revoke_license`	Remove license from user

Create User

const user = await tools.google_admin_create_user({
  email: 'newuser@company.com',
  firstName: 'New',
  lastName: 'User',
  password: 'temporary-password',
  changePasswordAtNextLogin: true,
  orgUnitPath: '/Employees/Engineering'
});

// Returns
{
  id: 'user-123',
  primaryEmail: 'newuser@company.com',
  name: { givenName: 'New', familyName: 'User' },
  isAdmin: false,
  isDelegatedAdmin: false,
  creationTime: '2024-01-15T10:00:00Z'
}

List Users

const users = await tools.google_admin_list_users({
  domain: 'company.com',
  query: 'orgUnitPath=/Employees/Engineering',
  maxResults: 50
});

Assign License

await tools.google_admin_assign_license({
  userEmail: 'newuser@company.com',
  productId: 'Google-Apps',
  skuId: '1010020020' // Google Workspace Business Standard
});

Best Practices

1. Minimal Scopes

// ✅ Good - request only what you need
scopes: ['gmail.readonly', 'calendar.readonly']

// ❌ Bad - overly broad
scopes: ['https://mail.google.com/']

2. Error Handling

try {
  const emails = await tools.gmail_search({ query: '...' });
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // Wait and retry
  } else if (error.code === 'PERMISSION_DENIED') {
    // Check scopes
  }
}

3. Pagination

// Handle large result sets
let pageToken = null;
const allEmails = [];

do {
  const result = await tools.gmail_search({
    query: 'is:unread',
    pageToken
  });
  allEmails.push(...result.messages);
  pageToken = result.nextPageToken;
} while (pageToken);

4. Use Service Accounts for Automation

// For scheduled tasks, use service account
// Avoids user token expiry issues

Troubleshooting

"Access Denied"

Check user has Google Workspace license
Verify OAuth scopes include required API
Check Google Admin console for API restrictions

"Rate Limit Exceeded"

Google APIs have per-user and per-project limits:

API	Limit
Gmail	250 quota units/user/second
Drive	12,000 requests/day
Calendar	500 requests/100 seconds

"Invalid Grant"

OAuth token expired or revoked:

await client.integrations.refreshConnection('connection-123');

Next: Explore Microsoft 365 integration.

Available Tools​

Gmail​

Google Drive​

Google Calendar​

Google Docs​

Google Sheets​

Connecting​

Required Scopes​

OAuth Setup​

Service Account (Admin)​

Tool Examples​

Gmail Search​

Gmail Send​

Drive Search​

Drive Read​

Calendar Events​

Calendar Create​

Sheets Read​

Sheets Write​

Google Admin​

Prerequisites​

Admin Tools​

Create User​

List Users​

Assign License​

Best Practices​

1. Minimal Scopes​

2. Error Handling​

3. Pagination​

4. Use Service Accounts for Automation​

Troubleshooting​

"Access Denied"​

"Rate Limit Exceeded"​

"Invalid Grant"​