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.
"""
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")Use the ID segment from your spreadsheet URL, not the entire URL, and provide a range for a tab you can access. Constructor spreadsheet_id and spreadsheet_range take precedence over method arguments, so this configured toolkit always reads that range. Only read_sheet is registered by default.
Run the Example
Set up your virtual environment
uv venv --python 3.12
source .venv/bin/activateInstall dependencies
uv pip install -U agno google-api-python-client google-auth google-auth-httplib2 google-auth-oauthlib openaiExport your OpenAI API key
export OPENAI_API_KEY="your_openai_api_key_here"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.
Run the example
Save the code above as googlesheets_tools.py, then run:
python googlesheets_tools.pyFull source: cookbook/91_tools/googlesheets_tools.py