crewAI/docs/edge/en/enterprise/integrations/google_sheets.mdx

---
title: Google Sheets Integration
description: "Spreadsheet data synchronization with Google Sheets integration for CrewAI."
icon: "google"
mode: "wide"
---

## Overview

Enable your agents to manage spreadsheet data through Google Sheets. Read rows, create new entries, update existing data, and streamline your data management workflows with AI-powered automation. Perfect for data tracking, reporting, and collaborative data management.

## Prerequisites

Before using the Google Sheets integration, ensure you have:

- A [CrewAI AMP](https://app.crewai.com) account with an active subscription
- A Google account with Google Sheets access
- Connected your Google account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors)
- Spreadsheets with proper column headers for data operations

## Setting Up Google Sheets Integration

### 1. Connect Your Google Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Google Sheets** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for spreadsheet access
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash
uv add crewai-tools
```

### 3. Environment Variable Setup

<Note>
  To use integrations with `Agent(apps=[])`, you must set the
  `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
  Token.
</Note>

```bash
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Actions

<AccordionGroup>
  <Accordion title="google_sheets/get_spreadsheet">
    **Description:** Retrieve properties and data of a spreadsheet.

    **Parameters:**
    - `spreadsheetId` (string, required): The ID of the spreadsheet to retrieve.
    - `ranges` (array, optional): The ranges to retrieve from the spreadsheet.
    - `includeGridData` (boolean, optional): True if grid data should be returned. Default: false
    - `fields` (string, optional): The fields to include in the response. Use this to improve performance by only returning needed data.

  </Accordion>

  <Accordion title="google_sheets/get_values">
    **Description:** Returns a range of values from a spreadsheet.

    **Parameters:**
    - `spreadsheetId` (string, required): The ID of the spreadsheet to retrieve data from.
    - `range` (string, required): The A1 notation or R1C1 notation of the range to retrieve values from.
    - `valueRenderOption` (string, optional): How values should be represented in the output. Options: FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA. Default: FORMATTED_VALUE
    - `dateTimeRenderOption` (string, optional): How dates, times, and durations should be represented in the output. Options: SERIAL_NUMBER, FORMATTED_STRING. Default: SERIAL_NUMBER
    - `majorDimension` (string, optional): The major dimension that results should use. Options: ROWS, COLUMNS. Default: ROWS

  </Accordion>

  <Accordion title="google_sheets/update_values">
    **Description:** Sets values in a range of a spreadsheet.

    **Parameters:**
    - `spreadsheetId` (string, required): The ID of the spreadsheet to update.
    - `range` (string, required): The A1 notation of the range to update.
    - `values` (array, required): The data to be written. Each array represents a row.
      ```json
      [
        ["Value1", "Value2", "Value3"],
        ["Value4", "Value5", "Value6"]
      ]
      ```
    - `valueInputOption` (string, optional): How the input data should be interpreted. Options: RAW, USER_ENTERED. Default: USER_ENTERED

  </Accordion>

  <Accordion title="google_sheets/append_values">
    **Description:** Appends values to a spreadsheet.

    **Parameters:**
    - `spreadsheetId` (string, required): The ID of the spreadsheet to update.
    - `range` (string, required): The A1 notation of a range to search for a logical table of data.
    - `values` (array, required): The data to append. Each array represents a row.
      ```json
      [
        ["Value1", "Value2", "Value3"],
        ["Value4", "Value5", "Value6"]
      ]
      ```
    - `valueInputOption` (string, optional): How the input data should be interpreted. Options: RAW, USER_ENTERED. Default: USER_ENTERED
    - `insertDataOption` (string, optional): How the input data should be inserted. Options: OVERWRITE, INSERT_ROWS. Default: INSERT_ROWS

  </Accordion>

  <Accordion title="google_sheets/create_spreadsheet">
    **Description:** Creates a new spreadsheet.

    **Parameters:**
    - `title` (string, required): The title of the new spreadsheet.
    - `sheets` (array, optional): The sheets that are part of the spreadsheet.
      ```json
      [
        {
          "properties": {
            "title": "Sheet1"
          }
        }
      ]
      ```

  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Google Sheets Agent Setup

```python
from crewai import Agent, Task, Crew

# Create an agent with Google Sheets capabilities
sheets_agent = Agent(
    role="Data Manager",
    goal="Manage spreadsheet data and track information efficiently",
    backstory="An AI assistant specialized in data management and spreadsheet operations.",
    apps=['google_sheets']
)

# Task to add new data to a spreadsheet
data_entry_task = Task(
    description="Add a new customer record to the customer database spreadsheet with name, email, and signup date",
    agent=sheets_agent,
    expected_output="New customer record added successfully to the spreadsheet"
)

# Run the task
crew = Crew(
    agents=[sheets_agent],
    tasks=[data_entry_task]
)

crew.kickoff()
```

### Filtering Specific Google Sheets Tools

```python
from crewai import Agent, Task, Crew

# Create agent with specific Google Sheets actions only
data_collector = Agent(
    role="Data Collector",
    goal="Collect and organize data in spreadsheets",
    backstory="An AI assistant that focuses on data collection and organization.",
    apps=[
        'google_sheets/get_values',
        'google_sheets/update_values'
    ]
)

# Task to collect and organize data
data_collection = Task(
    description="Retrieve current inventory data and add new product entries to the inventory spreadsheet",
    agent=data_collector,
    expected_output="Inventory data retrieved and new products added successfully"
)

crew = Crew(
    agents=[data_collector],
    tasks=[data_collection]
)

crew.kickoff()
```

### Data Analysis and Reporting

```python
from crewai import Agent, Task, Crew

data_analyst = Agent(
    role="Data Analyst",
    goal="Analyze spreadsheet data and generate insights",
    backstory="An experienced data analyst who extracts insights from spreadsheet data.",
    apps=['google_sheets']
)

# Task to analyze data and create reports
analysis_task = Task(
    description="""
    1. Retrieve all sales data from the current month's spreadsheet
    2. Analyze the data for trends and patterns
    3. Create a summary report in a new row with key metrics
    """,
    agent=data_analyst,
    expected_output="Sales data analyzed and summary report created with key insights"
)

crew = Crew(
    agents=[data_analyst],
    tasks=[analysis_task]
)

crew.kickoff()
```

### Spreadsheet Creation and Management

```python
from crewai import Agent, Task, Crew

spreadsheet_manager = Agent(
    role="Spreadsheet Manager",
    goal="Create and manage spreadsheets efficiently",
    backstory="An AI assistant that specializes in creating and organizing spreadsheets.",
    apps=['google_sheets']
)

# Task to create and set up new spreadsheets
setup_task = Task(
    description="""
    1. Create a new spreadsheet for quarterly reports
    2. Set up proper headers and structure
    3. Add initial data and formatting
    """,
    agent=spreadsheet_manager,
    expected_output="New quarterly report spreadsheet created and properly structured"
)

crew = Crew(
    agents=[spreadsheet_manager],
    tasks=[setup_task]
)

crew.kickoff()
```

### Automated Data Updates

```python
from crewai import Agent, Task, Crew

data_updater = Agent(
    role="Data Updater",
    goal="Automatically update and maintain spreadsheet data",
    backstory="An AI assistant that maintains data accuracy and updates records automatically.",
    apps=['google_sheets']
)

# Task to update data based on conditions
update_task = Task(
    description="""
    1. Get spreadsheet properties and structure
    2. Read current data from specific ranges
    3. Update values in target ranges with new data
    4. Append new records to the bottom of the sheet
    """,
    agent=data_updater,
    expected_output="Spreadsheet data updated successfully with new values and records"
)

crew = Crew(
    agents=[data_updater],
    tasks=[update_task]
)

crew.kickoff()
```

### Complex Data Management Workflow

```python
from crewai import Agent, Task, Crew

workflow_manager = Agent(
    role="Data Workflow Manager",
    goal="Manage complex data workflows across multiple spreadsheets",
    backstory="An AI assistant that orchestrates complex data operations across multiple spreadsheets.",
    apps=['google_sheets']
)

# Complex workflow task
workflow_task = Task(
    description="""
    1. Get all customer data from the main customer spreadsheet
    2. Create a new monthly summary spreadsheet
    3. Append summary data to the new spreadsheet
    4. Update customer status based on activity metrics
    5. Generate reports with proper formatting
    """,
    agent=workflow_manager,
    expected_output="Monthly customer workflow completed with new spreadsheet and updated data"
)

crew = Crew(
    agents=[workflow_manager],
    tasks=[workflow_task]
)

crew.kickoff()
```

## Troubleshooting

### Common Issues

**Permission Errors**

- Ensure your Google account has edit access to the target spreadsheets
- Verify that the OAuth connection includes required scopes for Google Sheets API
- Check that spreadsheets are shared with the authenticated account

**Spreadsheet Structure Issues**

- Ensure worksheets have proper column headers before creating or updating rows
- Verify that range notation (A1 format) is correct for the target cells
- Check that the specified spreadsheet ID exists and is accessible

**Data Type and Format Issues**

- Ensure data values match the expected format for each column
- Use proper date formats for date columns (ISO format recommended)
- Verify that numeric values are properly formatted for number columns

**Range and Cell Reference Issues**

- Use proper A1 notation for ranges (e.g., "A1:C10", "Sheet1!A1:B5")
- Ensure range references don't exceed the actual spreadsheet dimensions
- Verify that sheet names in range references match actual sheet names

**Value Input and Rendering Options**

- Choose appropriate `valueInputOption` (RAW vs USER_ENTERED) for your data
- Select proper `valueRenderOption` based on how you want data formatted
- Consider `dateTimeRenderOption` for consistent date/time handling

**Spreadsheet Creation Issues**

- Ensure spreadsheet titles are unique and follow naming conventions
- Verify that sheet properties are properly structured when creating sheets
- Check that you have permissions to create new spreadsheets in your account

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Google Sheets integration setup
  or troubleshooting.
</Card>