Google Sheets in Agent Builder

The Google Sheets step lets an agent read and change a spreadsheet on a Google account you sign in, as part of a run. It can find or create a spreadsheet by its title, list recent files, read a tab as rows or as a range, append a row for each item that arrives, update a range, add a tab, or format cells. Each step does one thing, picked from 10 actions, and hands what Google sends back to the next step. A row it reads can answer a question. A row it appends can keep a log. The step has no trigger of its own: a schedule, a BigChange alert, or an email arriving in Outlook or Gmail starts the run, and this step writes or reads once that run is going.

app.centrus.ai/app/agents/workflow-builder

Agents

Build modular AI workflows with reusable nodes

Weekly job log

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Monday at 07:00

Weekly · Mon at 07:00

This week's jobs

List jobs

Each job

Batch size 1

Log the job

Append row · Completed

2

AI builderMap

1. 1Google Sheets in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action and the tab, Append row · Completed.
3. 3Connection: the one Google account this agent uses. There is no account list on the step.
4. 4Actions: the one action this step performs. Append row is selected.
5. 5Spreadsheet title and Worksheet in Google Sheets. Here the week's jobs are appended to the Completed tab in Weekly jobs.

Centrus works alongside Google Sheets. The spreadsheet stays in that Google account's Drive, and the agent reads and writes it. It does not replace the spreadsheet, and it does not replace the job system that produced the rows. To ask about a spreadsheet in a conversation rather than in an agent, see Google Sheets in chat. How connections differ across chat, Agent Builder and Train is in Integrations overview.

Open the agent in Agent Builder and find Google Sheets in the Integration group of the Nodes panel, under Microsoft Word and above Google Docs. Drag it onto the canvas and connect the step before it to its left-hand side. Until you choose an action, its summary on the canvas reads No actions selected. Once you have chosen one, the summary is the action's name, and the tab too if you have typed one, for example Append row · Completed. It does not read 1 action enabled, which is what an Outlook or Gmail step shows.

Monday at 07:00

Weekly · Mon at 07:00

Google Sheets

No actions selected

2

1. 1Google Sheets in the Integration group. Drag it onto the canvas.
2. 2The new step. It reads No actions selected until you choose an action in its Details panel.

On a phone, Agent Builder shows the canvas only. The Nodes panel is hidden on screens narrower than 768 pixels and the Details panel on screens narrower than 1,024 pixels, so you can follow an agent's steps on a phone but need a tablet or computer to add a Google Sheets step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Monday at 07:00

Weekly · Mon at 07:00

This week's jobs

List jobs

Each job

Batch size 1

Log the job

Append row · Completed

The Google Sheets connection belongs to this agent alone. It is stored for this agent, not taken from the Google Sheets card on the Integrations page, so connecting chat does not connect the agent, and connecting the agent does not connect chat. One connection covers every Google Sheets step on the agent, so you only sign in once per agent. The agent holds one Google account. There is no Account list on the step, and Settings has no Add another account for Google Sheets.

You sign in with Google. There is no customer ID or secret to copy, and there is no Copy from existing agent, because that list is only for connections that use a key. The person who signs in needs a Google account that can open the spreadsheet, or should own it, such as accounts@meridianfm.co.uk. Google's page asks you to choose an account, then to allow access. Centrus asks to see, edit, create and delete spreadsheets on that account, to see and download files in Drive so it can find a spreadsheet by its title, and to see the account's email address. It does not ask to change other files in Drive. The chat card asks for a wider Drive permission than this step does. Later runs use that sign-in, so a Monday schedule can open the spreadsheet without anyone sitting at the screen. Signing in again replaces the account already stored on the agent.

1. 1Save the agent with Save draft. Until it has been saved once, the Connection section reads Save this workflow as a draft first, then connect the account. and Connect is greyed out.
2. 2Select the Google Sheets step. In the Details panel, open Connection and click Connect.
3. 3Centrus leaves Agent Builder and opens Google's account page. Choose the account, then choose Allow.
4. 4You return to the agent. A message reads Google Sheets connected for this agent. Connection now reads Connected, followed by that account's address.

Centrus does not store a password. Google accepts or refuses the sign-in. If you close Google's page before you finish, nothing is saved and Connection stays Not connected. If Centrus cannot open Google at all, you see Failed to start Google Sheets connection. Try Connect again, and if it persists ask whoever looks after that Google account.

Whose account a run uses. Integration mode, in Settings, is shown to the agent's owner and to an organisation administrator. Agent-level is the default, and it is the mode this step is built for: every Google Sheets step uses the account connected on the agent, whoever starts the run. Per-user is only offered when the agent starts from chat. The control is greyed out for a schedule, for Email received, and for a system alert, because a scheduled run has no triggering user. Google Sheets is not one of the systems that can use a person's own chat connection. Outlook and Gmail are. If you switch the agent to Per-user anyway, the Connection section still shows the agent's account and adds a note that this step always uses that connection, because Google Sheets has no per-user credentials. A run in that mode still fails. The message says the action is not supported, and it talks about sending and creating drafts, which are Outlook and Gmail actions, not Google Sheets. Keep an agent that uses Google Sheets on Agent-level. For how sharing and this switch fit together, see Share an agent.

Sharing and copying the agent. When you share an agent, its Google Sheets connection stays on the agent. People you share it with cannot see or copy the sign-in. Their runs use the agent's Google account. When you duplicate an agent, the steps are copied and the connection is not. The copy says to connect again. Sign in again on the copy.

Disconnecting. Disconnect on the step removes Google Sheets from this agent. The confirmation reads Google Sheets disconnected from this agent. Every Google Sheets step on the agent stops until someone signs in again. Other agents keep their own accounts, and the Google Sheets card in chat is left as it is.

Select the step and open Actions in the Details panel. On a step in the agent's main flow the list is a set of radio buttons, one action only. The line under the title reads What this step does with the connected Google Sheets account. There is no search box. The 10 names, in order, are Find or create spreadsheet, List spreadsheets, Get spreadsheet, Ensure sheet, Append row, Read rows, Read values, Update values, Create sheet and Format cells. The canvas summary becomes the action's name, plus the tab when you have set Worksheet.

The fields sit in a section titled Google Sheets, under the actions. The line there says an append writes one row per incoming item, a bare spreadsheet title is found or created, and there is no folder path. Which boxes appear depends on the action. Spreadsheet title is the file's name, with no folder in front of it. For Append row, Find or create spreadsheet and Ensure sheet, a title that matches nothing is created in that Google account's Drive. Read rows never creates a file. A missing title fails the read, even though the line under Google Sheets still says a title is found or created.

Append row is the usual way to add lines to a log. Spreadsheet ID (optional) is the long id from the spreadsheet's address. Leave it empty when Spreadsheet title should find or create the file. Worksheet is the tab, and it defaults to Sheet1 if you leave it empty. Headers is one column name per line. Those names are written on row 1 only when that row is empty, and that row is made bold. Row values is one cell per line, left to right. Each item that arrives becomes one spreadsheet row, so a list of twelve jobs becomes twelve rows in that one visit, written in batches of up to 200. Put {{ item.json.reference }} in a cell when the step sits inside a Loop. You do not need Find or create spreadsheet or Ensure sheet in front of Append row: the append finds or creates the spreadsheet from the title, makes sure the tab exists, writes the headers when row 1 is empty, and then adds the rows.

To use a value from an earlier step, open Step data references at the top of the Details panel and click a field to copy its reference, then paste it into a Row values line, into Spreadsheet title, or into Range. In the weekly agent, the job reference, the site and the engineer come from the job item inside the Loop. A column name is used as it is written, including spaces and capitals. Keep those names as plain words so a later step can refer to them.

Find or create spreadsheet only asks for Spreadsheet title. It returns the file's id and address for a later step. The lookup is an exact title, among Google Sheets files, newest first, and a title that differs only by capitals still matches. List spreadsheets shows no fields. It returns the 10 most recently changed spreadsheet files on the connected account, and it does not fetch a second page. That list can include an Excel file someone uploaded to Drive, as well as a native Google Sheet. Get spreadsheet asks for Spreadsheet ID and returns the file's details and the names of its tabs.

Ensure sheet asks for Spreadsheet title or Spreadsheet ID (optional), Worksheet and Headers. It makes sure the tab exists, writes the header line when row 1 is empty, and bolds that row. Read values asks for Spreadsheet ID, Worksheet and Range, such as A1:D20 or Plant!A1:D20. A range that already names a tab is used as it is. A bare range is placed on Worksheet. Empty rows and columns at the end are dropped. Read rows is the one to use when the next step should see each data row on its own. It asks for Spreadsheet title or Spreadsheet ID (optional), and Worksheet. It passes on one item per non-blank data row, with the real sheet row, the spreadsheet id, and one field per header, using the header text as written. A blank row is skipped and does not shift the later row numbers. The cells come back as the text the sheet shows. There is no box for which row holds the headers: it is always row 1. Update values asks for Spreadsheet ID, Worksheet, Range and Row values. It writes that one row into the range. It does not add rows at the bottom: use Append row for that. Do not point a long list of values at a single cell. Google writes downward from that cell and will change the rows underneath.

Create sheet asks for Spreadsheet ID and New tab name. It adds the tab and does not write headers. Use Ensure sheet or Append row when the new tab should start with a header row. Format cells on the main path only shows Spreadsheet ID. There is nowhere to type a colour, a font, an alignment, a number format, or which cells to format. Attach it to an Intelligence step if you need those, or format the sheet in Google Sheets. The description under the action mentions an internal name for the read, and it uses a dash. You can ignore both and use Read rows.

What the step passes on. Read rows and List spreadsheets pass on one item per row or file. A single Append row passes on one item for each item that arrived, with the spreadsheet id, the tab, and how many rows were written. Later steps reach their fields through Step data references, and an Intelligence step reads all of the items together. To update one row for each item from a list, put Update values inside a Loop, described in Conditions, loops and approvals. Append row does not need a Loop when every item should simply become a row: it writes them all in that one visit. Use a Loop when something else has to happen to each item first.

As a tool for an Intelligence step. Connect a Google Sheets step to the Tools side of an Intelligence step and Actions becomes a searchable list where you can tick several. The line changes to Choose the tools this assistant can call. It fills the fields on the call. The AI decides when to call each one and fills in the fields itself. The canvas summary is the first action, then a count if there are more, such as Read rows · Plant +2.

Question from chat

From chat

Answer the date

GPT-5.6 Terra

PPM tools

Read rows · Plant +2

1

1. 1The Google Sheets step attached to the Intelligence step as a tool.
2. 2Actions: the Google Sheets actions the AI may call. Here, read rows, list spreadsheets and get a spreadsheet.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval sits under Require approval on every Google Sheets step, but it only applies to calls an AI makes, so it has no effect on a step in the main flow. To ask someone before a main-flow step changes a spreadsheet, put an Approval step in front of it.

Google Sheets has no trigger of its own. Nothing in Drive starts a run when a cell changes. The run starts somewhere else, and the Google Sheets step is one of the steps after that. Three starts cover almost every facilities spreadsheet: a Schedule Trigger (every Monday at 07:00, for a weekly log), Email received (a repair request lands in a folder, and the next step appends a row), or another system's alert, such as a BigChange webhook when a job is finished. Setting up a schedule is part of the trigger's own panel. Email is covered in Start an agent when an email arrives. A BigChange alert is covered in BigChange REST in Agent Builder. The general picture for every system is in Start an agent from a system alert.

Repair requests

Outlook · Inbox/Requests

Log the request

Append row · Requests

1. 1Connection on Email received. This is the agent's Outlook connection, not the Google Sheets connection. Google Sheets has no trigger of its own.
2. 2Mailbox: Provider is Outlook, and Folder is the folder to watch. Inbox/Requests watches that folder, not the folders inside it.
3. 3How do we decide this is the right email?: the filters. Open it on the trigger. The full guide is the Email received article.

What the Google Sheets step should read from the start. An email trigger hands the new message to the next step: sender, subject, text and a list of attachments. Append row can put the sender and subject into Row values, or an Intelligence step can turn the message into a short line first and the Google Sheets step can paste that line. A schedule hands on the time it fired, so the Google Sheets step usually follows a step that fetched the rows, such as a BigChange list of the week's jobs. A BigChange webhook hands on the id of the record that changed. Follow it with a BigChange Get if you need the site and the engineer, then Append row. A filter that does not match does not start a run and does not use a credit. The trigger itself is free. Each run it starts costs 1 credit, like any other run.

Alerts only start runs once the agent is published. Run now works on a draft. A simulated BigChange alert is a real run: a Google Sheets write still changes the spreadsheet, and the run uses credits. Try the write with a dry run first, as described under Test before it goes live.

Monday at 07:00

Weekly · Mon at 07:00

This week's jobs

List jobs

Each job

Batch size 1

Log the job

Append row · Completed

Weekly completed-jobs log appends the week's finished jobs to a spreadsheet every Monday at 07:00. This week's jobs uses BigChange REST to list the jobs in that window. Log the job sits inside a Loop so it runs once per job, which is the place for a lookup that has to happen before that row is written. Spreadsheet title is Weekly jobs and Worksheet is Completed. The columns are the job reference, the site, the engineer, the status and the time it finished. For job J-10482, a boiler service at Riverside House for Northgate Housing, Dylan Hughes is the engineer. The list costs 1 credit. Each append costs another credit, so twelve jobs cost twelve credits for that step. If every job is only becoming a row, connect the list straight to Append row and skip the Loop: every job becomes a row in one visit, written in batches of up to 200, for 1 credit. The BigChange side of the list is in BigChange REST in Agent Builder.

Repair requests

Outlook · Inbox/Requests

Read the request

GPT-5.6 Terra

Log the request

Append row · Requests

Log email requests adds a row when a repair request lands in Inbox/Requests. The trigger watches that folder on accounts@meridianfm.co.uk. Read the request turns the message into a short line: who asked, which site, and what they need. Log the request is Append row, with Spreadsheet title set to Email requests and Worksheet set to Requests. The columns are the time, the sender, the site and the summary. A message from Sarah Price about a leaking plant room at 12 High Street becomes one row, and the sheet keeps growing because nothing on this step clears the rows already there. Each matching email costs at least 4 credits: 1 for the run, at least 2 for Read the request and 1 for the row. The email trigger is free.

Question from chat

From chat

Read the PPM sheet

Read rows · Plant

Answer the date

GPT-5.6 Terra

Answer from a PPM sheet reads a spreadsheet the contracts team already keep, and answers a question asked in chat. Priya Shah asks when the boiler at Riverside House is next due. Read the PPM sheet uses Read rows, with Spreadsheet title set to PPM schedule and Worksheet set to Plant. The header stays on row 1, which is the only row this step will treat as the header. The sheet is find-only: a mistyped title fails the step and does not create an empty spreadsheet. Answer the date reads the rows together and replies with the matching line, for example an annual boiler service due on 16/10/2026. The read costs 1 credit however many rows come back, up to the size limit under Limits and good to know. The chat that starts the run is covered in Run an agent from chat.

A dry run is the safe way to try a Google Sheets step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Read actions such as Read rows, Read values, List spreadsheets and Get spreadsheet call Google for real, so you see real rows. Write actions, Find or create spreadsheet, Append row, Update values, Ensure sheet, Create sheet and Format cells, are skipped. The step's summary starts with DRY RUN and says what it would have done, and nothing in the spreadsheet changes. Run for real performs every action, including the writes.

{
  "handles": {
    "main": 14
  },
  "items": {
    "main": [
      {
        "Site": "Riverside House",
        "Asset": "Boiler",
        "Task": "Annual service",
        "Due": "16/10/2026",
        "rowNumber": 4,
        "spreadsheetId": "1MeridianPpm2026"
      }
    ]
  }
}

Open a step in the run to see its output. A skipped append says it would have appended the rows and names the tab. The panel shows the first 50 items of each output, and later steps still receive all of them. A dry run costs 1 credit for the whole run. For a published agent, Run now on Run for real writes to the spreadsheet, so try Append row and Update values with a dry run first. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

A Google Sheets step costs 1 automation credit each time it runs successfully, whatever the action and however many rows Read rows returns or Append row writes in that visit. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. Google Sheets has no trigger. A run started by a schedule, by Email received, or by another system's alert still costs 1 credit for the run, like any other run, and that trigger itself is free.

Inside a Loop, the step is charged on every pass, so a Loop over 40 jobs that appends each one costs 40 credits for that step. One Append row visit is usually cheaper than a Loop when every item is only becoming a row. One Read rows is cheaper than reading the sheet one row at a time. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• Two connections. The agent's Google account and each person's Google Sheets card in chat are separate. Connecting one does not connect the other. The agent's sign-in can see and download Drive files so it can find a spreadsheet by title. The chat card asks for a wider Drive permission. A spreadsheet created in chat is not automatically the spreadsheet this step uses, unless it sits on the Google account you signed in on the agent.
• One account, no folder. The step uses the single account chosen on Google's page. A bare Spreadsheet title is matched by its exact name. There is no folder box, so a new spreadsheet is created in that account's Drive rather than in a folder you name. Signing in again replaces the stored account. There is no second account to switch to.
• Per-user integration mode. Google Sheets has no per-user credentials. The Connection note says the step still uses the agent's account. The run does not: every Google Sheets action fails in that mode, and the message talks about sending mail. Keep the agent on Agent-level.
• Read size. A read over 8 MB fails, and the message states the size, the row count and the limit. A read over 1 MB still succeeds. Narrow the tab, or read a smaller Range, rather than pulling a very wide sheet into the run.
• List spreadsheets. On the main path there is no box for how many files to return. The step returns the 10 most recently changed files and will not fetch a second page. The list can include an uploaded Excel file as well as a Google Sheet.
• Append. Append row writes up to 200 rows in each call to Google, still as one step visit. Values are entered as the sheet would type them, so a date written as 09/10/2026 follows the spreadsheet's own locale. Headers are written only when row 1 is empty, and that row is bold.
• Read rows. The header is always row 1. Each item is one data row, keyed by the header text as written, plus the real sheet row and the spreadsheet id. A blank row is skipped. The cells are the text the sheet shows. A missing title does not create a spreadsheet.
• Create sheet and Format cells. Create sheet adds a tab from New tab name and does not write headers. Format cells on the main path has no colour, font, alignment or range. Format the sheet in Google Sheets, or attach Format cells to an Intelligence step as a tool.

• Google Sheets not connected to this agent. Open the step's Connection section and click Connect. If you have duplicated the agent, the copy needs its own sign-in. A chat connection on the Integrations page does not count. Google Sheets not connected, without the words to this agent, is the chat card, not this step. A second wording, Google Sheets not connected for this agent, can appear from the same sign-in. Treat it the same way.
• Save this workflow as a draft first, then connect the account. Click Save draft, then Connect.
• Failed to start Google Sheets connection. Centrus could not open Google. Try Connect again.
• The action is not supported in per-user mode. The agent is on Per-user. Google Sheets cannot run in that mode. Switch Integration mode to Agent-level. The message names an internal action id and mentions sending and creating drafts. You can ignore both and use the action's name from Actions.
• Google Sheets node needs a spreadsheet. Append row and Ensure sheet need Spreadsheet title or Spreadsheet ID. Set one of them.
• Google Sheets read rows needs a spreadsheet. Read rows has no title and no id. The message names the internal field names. Set Spreadsheet title or Spreadsheet ID (optional).
• The spreadsheet was not found. Read rows looked through the connected Drive for a Google Sheet of that exact title and did not find one. Check the title and the account under Connection. A read never creates a spreadsheet, even though the line under Google Sheets says a title is found or created.
• No actions selected. The step has no action yet. Choose one under Actions.
• Format cells does nothing useful on the main path. There is no box for the cells or the formatting. Use Google Sheets itself, or attach the action to an Intelligence step.
• A list stops early. List spreadsheets stops at 10. Read rows stops if the tab is over 8 MB. Narrow the sheet rather than expecting every file on the Drive.
• An earlier append is not reusable. A retried Append row can stop with an idempotency conflict. Read the run that already wrote the rows before you run the step again, so you do not add the same lines twice.
• An alert never starts the agent. Google Sheets does not listen for alerts. Check the schedule, the Email received trigger, or the other system's webhook on the same agent. The agent must be published. See Start an agent from a system alert.

The Google Sheets step has 10 actions. Four read the spreadsheet and six change it. They call the Google Sheets API at https://sheets.googleapis.com and, when the step has to find or list a file, the Drive API at https://www.googleapis.com, as the Google account connected on the agent. Where an action calls more than one path, the table gives the main one.