Microsoft Excel in Agent Builder

The Microsoft Excel step lets an agent read and change a workbook in the OneDrive of a Microsoft account you sign in, as part of a run. It can find or create a workbook, list the workbooks on that drive, read a sheet as rows or as a range, append rows, update a range, add a worksheet, turn the used cells into a table, or add a chart. Each step does one thing, picked from 14 actions, and hands what Excel 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 rows · Jobs

2

AI builderMap

1. 1Microsoft Excel in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action and the worksheet, Append rows · Jobs.
3. 3Connection: the Microsoft account this agent uses. With more than one account, Account picks which OneDrive this step uses.
4. 4Actions: the one action this step performs. Append rows is selected.
5. 5Workbook name and Worksheet in Excel details. Here the week's jobs are appended to Jobs in the workbook Weekly jobs.

Centrus works alongside Excel. The workbook stays in OneDrive, and the agent reads and writes the file on the account you sign in. It does not replace the workbook, and it does not replace the job system that produced the rows. To ask about a workbook in a conversation rather than in an agent, see Microsoft Excel in chat. How connections differ across chat, Agent Builder and Train is in Integrations overview.

Open the agent in Agent Builder and find Microsoft Excel in the Integration group of the Nodes panel, under Outlook and Gmail. 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 worksheet too if you have typed one, for example Append rows · Jobs. 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

Microsoft Excel

No actions selected

2

1. 1Microsoft Excel 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 Microsoft Excel 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 rows · Jobs

The Excel connection belongs to this agent alone. It is separate from the Microsoft Excel 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 Microsoft Excel step on the agent, so you only sign in once per agent. An agent can hold more than one Microsoft account. Each Excel step then picks which OneDrive to use.

You sign in with Microsoft. 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 Microsoft 365 account whose OneDrive holds the workbooks, or should hold them, such as accounts@meridianfm.co.uk. Microsoft's page asks you to pick an account. Centrus asks Microsoft for permission to read and change files in that account, which is wider than Excel workbooks alone, and to read the signed-in profile. Later runs use that sign-in, so a Monday schedule can open the workbook without anyone sitting at the screen.

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 Microsoft Excel step. In the Details panel, open Connection and click Connect.
3. 3Centrus leaves Agent Builder and opens Microsoft's account page. Choose the account, then accept the permissions.
4. 4You return to the agent. Connection now reads Connected, followed by that account's address.

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

Several accounts. After the first account is connected, open Settings in the toolbar. Under Integrations, Add another account starts a second Microsoft sign-in and leaves the first account in place. Each row can be renamed, made primary, or disconnected on its own. On the step, Account appears once the agent has two or more Microsoft Excel accounts, or if the step still points at an account that has been disconnected. Primary account (default) follows whichever row is marked primary in Settings. A named row, such as john.martin@meridianfm.co.uk, locks this step to that OneDrive. The list on the step shows the primary row with (primary) after the address.

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 Microsoft Excel 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, and the note reads that it is only available for workflows triggered from chat or manually, because a scheduled run has no triggering user. Excel is not one of the systems that can use a person's own chat connection. 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 Microsoft Excel 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 Excel. Keep an agent that uses Excel 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 Excel connection stays on the agent. People you share it with cannot see or copy the sign-in. Their runs use the agent's OneDrive. 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, or add the accounts under Settings.

Disconnecting. Disconnect on the step removes Microsoft Excel from this agent. The confirmation reads Microsoft Excel disconnected from this agent. Every Excel step on the agent stops until someone signs in again. Other agents keep their own accounts, and the Microsoft Excel card in chat is left as it is. To drop one account and keep another, disconnect that row under Settings, then Integrations, rather than using Disconnect on the step.

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 Microsoft Excel account. There is no search box. The 14 names, in order, are Find or create workbook, List workbooks, Get workbook, Download workbook file, Ensure sheet & headers, Append rows, Export dataset to workbook, Read values, Read rows, Update values, Create sheet, Format cells, Create table and Add chart. The canvas summary becomes the action's name, plus the worksheet when you have set one.

The fields sit in Excel details, under the actions. The line there says you can use Step data references for an earlier step, or {{ item.json.field }} inside a loop. Which boxes appear depends on the action. Workbook name is the file name without .xlsx, a folder path such as Documents/Reports/Weekly jobs, or a link to a file already in that OneDrive. A name on its own is found anywhere in the drive. For Append rows, Find or create workbook, Export dataset to workbook, Create table and Add chart, a name that matches nothing is created: a bare name at the drive root, a folder path inside that folder. Read rows and Download workbook file never create a file. A missing name fails the read, and a download with nothing to fetch ends with the summary No workbook to download.

Append rows is the usual way to add lines to a log. Worksheet is the tab, and it defaults to Sheet1 if you leave it empty. Header row is a list of column names, added with Add column. Those names are written on the first row only when the sheet is new or the headers differ, and that row is made bold. Row values is one entry per column, left to right, added with Add cell. Each item that arrives becomes one spreadsheet row, so a list of twelve jobs becomes twelve rows in that one visit, written to Excel in batches of up to 200. Put {{ item.json.reference }} in a cell when the step sits inside a Loop. Bold this appended row is off unless you tick it, for a heading row rather than a data row. Replace existing rows on this tab each run (keep header) is off unless you tick it. Leave it off for a log that should grow. Tick it for a report tab that should be rewritten each Monday. Do not tick it on two Excel steps that share the same worksheet.

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 cell, into Workbook name, or into Range (A1 notation). In the weekly agent, the job reference, the site and the engineer come from the job item inside the Loop.

Find or create workbook only asks for Workbook name. It returns the file's id and address for a later step. You do not need it in front of Append rows, Ensure sheet & headers, Create table or Add chart: those find or create the workbook from Workbook name themselves. List workbooks shows no fields. On the main path it returns up to 50 workbooks, and never more than 200. Get workbook asks for Workbook ID, the OneDrive file id, and returns the sheet names and the file's address. Download workbook file asks for Workbook name and an optional Attachment file name, used when a later email step attaches the file. The help under Workbook name on a download still says a missing file will be created. It will not. The download only finds a file that is already there.

Ensure sheet & headers asks for Workbook ID, Worksheet, the column list under Header row, and When worksheet is missing. That last box starts on Reuse default Sheet1 if empty, else create new (Recommended). The other choices are Always create a new worksheet, Use existing Sheet1 instead, and Fail the step. Read values asks for Workbook ID, Worksheet and Range (A1 notation), such as A1:D20, and returns the cells that hold something inside that range. Read rows is the one to use when the next step should see each data row on its own. It asks for Workbook name or Workbook ID, Worksheet, and Header row as a number, default 1. It passes on one item per non-blank data row, with the real sheet row, the file id, and one field per header, using the header text as written. A date cell arrives as a year-first date. Every other cell arrives as the text the sheet shows. A header that contains a full stop or a vertical bar cannot be pasted into a later field: rename that column in the sheet. Update values asks for Workbook ID, Worksheet, Range (A1 notation) and Row values. It writes that one range. It does not add rows at the bottom: use Append rows for that.

Create sheet on the main path only shows Workbook ID. There is no box for the new tab's name, so the step cannot be filled in there. Use Append rows or Ensure sheet & headers, which create the worksheet from Worksheet, or attach Create sheet to an Intelligence step as a tool so the AI can supply the name. Format cells on the main path only shows Workbook ID, Worksheet and Range (A1 notation). There is nowhere to type a colour, a font or an alignment. Attach it to an Intelligence step if you need those, or format the sheet in Excel. Freezing panes, borders, merged cells and conditional formatting are not available. Export dataset to workbook asks for Workbook name and Worksheet. It writes a dataset an Ingest or Merge step has already staged, in chunks of 200, and passes on the workbook and the row count, not the rows themselves. Put that Ingest step directly in front of it. There is no dataset box on the Excel step. Dates are written day-first unless you are driving the step as a tool and ask for year-first. Create table asks for Workbook name, Worksheet, Show filter buttons (on unless you untick it) and Show totals row (off unless you tick it). It turns the used range into a table. Run it once after the rows exist, on the Loop's done side or straight after an export. Never put it inside a Loop that is still appending. Add chart asks for Workbook name, Worksheet, Chart type (it starts on Pie), Chart name (default Chart, replaced each run), Source range or Data start, Series by, Start cell, End cell, and Attach a picture of the chart for Word or PDF, which starts ticked. Put it after the rows exist, not inside an append Loop. Leave Series by on columns. Auto on a pie draws an empty circle. Cell addresses are bare, such as D1, with no sheet name in front.

What the step passes on. Read rows and List workbooks pass on one item per row or file. A single Append rows, Get workbook or Download workbook file passes on one item. 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 rows 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, or when Create table or Add chart must wait until the rows are in.

As a tool for an Intelligence step. Connect a Microsoft Excel 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 · Rates +2.

Question from chat

From chat

Answer the rate

GPT-5.6 Terra

Price tools

Read rows · Rates +2

1

1. 1The Microsoft Excel step attached to the Intelligence step as a tool.
2. 2Actions: the Excel actions the AI may call. Here, read rows, list workbooks and get a workbook.
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 Microsoft Excel 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 workbook, put an Approval step in front of it.

Microsoft Excel has no trigger of its own. Nothing in OneDrive starts a run when a cell changes. The run starts somewhere else, and the Excel step is one of the steps after that. Three starts cover almost every facilities workbook: 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 rows · Requests

1. 1Connection on Email received. This is the agent's Outlook connection, not the Excel connection. Excel 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 Excel 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 rows can put the sender and subject into Row values, or an Intelligence step can turn the message into a short line first and the Excel step can paste that line. A schedule hands on the time it fired, so the Excel 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 rows. 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: an Excel write still changes the workbook, 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 rows · Jobs

Make it a table

Create table · Jobs

Weekly job log appends the week's finished jobs to a workbook 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, with Workbook name set to Weekly jobs and Worksheet set to Jobs. 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. Make it a table uses Create table on the Loop's done side, with Show filter buttons left on and Show totals row left off, so it runs once after the rows exist. The list costs 1 credit. Each append costs another credit, so twelve jobs cost twelve credits for that step, and the table is one more. If you do not need a step between the jobs, connect the list straight to Append rows and skip the Loop: every job becomes a row in one visit, 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 rows · 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 rows, with Workbook name set to Email requests and Worksheet set to Requests. The columns are the time, the sender, the site and the summary. A message about a leaking plant room at 12 High Street becomes one row, and the sheet keeps growing because Replace existing rows stays off. 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 price list

Read rows · Rates

Answer the rate

GPT-5.6 Terra

Answer from a price list reads a workbook the accounts team already keep, and answers a question asked in chat. Priya Shah asks what the call-out is for a boiler service. Read the price list uses Read rows, with Workbook name set to Price list and Worksheet set to Rates. Header row stays at 1. The sheet is find-only: a mistyped name fails the step and does not create an empty workbook. Answer the rate reads the rows together and replies with the matching line, for example a boiler service call-out at £95.00. 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 Microsoft Excel 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 workbooks and Get workbook call Excel for real, so you see real rows. Write actions, Find or create workbook, Append rows, Update values, Ensure sheet & headers, Create sheet, Format cells, Create table, Add chart and Export dataset to workbook, are skipped. The step's summary starts with DRY RUN and says what it would have done, and nothing in the workbook changes. Download workbook file reads the file, so a dry run does download it. Run for real performs every action, including the writes.

{
  "handles": {
    "main": 18
  },
  "items": {
    "main": [
      {
        "Service": "Boiler service",
        "Charge": "Call-out",
        "Amount": "£95.00",
        "rowNumber": 2
      }
    ]
  }
}

Open a step in the run to see its output. A skipped append says it would have appended the rows and names the worksheet. 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 workbook, so try Append rows 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 Microsoft Excel step costs 1 automation credit each time it runs successfully, whatever the action and however many rows Read rows returns or Append rows writes in that visit. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. Excel 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 rows 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 Microsoft account and each person's Microsoft Excel card in chat are separate. Connecting one does not connect the other. A workbook created in chat is not automatically the workbook this step uses, unless it sits in the OneDrive you signed in on the agent.
• The signed-in OneDrive. The step uses the account chosen at Microsoft's account page. A bare Workbook name is found anywhere in that drive. A folder path is found, or created, in that folder. A link to a file that account can open also works. The sign-in can read and change files across that account, not only .xlsx files. This step does not ask you to pick a SharePoint site. For a document library, see SharePoint in Agent Builder.
• Several accounts, one picker. Account appears when the agent has two or more Excel accounts. Primary account (default) follows the primary row in Settings. A schedule has no person behind it, so it always uses the account on the agent.
• Per-user integration mode. Excel has no per-user credentials. The Connection note says the step still uses the agent's account. The run does not: every Excel 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 and the limit. A read over 1 MB still succeeds. Narrow the range, or use Export dataset to workbook after an Ingest step for a large list, rather than pulling the whole sheet into the run.
• List workbooks. On the main path there is no box for how many files to return. The step returns 50, and will not return more than 200.
• Append, then present. Append rows writes up to 200 rows in each call to Excel, still as one step visit. Create table and Add chart belong after the rows exist, on a Loop's done side or after the append, not inside the loop body. Replace existing rows clears below the header on the first visit of that step in the run.
• Headers. On Append rows and Ensure sheet & headers, Header row is the column names, and that row is bold. On Read rows, Header row is the row number. A date read back is year first. A header with a full stop or a vertical bar cannot be used in a later reference.
• Create sheet and Format cells. On the main path, Create sheet has no name for the new tab, and Format cells has no colour, font or alignment. Use Append rows or Ensure sheet & headers to add a tab, and format in Excel, or attach those two actions to an Intelligence step as tools.

• Microsoft Excel not connected for 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. Microsoft Excel not connected, without the words for this agent, is the chat card, not this step.
• Microsoft Excel account "primary" is no longer connected to this agent. The word in quotes is the account reference stored on the step, and it may be a longer id for an account you added later. The Account list also warns This node's account is no longer connected to this agent. Choose Primary account (default) or another account, or sign that one in again.
• Save this workflow as a draft first, then connect the account. Click Save draft, then Connect.
• Failed to start Microsoft Excel connection. Centrus could not open Microsoft. Try Connect again.
• The action is not supported in per-user mode. The agent is on Per-user. Excel 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.
• Excel node needs a workbook. Append rows, Ensure sheet & headers, Create table and Add chart need Workbook name or Workbook ID. Set one of them.
• The workbook was not found. Read rows looked through the connected OneDrive and did not find that name. Check the file name, the account under Account, or paste the file's link or its folder path. A read never creates a workbook.
• No workbook to download. Download workbook file found nothing. The help text under Workbook name says a missing name is created. For a download, it is not.
• A range is not a cell address. Range (A1 notation), Source range, Start cell or End cell includes a sheet name, or is not a cell such as A2:D2. Use the bare address. The worksheet is the Worksheet box.
• The export has no dataset. Export dataset to workbook needs an Ingest or Merge step directly in front of it. The message names an internal field. Wire the Ingest step in front, then run again. That ingest or merge dataset is not ready in this run means the Ingest step did not finish.
• No actions selected. The step has no action yet. Choose one under Actions.
• Create sheet does nothing useful. There is no box for the tab name. Use Worksheet on Append rows or Ensure sheet & headers.
• A list stops early. List workbooks stops at 50 on the main path, and at 200 at most. Read rows stops if the sheet is over 8 MB. Narrow the sheet rather than expecting every workbook on the drive.
• An alert never starts the agent. Excel 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 Microsoft Excel step has 14 actions. Five read the workbook and nine change it. They call Microsoft Graph at https://graph.microsoft.com/v1.0, as the Microsoft account connected on the agent. Where an action calls more than one path, the table gives the main one.