OneDrive in Agent Builder

The OneDrive step lets an agent file documents in a Microsoft account you sign in, and read them back, as part of a run. It can make sure a folder exists, upload each file it is given, list what is in a folder, or download a file and pass it on. Each step does one thing, picked from 4 actions. Ensure folder and Upload file change that OneDrive. List folder and Download file read it. Download file passes the file on, so a later step such as File Parser, or an email that attaches it, can use the bytes. 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 files or reads once that run is going.

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

Agents

Build modular AI workflows with reusable nodes

File job photos

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Job finished

Job status changed

Ensure the folder

Ensure folder · Sites/Riverside House

Each photo

Batch size 1

File the photo

Upload file · Sites/Riverside House

2

AI builderMap

1. 1OneDrive in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action and the folder, Upload file · Sites/Riverside House.
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. Upload file is selected.
5. 5Folder path in OneDrive details. File name is blank, so each photo keeps the name it arrived with.

Syncing OneDrive into the knowledge base is a different feature. That connection is on the Integrations tab of Train, and the files it brings in can be searched as sources. It does not sign this step in, and signing this step in does not sync a folder into Train. See Sync OneDrive.

Centrus works alongside OneDrive. The files stay in the account you sign in. The step does not replace OneDrive, and it does not replace the job system that produced the photos or the certificate. There is no OneDrive card on the Integrations page, and there are no OneDrive tools in chat. A question in chat can still use files that Train has already synced. How connections differ across chat, Agent Builder and Train is in Integrations overview.

Open the agent in Agent Builder and find OneDrive in the Integration group of the Nodes panel, under Google Docs and above SharePoint. 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 folder path too if you have typed one, for example Ensure folder · Sites/Riverside House. Download file has no folder path, so its summary stays Download file even after you set File path. It does not read 1 action enabled, which is what an Outlook or Gmail step shows.

Job finished

Job status changed

OneDrive

No actions selected

2

1. 1OneDrive 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 OneDrive 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

Ensure the folder

Ensure folder · Sites/Riverside House

Each photo

Batch size 1

File the photo

Upload file · Sites/Riverside House

The OneDrive connection belongs to this agent alone. It is separate from the OneDrive card on Train, so syncing files into the knowledge base does not connect the agent, and connecting the agent does not start a sync. One connection covers every OneDrive step on the agent, so you only sign in once per agent. An agent can hold more than one Microsoft account. Each OneDrive step then picks which drive 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 should hold the files, 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 that account can open, which is the whole drive and not one folder, to read the signed-in profile, and to keep that access until you remove it. Later runs use that sign-in, so a job finishing at 18:00 can file the photos 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 OneDrive 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 OneDrive 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 OneDrive 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 OneDrive 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. OneDrive 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 OneDrive 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 OneDrive. Keep an agent that uses OneDrive 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 OneDrive 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 sign-in is not. The copy is a draft, and Connection reads Not connected until you sign in again.

Disconnecting. Disconnect on the step removes the primary OneDrive account from this agent. The confirmation reads OneDrive disconnected from this agent. If another account is still connected, the oldest one becomes primary and the steps keep working against that drive. To drop one account and keep another, disconnect that row under Settings, then Integrations, rather than using Disconnect on the step. Files already in OneDrive stay there. The OneDrive card on Train 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 OneDrive account. There is no search box. The 4 names, in order, are Ensure folder, Upload file, List folder and Download file. The canvas summary becomes the action's name, plus the folder path when that box is filled in.

The fields sit in OneDrive details, under the actions. The line there says you can build paths from Step data references, or use {{ item.json.field }} for each incoming item, including inside a Loop. Which boxes appear depends on the action. Folder path is shown for Ensure folder, Upload file and List folder. It is the path under the top of that drive, such as Sites/Riverside House or Certificates/2026. The help under it says folders are created automatically when missing. That is true for Ensure folder and for Upload file. The same sentence is shown for List folder, and a list does not create anything: a path that is not there fails the step.

Ensure folder only asks for Folder path. It creates each missing part and leaves a folder that is already there as it is, so a second run reuses it. It passes on the folder's id, its address and the path. It does not upload a file. A path with nothing in it fails, and the message says a folder path with at least one segment is required. Characters that cannot sit in a folder name, such as a slash inside one part, a colon or an asterisk, are turned into spaces.

Upload file asks for Folder path and File name. It takes the file from the step before it. Every incoming item that carries a file is uploaded in that one visit, so a list of twelve photos becomes twelve files without a Loop, as long as the previous step has already fetched each one. A blank File name keeps the incoming file's name. If the name you type has no extension, the original extension is kept. A Folder path that is missing is created first, so this one step can both make the folder and file the document. There is no Folder ID box on the panel, so you aim the upload with Folder path rather than pasting the id from Ensure folder. Use Ensure folder when you want the folder in place once, before a loop, or when a later step should read the folder's address.

A file of that name is not replaced. The first clash is saved with (1) before the extension, the second with (2), and a third clash fails. A new run is a new upload, so filing the same certificate again adds (1) rather than overwriting the file already there. Put the date in the name, such as gas-safety 09/10/2026.pdf, when each run should keep its own copy. A retry of the same step in the same run does not upload a second copy. An item with no file is skipped. If none of the items have a file, the summary is No files to upload and the drive is left as it is.

List folder asks for Folder path. Leave it empty to list the top of the drive. It returns one item, holding up to 100 children. Each child has a name, whether it is a file or a folder, a size, an address and a modified time. It does not pass on one item per file, so a Loop after it does not walk the files one by one. There is no box for how many to return, and there is no second page, so a folder with more than 100 children is cut off at 100. The step will not return more than 200 even if a number were set behind the panel.

Download file asks for File path, under the top of the drive, such as Sites/Riverside House/gas-safety.pdf. The OneDrive page often labels the library Documents. Omit that word when the folder sits at the top of the drive. The file is passed on for the next step to read or attach, and the fields already on the item stay with it. The panel has one File path. It does not show a box for a file id, or for a list of further paths. A path that points at a folder fails: the message uses an internal action name and says the step wants a file. A missing file fails the step.

What the step passes on. List folder passes on one item. Ensure folder passes on one item, with the folder id, the address and the path added to whatever arrived. Upload file passes on one item per file it filed, with the address and the name it saved, and it drops the file bytes so a later approval does not have to carry them. Download file keeps the incoming fields and adds the file. To do something else to each photo before it is filed, put that work and Upload file inside a Loop, described in Conditions, loops and approvals. You do not need a Loop when the previous step has already handed over every file and Upload file should simply file them all.

As a tool for an Intelligence step. Connect a OneDrive 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 List folder +1.

Question from chat

From chat

Answer the question

GPT-5.6 Terra

Certificate tools

List folder +1

1

1. 1The OneDrive step attached to the Intelligence step as a tool.
2. 2Actions: the OneDrive actions the AI may call. Here, list a folder and download a file.
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 OneDrive 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 files a document, put an Approval step in front of it.

OneDrive has no trigger of its own. Nothing in the drive starts a run when a file arrives or a folder changes. The run starts somewhere else, and the OneDrive step is one of the steps after that. Three starts cover almost every facilities filing job: a Schedule Trigger (every Monday at 07:00, for a pack of certificates), Email received (a certificate lands in a folder, and the next step files the attachment), 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.

Job finished

Job status changed

Ensure the folder

Ensure folder · Sites/Riverside House

1. 1Connection on the BigChange webhook. This is the BigChange REST connection, not OneDrive. OneDrive has no trigger of its own.
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. An Upload file step after it still changes OneDrive.

What the OneDrive step should read from the start. A BigChange webhook hands on the id of the record that changed. Follow it with a BigChange Get job if you need the site, then Ensure folder with a path such as Sites/Riverside House, then the photos. An email trigger hands the new message to the next step: sender, subject, text and a list of attachments. Download the attachments with Outlook or Gmail, then Upload file. A schedule hands on the time it fired, so the OneDrive step usually follows a step that fetched the files. 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: Upload file and Ensure folder still change OneDrive, and the run uses credits. Try the write with a dry run first, as described under Test before it goes live.

Job finished

Job status changed

Read the job

Get job

Ensure the folder

Ensure folder · Sites/Riverside House

List the photos

List attachments

Each photo

Batch size 1

Download the photo

Download attachment

File the photo

Upload file · Sites/Riverside House

File the job photos puts a finished job's photos into a folder for that site. Job finished is a BigChange webhook with Job status changed ticked, and the status filter in BigChange set to the completed status. Read the job uses Get job so the agent has the site, for example Riverside House on job J-10482, a boiler service for Northgate Housing, with Dylan Hughes as the engineer. Ensure the folder uses Ensure folder with Folder path set to Sites/Riverside House, and it runs once. List the photos uses BigChange Web Services List attachments. Download the photo and File the photo sit inside a Loop, so each photo is fetched and then uploaded. File name is left blank, so plant-room.jpg keeps that name. A second run does not overwrite it: the next copy is saved as plant-room (1).jpg. Read the job, the list, the folder and each download and upload cost 1 credit each. The Loop itself is free. Twelve photos cost twelve downloads and twelve uploads. The BigChange side of the photos is in BigChange Web Services in Agent Builder.

Certificate received

Outlook · Inbox/Certificates

Download the files

Download attachments

File the certificate

Upload file · Certificates/2026

File email attachments saves what arrives in Inbox/Certificates. The trigger watches that folder on accounts@meridianfm.co.uk. Download the files is Outlook Download attachments, which passes each file on. File the certificate is Upload file, with Folder path set to Certificates/2026 and File name left blank, so gas-safety.pdf keeps that name. Upload file files every attachment from that email in one visit, so you do not need a Loop unless something else has to happen to each file first. The folder is created if Certificates/2026 is not there yet. A name already in the folder is not replaced. Each matching email costs 3 credits. The email trigger is free. Outlook's side of the download is in Start an agent when an email arrives.

Question from chat

From chat

Download the certificate

Download file

Read the certificate

Gas safety date

Answer the question

GPT-5.6 Terra

Answer from a certificate reads a PDF the accounts team already keep, and answers a question asked in chat. Priya Shah asks when the gas safety certificate at Riverside House is next due. Download the certificate uses Download file, with File path set to Sites/Riverside House/gas-safety.pdf. A mistyped path fails the step and does not create a file. Read the certificate is a File Parser step, which reads the file and pulls out the date the question asked for. Answer the question replies with that date, and does not invent one that was not in the file. The download costs 1 credit. File Parser and the answer cost at least 2 credits each. The chat that starts the run is covered in Run an agent from chat. File Parser is covered under Steps an agent can use.

A dry run is the safe way to try a OneDrive step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). List folder calls OneDrive for real, so you see the real names in that folder. Ensure folder and Upload file are skipped, and nothing in the drive is created or filed. Download file is also skipped: a dry run does not fetch the file, even though a download only reads. The step's summary starts with DRY RUN and says what it would have done. An upload says how many files it would have uploaded. An ensure names an internal action rather than Ensure folder. You can ignore that name: the drive is left as it is. Run for real performs every action, including the writes and the download.

{
  "dryRun": true,
  "wouldUpload": {
    "folderPath": "Certificates/2026",
    "fileName": "gas-safety.pdf"
  }
}

Open a step in the run to see its output. A skipped upload names the folder and the file and does not write them. A skipped download names the path and does not fetch it. List folder on a dry run is a real list, and its summary uses an internal action name rather than List folder. 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 drive, so try Upload file and Ensure folder 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 OneDrive step costs 1 automation credit each time it runs successfully, whatever the action and however many files Upload file writes in that one visit. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. OneDrive 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. The Loop itself is free. File Parser and an Intelligence step cost at least 2 credits each.

Inside a Loop, the step is charged on every pass, so a Loop over 12 photos that uploads each one costs 12 credits for that step. One Upload file visit is usually cheaper when every file has already been fetched and only needs filing. One Download file is one credit for the file on that path. 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 the OneDrive card on Train are separate. Connecting one does not connect the other. Files synced into Train are not automatically the files this step uses, unless they sit in the OneDrive you signed in on the agent. There is no OneDrive card in chat.
• The signed-in drive. The step uses the account chosen at Microsoft's account page. Folder path and File path start at the top of that drive. The sign-in can read and change files across that account, not only the folder you name. 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 OneDrive 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. OneDrive has no per-user credentials. The Connection note says the step still uses the agent's account. The run does not: every OneDrive action fails in that mode, and the message talks about sending mail. Keep the agent on Agent-level.
• Names. Upload file does not replace a file of the same name. It tries the name, then the name with (1), then (2), and then it fails. A retry inside the same run does not file a second copy. A new run does. Characters that cannot sit in a name are turned into spaces.
• List folder. On the main path there is no box for how many children to return. The step returns 100, in one item, and will not return more than 200. There is no second page. An empty Folder path lists the top of the drive. A missing folder fails the list. The help that says folders are created when missing does not apply to this action.
• Size. A list or a download whose result is over 8 MB fails, and the message names an internal action, states the size and states the limit. A result over 1 MB still succeeds. Upload file is one put of the whole file. There is no large-file session, so a file Microsoft refuses fails, and the message includes Microsoft's reason. An item with no file is skipped.
• Download file on a dry run. The download is skipped, so you do not get the bytes until Run for real. List folder does call OneDrive on a dry run. The canvas summary for Download file does not include File path.
• What stays in OneDrive. The step cannot delete, rename, move or share a file, and it cannot empty a folder. Those stay in OneDrive. A file that occupies the name you wanted for a folder will stop Ensure folder on that part of the path.

• OneDrive 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 Train connection does not count.
• OneDrive 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 OneDrive connection. Centrus could not open Microsoft. Try Connect again.
• The action is not supported in per-user mode. The agent is on Per-user. OneDrive 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.
• A folder path with at least one segment is required. Ensure folder has an empty Folder path. Type the path, such as Sites/Riverside House.
• No files to upload. The previous step did not pass a file, or every item was skipped because it had no bytes. Check the download in front of Upload file. The summary may also say it skipped a number of items without bytes. The drive is unchanged.
• Failed to upload file. Microsoft refused the put. A third file of the same name fails after (1) and (2) have been tried. Rename the file, or remove the older copies in OneDrive, then run again. A file Microsoft treats as too large for a single put fails here too.
• Failed to create folder. Ensure folder, or the folder Upload file creates from Folder path, was refused. Check the account under Account, and check that a file does not already use that folder name.
• Failed to list folder. List folder could not open that path. Check the spelling, the account, and that the folder exists. A list does not create it. An empty path lists the top of the drive instead.
• Set a file path under the drive root (or a file id) before downloading. Download file has an empty File path. The panel does not show a file id box, so type the path.
• OneDrive file lookup failed. The path does not match a file that account can open. Check File path, and omit Documents if that is the library name rather than a folder.
• The download pointed at a folder. The message names an internal action and says it targets a file, not a folder. Point File path at the file, or use List folder if you wanted the children.
• No actions selected. The step has no action yet. Choose one under Actions.
• The list stops at 100. List folder returns one page. A name that is missing may be further down the folder. There is no second page on this step.
• An alert never starts the agent. OneDrive 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 OneDrive step has 4 actions. Two change the drive and two read 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. {parent} is the folder the step has reached, {folderId} is a folder id, {fileName} is the file name, and {path} is the path under the top of the drive.