Summary
This guide explains how to configure the Google Sheets — Search and find row action in Astra. This action allows your agent to read and retrieve rows from a selected Google Sheets worksheet (tab) and return the results as a structured list.
To ensure the action works correctly, your spreadsheet must contain one non-empty header row at the top. These headers define the structure of the data that Astra reads.
Before configuring the action, make sure your Google account is connected to Astra.
Instructions
Follow these steps to configure the Google Sheets — Search and find row action:
Step 1: Open the action template
Log into your Astra account.
Go to the Action Library.
Select Google Sheets — Search and find row.
Open the Configuration page.
You will configure several sections on this page.
Step 2: Configure the action intent
In the Action intent section:
Enter an Action name.
Write an Intent that explains when the agent should look up rows in the spreadsheet.
Why this matters
The intent helps the agent understand when it should use this action.
Clear instructions improve the accuracy of when the action is triggered.
For example, the agent may search the sheet when a user asks for customer details or when it needs to retrieve stored information.
Step 3: Select the Google account
In the Google account section:
Choose the connected Google account that has access to the spreadsheet.
How this works
Astra uses the selected account to access Google Sheets through secure OAuth authentication.
The spreadsheet must be accessible from that account.
Step 4: Select the spreadsheet and worksheet
In the Spreadsheet and worksheet section:
Choose the Drive location.
Select the Spreadsheet.
Select the Worksheet (tab) that contains the data.
Important:
Only spreadsheets located in My Drive or Shared Drives can be used.
Astra will read data only from the selected worksheet.
Step 5: Configure row filtering
You can control how Astra reads rows using the Read only relevant rows toggle.
Option 1: Toggle OFF (read the entire sheet)
When the toggle is OFF:
Astra reads the entire worksheet.
All rows are returned to the agent.
Best for:
Sheets with small datasets (around 1,000 rows or fewer).
Option 2: Toggle ON (read only relevant rows)
When the toggle is ON:
Astra attempts to filter and return only relevant rows.
The agent searches the data instead of reading the entire sheet.
Important notes about matching:
Matching is approximate (fuzzy) for ASCII text.
Searches are typically:
Case-insensitive
Less sensitive to spaces or punctuation
For non-Latin text, matching is more literal and may require closer matches.
Best for:
Sheets with large datasets where reading the entire sheet would be inefficient.
What happens when the action runs
When the action is triggered:
Astra reads the selected Google Sheets worksheet.
It retrieves rows based on the configured settings.
The rows are returned to the agent as a structured list of data.
This allows your workflows to dynamically retrieve information stored in Google Sheets, such as customer records, product data, or internal tracking information.