Google Docs in Agent Builder

The Google Docs step lets an agent create and update Google Docs in a Google Drive as part of a run. It can find a document by its exact title or create it, list the recent Docs on that account, read a document's title, link and body, append headings, paragraphs, lists and tables, or replace a phrase. Each step does one thing, picked from 5 actions, and hands what Google sends back to the next step. A finished letter stays in Drive as a real Google Doc, with a link later steps can put in an email.

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

Agents

Build modular AI workflows with reusable nodes

Job letter after a visit

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Job finished

Job status changed

Fetch the job

Get job

Write the letter

GPT-5.6 Terra

Write the document

Insert blocks · Job letter, Riverside House

2

AI builderMap

1. 1Google Docs in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action and the document title, Insert blocks · Job letter, Riverside House.
3. 3Connection: the one Google account this agent uses. The address is the account you signed in.
4. 4Actions: the one action this step performs. Insert blocks is selected.
5. 5Document title: the name of the Google Doc in Drive.

Centrus works alongside Google Docs. The file stays in the Drive of the account you sign in, and anyone who can open that Drive can open it in Docs. The step does not replace the job system. To ask for a document in a conversation rather than in an agent, see Google Docs in chat. How connections differ across chat, Agent Builder and Train is in Integrations overview.

Open the agent in Agent Builder and find Google Docs in the Integration group of the Nodes panel, under Google Sheets and above OneDrive. Drag it onto the canvas and connect the step before it to its left-hand side. A new step already has Insert blocks chosen, so its summary reads Insert blocks. Once you type a Document title, the summary becomes Insert blocks followed by that title. If you clear the action, the summary reads No actions selected.

Job finished

Job status changed

Google Docs

Insert blocks

2

1. 1Google Docs in the Integration group. Drag it onto the canvas.
2. 2The new step. It already reads Insert blocks, which is the action a new step starts with.

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 Docs step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Job finished

Job status changed

Fetch the job

Get job

Write the letter

GPT-5.6 Terra

Write the document

Insert blocks · Job letter, Riverside House

The Google Docs connection belongs to this agent alone. It is separate from the Google Docs 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 Docs step on the agent, so you only sign in once per agent. The agent holds one Google account for Docs. There is no Account list on the step, and Settings has no Add another account for Google Docs. Signing in again replaces that one account.

You sign in with Google. There is no customer ID or secret to copy. The person who signs in needs the Google account whose Drive should hold the documents, such as accounts@meridianfm.co.uk. Centrus asks Google for permission to see, edit, create and delete that account's Google Docs, to see and download every file in its Drive, and to see the account's email address. The Drive permission is read only, and it is wider than Docs: the title search and the document list use it, and the step still only writes Google Docs. Google's page asks you to pick an account and then to allow those permissions. Chat's Google Docs card asks for a wider Drive permission, because chat can also save a file into a folder. The two sign-ins stay separate.

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 Docs 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 allow the permissions. You have 10 minutes to finish. After that the sign-in expires and you start again from Connect.
4. 4You return to the agent. A notice reads Google Docs connected for this agent, and Connection 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 Docs connection. Try Connect again. If the sign-in fails after you have left the builder, you land on the agents list and the page does not say why. Open the agent and click Connect again.

One account. Gmail, Outlook, Excel, Word, OneDrive and SharePoint can hold several accounts on one agent, with an Account picker on the step. Google Docs cannot. Settings, then Integrations, shows a single row: Connected and the address, with Disconnect. There is no rename, no primary, and no Add another account. To use a different Google account, click Connect again and pick the other one at Google. That replaces the account already stored. Every Google Docs step on the agent then uses the new 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 Google Docs uses. Every Google Docs step uses the account connected on the agent, whoever starts the run. Per-user is only offered when the agent starts from chat, and the note under the switch talks about Outlook and Gmail. Google Docs is not included. If the agent is switched to Per-user, the Google Docs step still uses the agent's own account. Its Connection section says so: the step always uses the agent's connection, because Google Docs has no per-user credentials. Keep an agent that writes documents on Agent-level so the Settings note and the step agree. For how sharing and this switch fit together, see Share an agent.

Sharing and copying the agent. When you share an agent, its Google Docs connection stays on the agent. People you share it with cannot see or copy the sign-in, and their runs write to the agent's Drive. When you duplicate an agent, the steps are copied and the connection is not. The copy says to connect again. There is no Copy from existing agent for Google Docs, because that list is only for connections that use a key rather than Google sign-in. Sign in again on the copy.

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

Select the step and open Actions in the Details panel. The line under the title reads What this step does with the connected Google Docs account. On a step in the agent's main flow the list is a set of radio buttons, one action only, in this order: Find or create document, List documents, Get document, Insert blocks, Replace text. There is no search box. The canvas summary shows the action's name, and the document title when you have typed one. It does not show a count such as 1 action enabled. A new step starts on Insert blocks.

Insert blocks then shows a section titled Google Docs. The line under that title says the step finds or creates the document, then appends headings, lists and tables, and that one visit writes one document from the first item. Document title is the name in Drive, for example Job letter, Riverside House. Leave Document ID blank and the step finds that title, or creates a blank Doc in My Drive if it is not there. If you already have the file's ID from an earlier step, paste it into Document ID and the title is not used for the lookup. The same section title and the same sentence stay on screen for the other actions, even when the step is only listing or reading.

The body of the document comes from Bind blocks from incoming item. Tick it when an Intelligence step has just written the letter or the report. The box fills with {{ item.json.blocks }}, and you leave it like that. The Intelligence step has to return that list: headings, paragraphs, bullets, numbered steps and tables. If it does not, a real run still finds or creates the document and then adds nothing. The panel has no rows for typing blocks yourself, and no bold, colour or size controls, even though a blocks list from the previous step can carry bold, italic, underline, a colour and a font size in points. The help under the tick mentions a list. That list is the one the previous step returns.

Each block has a type: heading 1, heading 2, heading 3, paragraph, bullet, numbered or table. Consecutive numbered blocks are one list, and the same is true of bullets. A table's rows are lines of cells, and the first row can be marked as a header, which is then bold. The step appends these blocks to whatever is already in the file. It does not clear the file first, so a second run of the same agent adds the letter again. There is no image, page break, header or footer.

Find or create document uses Document title. It searches Drive for a Google Doc with that exact name, ignoring the bin, and takes the newest match. An exact capitalisation is preferred, then any capitalisation. If it finds one, it passes on the ID and the link and does not change the file. If it does not, it creates a blank Doc in My Drive. The panel also shows Document ID for this action, but the action only uses the title. A name that already exists is reused. It is not saved again as the same name with (1). An empty title fails with A document title is required.

List documents returns one item, holding up to 10 Google Docs from the connected Drive, newest first, not in the bin. The panel has no box for that cap, so a step on the main path always asks for 10. Each file has an ID, a name, a created time, a modified time and a link. It does not pass on one item per file, so a Loop after it does not walk the files one by one. The Google Docs section still opens, with the insert sentence and no fields of its own. Get document needs Document ID. It returns the title, the link and the document body as Google stores it. That body is the document's structure, not a flat letter. There is no download, so a later step cannot attach the file or hand it to File Parser. To use the wording, let an Intelligence step read what Get document passed on.

Replace text shows Find and Replace with, and Document ID is required. Every match is replaced, and the match respects capitals, so Site and site are different. The panel has no box to change only the first match, and it does not warn you when Find is empty. The phrase is sent to Google as you typed it. If nothing matches, the step still succeeds and the file is unchanged.

What the step passes on. Insert blocks passes on one item: the document ID, the Docs link, and a flag that the insert ran, together with whatever the previous step had already put on that item. Find or create document passes on one item with the ID, the title, the link and whether the file was created. Get document passes on the title, the link and the body. List documents passes on one item for the whole list. Later steps reach those fields through Step data references. One visit writes one document, from the first item it receives, not one block for each row of a list. To write one document per job, put the Google Docs step inside a Loop with batch size 1, described in Conditions, loops and approvals.

As a tool for an Intelligence step. Connect a Google Docs step to the Tools side of an Intelligence step and Actions becomes a searchable list where you can tick several. The AI decides when to call each one and fills in the fields itself. The canvas summary is the first action's name plus a count when there are more, such as Find or create document +2, not the full list of names.

Job finished

Job status changed

Draft the letter

GPT-5.6 Terra

Document tools

Find or create document +2

1

1. 1The Google Docs step attached to the Intelligence step as a tool.
2. 2Actions: the Docs actions the AI may call. Here, find or create, insert and replace.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval appears on every Google Docs step but 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 writes a document, put an Approval step in front of it.

Google Docs has no trigger of its own. Nothing in Drive starts a run when a document changes. An agent that should write a letter after a job is finished starts from a BigChange webhook, then a BigChange REST step if it needs the job, then the Google Docs step. An agent that should write on a timetable starts from a Schedule. An agent that should answer a question about a contract starts from Email received, then reads the document. The general picture for every system is in Start an agent from a system alert. Schedules are in Run an agent on a schedule. Mail is in Start an agent when an email arrives.

Job finished

Job status changed

Write the document

Insert blocks · Job letter, Riverside House

1. 1Connection on the BigChange webhook. This is the BigChange REST connection. Google Docs has no trigger of its own, and this webhook does not use the Google account.
2. 2Event types: the events that start a run. Only Job status changed is ticked.
3. 3Set this up in BigChange: the steps to follow in BigChange and the address to paste there.
4. 4Simulate webhook: runs the agent once with a sample alert. A Google Docs step after it still writes the document.

What the Google Docs step should read from the alert. A BigChange Job status changed alert hands on the ID of the job, which is a number. Document title is text, so you can build a name from a later Get job, for example a title that includes the job reference J-10482. The usual pattern is Get job in between, then an Intelligence step that turns the job into blocks, then Insert blocks with Bind blocks from incoming item ticked. Setting up the webhook, the full list of events, and the status filter are covered in BigChange REST in Agent Builder.

A schedule has no record attached. The first step after it has to go and fetch the jobs or the sites, usually with a list action, and a Loop if each one needs its own document. Email received hands the new message to the next step. The Google Docs step does not read that message by itself. Read the contract with Get document, and let an Intelligence step draft the reply. A simulated BigChange alert is a real run: Insert blocks, Replace text and Find or create document do change Drive, and the run uses credits. Alerts and schedules only start runs once the agent is published. Simulate webhook and Run now work on drafts.

Job finished

Job status changed

Fetch the job

Get job

Write the letter

GPT-5.6 Terra

Write the document

Insert blocks · Job letter, Riverside House

Job letter after a visit files a customer letter when a job is completed. Job finished is a BigChange webhook with Job status changed ticked, and the status filter in BigChange set to the completed statuses. Fetch the job uses Get job, so the agent has the contact, the site and the engineer: job J-10482, a boiler service at Riverside House for Northgate Housing, with Dylan Hughes on the job. Write the letter turns that into blocks: a heading, a short paragraph, and a table of what was done. Write the document is Insert blocks, with Document title set to Job letter, Riverside House and Bind blocks from incoming item ticked. The file is created in the office Drive the first time, and later runs append to the same file, so give each visit its own title if you do not want them stacked. Each finished job costs five credits or a little more. To email the link as well, add a Gmail Send email after it and put the document link in the message. The step cannot attach the file, because it has no download. The BigChange side of the alert is in BigChange REST in Agent Builder. Gmail's side of the message is in Gmail in Agent Builder.

Monday at 08:00

Weekly · Mon at 08:00

This week's jobs

List jobs

Each job

Batch size 1

Write the summary

GPT-5.6 Terra

Site summary

Insert blocks · Site summary

Weekly site summaries writes one document per job completed in the past week, at 08:00 every Monday. This week's jobs uses BigChange REST List jobs for that date window, and passes on one item per job: Riverside House on Monday, Harbour View Apartments on Wednesday, 12 High Street on Friday. Each job is a Loop with batch size 1, because a Google Docs step writes from the first item it receives and would otherwise ignore the rest. Write the summary drafts the blocks for that one job. Site summary is Insert blocks, with Document title set from the site name on the item, and the blocks bound from Write the summary. Twelve jobs mean twelve documents, and twelve passes of the Google Docs step. The list costs 1 credit however many rows it returns. The schedule is free. The Loop itself is free. Each document costs another credit, and the writing step is charged on every pass.

Contract question

Gmail · Inbox

Read the contract

Get document

Draft the reply

GPT-5.6 Terra

Reply

1 action enabled

Answer a contract question replies when a message about the Northgate Housing contract lands in the inbox. Contract question is Email received on the agent's Gmail connection, watching Inbox, with Subject contains set to contract. Google Docs does not watch the mailbox, and the Gmail sign-in is a different connection from the Docs sign-in, even when both are Google. Read the contract is Get document, with Document ID set to the contract that already lives in Drive. Find or create document is the wrong action here: a title that does not match creates a blank Doc. Draft the reply reads the body Get document passed on, writes a short answer from the sentence the message asked about, such as the response time at Riverside House, and does not invent a term that was not in the file. Reply is Gmail Reply to email, so the answer stays in the same conversation. The reply can include the document link. It cannot attach the file. Each matching message costs five credits or a little more. Gmail's side of the reply is in Gmail in Agent Builder.

A dry run is the safe way to try a Google Docs step that writes. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Read actions such as List documents and Get document call Google for real, so you see real file names and, for Get document, the body. Write actions are skipped when they are the step's own action. Insert blocks is skipped before it looks the file up, so a dry run does not create a blank Doc and does not append. Its summary starts with DRY RUN and says how many blocks would have been inserted, and that the change was not performed. Find or create document and Replace text are skipped in the same way. Their summaries name an internal action rather than the label you picked. You can ignore that name: Drive is left as it is. Run for real performs every action, including the writes.

{
  "handles": {
    "main": 1
  },
  "items": {
    "main": [
      {
        "dryRun": true,
        "documentTitle": "Job letter, Riverside House",
        "blocks": 6
      }
    ]
  }
}

Open a step in the run to see its output. The panel shows the first 50 items of each output, and later steps still receive all of them. A skipped insert does not add text to the file and does not create one. A dry run costs 1 credit for the whole run. A simulated BigChange alert is not a dry run, so test Insert blocks with Run now first. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

A Google Docs step costs 1 automation credit each time it runs successfully, whatever the action and however long the document. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. Google Docs has no trigger. A run started by a schedule, by Email received, or by a BigChange webhook still costs 1 credit for the run, like any other run, and those triggers themselves are free. Find or create document inside an insert is part of that same step. It is not a second credit.

Inside a Loop, the Google Docs step is charged on every pass, so a Loop over 40 jobs that writes a document for each one costs 40 credits for that step. One List documents is not a way to walk every file, because it returns a single list capped at 10. 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 Docs card in chat are separate. Connecting one does not connect the other. Chat works in the signed-in person's own files. An agent writes to the Drive connected on the agent. The agent's Drive permission is read only. Chat's card asks for a wider Drive permission so a chat can save a file into a folder.
• One Google account. The step uses the account chosen at Google's account page. A second Connect replaces it. There is no Account picker and no Add another account.
• Files land in My Drive. Find or create document, and an insert that looks up by title, creates a missing file at the top of that Drive. There is no folder box. A file in a shared drive is not included in the title search or the list.
• Google Docs only. The list, the title search and the create action use Google Docs. A Word file, a PDF or a Sheet in the same Drive is not listed and is not opened.
• Append, not replace. Insert blocks adds to the file that is already there. Run the same title twice and the letter appears twice. Use a title that changes with the job, or Replace text when you are filling a phrase you put in the file on purpose.
• One document per visit. A Google Docs step writes from the first item it receives. Per-job documents need a Loop with batch size 1. List documents returns one item with at most 10 files, not one item per file, and the panel has no box to raise that.
• Reading the words. Get document returns the title, the link and the body as Google stores it. There is no download and no PDF, so File Parser and an email attachment are not available from this step. Put the link in the message when you need someone to open the file.
• The look of the text. Bold, italic, underline, colour and font size can travel inside the blocks list from the previous step. The panel itself has no controls for them, and no place to type a block by hand.
• Replace is case sensitive. Site does not match site. Every match is replaced. There is no first-match-only switch.
• Per-user integration mode. Google Docs only works with the agent's own connection. The note under Integration mode in Settings names Outlook and Gmail, not Google Docs.
• Sign-in lasts 10 minutes. If you leave Google's page open longer than that, the sign-in expires and Connect has to be started again. The Drive permission you allow covers every file the account can open, for reading. The step writes Google Docs only.
• Published agents only. A schedule, a BigChange webhook and Email received only start runs once the agent is published. Run now works on drafts.

• Google Docs 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.
• Save this workflow as a draft first, then connect the account. Click Save draft, then Connect.
• Failed to start Google Docs connection. Centrus could not open Google. Try Connect again. If the message is Failed to connect Google Docs, the same applies.
• You return to the agents list and nothing explains the failure. The sign-in was refused, it expired after 10 minutes, or it was closed early. Nothing was saved. Open the agent and click Connect again.
• Connected, with no address. The sign-in succeeded, and a later refresh of the stored sign-in can clear the email that was saved with it. The step still uses that account. Disconnect and Connect again if you need the address back on the step.
• Set a document title (find or create) or a document ID before inserting blocks. Insert blocks had neither. Type a Document title, or paste a Document ID from an earlier step.
• A document title is required. Find or create document had a blank title.
• A document id is required. Insert blocks reached Google without an ID, which happens when the title search did not return one. The message uses a lower case id.
• Google Docs inserted the table, but the cell indexes could not be read back. The table was created and the words for the cells could not be placed. Open the Doc and check the table before you run the agent again, because a second run appends another copy.
• The letter appears twice. Insert blocks appends. The same title on a second run adds the blocks again. Change the title per job, or replace a known phrase instead.
• A blank Doc appears and the letter does not. The title was found or created, and the blocks list was empty. Tick Bind blocks from incoming item, and make sure the Intelligence step returns a blocks list. The panel will not warn you when that list is missing.
• A list stops at 10. List documents asks for 10 files, and the panel has no box to raise that. A Loop does not split that list into one item per file. Use Get document with an ID, or Find or create document when a missing title should create a blank Doc.
• The contract answer is thin or odd. Get document passes on Google's own structure for the body, not a flat transcript. Keep the question specific, and put the document ID of the file you mean on the step.
• Find did nothing. Replace text matches capitals. Site does not match site. An empty Find is still sent to Google.
• An alert never starts the agent. Google Docs does not listen for alerts. Check the trigger on the same agent: the agent must be published, and a BigChange webhook must be ticked and added in BigChange. See BigChange REST in Agent Builder.
• The step still uses the office account after you switch to Per-user. That is expected. Google Docs has no per-user credentials. Sign the account in on the agent, and leave Integration mode on Agent-level.
• The dry run summary names an internal action. Find or create document and Replace text do that. The change was not performed. Insert blocks says how many blocks it would have written.

The Google Docs step has 5 actions. Two read the account and three change it. Listing and the title search call Google Drive at https://www.googleapis.com/drive/v3. Creating, reading and updating the document call the Docs API at https://docs.googleapis.com/v1, as the account you connected on the agent. Insert blocks and Replace text both update with the same batch call. Find or create document lists Drive first, then creates with the Docs API only when nothing matches.