Google Sheets Tools

Read a configured range with GoogleSheetsTools using service-account or OAuth credentials.

Read a Google Sheet with GoogleSheetsTools after configuring service-account or OAuth credentials.

Fresh setups must enable the Google Sheets API and configure Google credentials. The source’s OAuth redirect path is stale: InstalledAppFlow.run_local_server(port=8080) uses http://localhost:8080/, not http://localhost:8080/flowName=GeneralOAuthFlow. See the Google Sheets Python quickstart.

googlesheets_tools.py

"""

Google Sheets Toolkit can be used to read, create, update and duplicate Google Sheets.

Example spreadsheet: https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/
The ID is the URL of the spreadsheet and the range is the sheet name and the range of cells to read.

If you'd like to use a service account for access to Google Sheets, provide the absolute path
to the service account file either using the service_account_path arg in the GoogleSheetsTools
constructor or using a GOOGLE_SERVICE_ACCOUNT_FILE environment variable.

Note: Add the complete auth URL as an Authorised redirect URIs for the Client ID in the Google Cloud Console.

e.g for Localhost and port 8080: http://localhost:8080/flowName=GeneralOAuthFlow and pass the oauth_port to the toolkit

"""

from agno.agent import Agent
from agno.tools.google.sheets import GoogleSheetsTools

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------


SAMPLE_SPREADSHEET_ID = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
SAMPLE_RANGE_NAME = "Class Data!A2:E"

google_sheets_tools = GoogleSheetsTools(
    spreadsheet_id=SAMPLE_SPREADSHEET_ID,
    spreadsheet_range=SAMPLE_RANGE_NAME,
    oauth_port=8080,  # or any other port
)

agent = Agent(
    tools=[google_sheets_tools],
    instructions=[
        "You help users interact with Google Sheets using tools that use the Google Sheets API",
        "Before asking for spreadsheet details, first attempt the operation as the user may have already configured the ID and range in the constructor",
    ],
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response("Please tell me about the contents of the spreadsheet")

Run the Example

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
2. Install dependencies

   uv pip install -U agno google-api-python-client google-auth google-auth-httplib2 google-auth-oauthlib openai
   
3. Export your OpenAI API key

   Mac/Linux

   export OPENAI_API_KEY="your_openai_api_key_here"
   

   $Env:OPENAI_API_KEY="your_openai_api_key_here"
   
4. Configure Google Sheets authentication

   Enable the Google Sheets API. Then choose one credential flow: set GOOGLE_SERVICE_ACCOUNT_FILE to a service-account JSON key and share the target sheet with that account’s email; or create an OAuth desktop client, save its JSON as credentials.json beside the script, and authorize in the browser. With oauth_port=8080, use http://localhost:8080/ as the local redirect URI. If your OAuth client requires registered redirect URIs, register that exact URL.

5. Run the example

   Save the code above as googlesheets_tools.py, then run:

   python googlesheets_tools.py
   

Full source: cookbook/91_tools/googlesheets_tools.py