Skip to main content

OneDrive for Business Integration

Connect OneDrive for Business to enable AI agents to search, read, edit, and create documents in users' OneDrive accounts using your existing Microsoft 365 authentication.

Overview​

OneDrive for Business Integration allows your AI agents to perform document operations on users' OneDrive for Business accounts. Agents can search for documents by name or content, read file contents (including Office documents), update existing text files, and create new text documents. Because the integration uses your existing Microsoft 365 Entra (Azure AD) application, there is no per-user OAuth flow required.

Each agent execution is scoped to a single user's OneDrive — the system automatically determines whose OneDrive to access based on who triggered the agent (the email sender or chat user). Agents cannot access other users' OneDrive accounts.

Use Cases​

  • Meeting Summaries - Email agent saves meeting notes to the sender's OneDrive after processing a meeting recap email
  • Document Research - Research agent reads reference documents from a user's OneDrive to build comprehensive answers
  • Report Generation - Operations agent creates weekly reports and saves them to a user's OneDrive
  • Project Document Search - AICOS agent searches for project documents in the Business Owner's OneDrive to gather context for goals and tasks
  • Content Updates - Agent edits a shared status document to reflect the latest project milestones

How It Works​

Email/Chat Trigger          Tool Factory              Agent Operations
        |                        |                          |
        v                        v                          v
+-----------------+       +-----------------+        +-----------------+
| Sender's email  |  ->   | Domain check +  |  ->    | Search, Read,   |
| identified      |       | scoped tools    |        | Edit, and Save  |
|                 |       | created         |        | in sender's     |
|                 |       |                 |        | OneDrive        |
+-----------------+       +-----------------+        +-----------------+

The integration leverages the same Entra application that your organization consented to during onboarding. It uses application-level permissions (Files.ReadWrite.All) to access OneDrive for Business accounts within your Microsoft 365 tenant. Tools are assigned to agents as a group via the "OneDrive" Tool Group, and are automatically scoped to the appropriate user at execution time.

Getting Started​

Prerequisites​

Before enabling OneDrive:

  1. Microsoft 365 Organization - Your organization must use Microsoft 365 with OneDrive for Business
  2. Entra App Consent - The Outermind Entra application must be consented in your tenant (completed during onboarding)
  3. Graph Permission - The Files.ReadWrite.All application permission must be granted to the Entra app
  4. Admin Access - You must be a Control Bridge administrator to enable the integration
info

OneDrive for Business Integration uses application permissions, not delegated permissions. While the app technically has access to any user's OneDrive in your tenant, each agent execution is scoped to a single user's OneDrive determined by the email sender or chat user. Agents cannot access arbitrary users' OneDrive accounts. Only OneDrive for Business accounts are supported; personal OneDrive accounts are not accessible.

Step 1: Enable OneDrive​

  1. Navigate to Build > Connections > OneDrive
  2. Toggle Enable OneDrive Integration to on
  3. Click Save Changes

When enabled, the system creates four OneDrive tools and an "OneDrive" Tool Group containing them.

Step 2: Test Connection​

  1. On the OneDrive configuration page, click the Test Connection button
  2. The system verifies that:
    • The Entra app has the required Files.ReadWrite.All permission
    • The Microsoft Graph API is reachable
    • OneDrive for Business is accessible in your tenant
  3. Confirm you see a success message
warning

If the connection test fails, verify that the Files.ReadWrite.All (Application) permission has been granted and admin-consented in your Azure Portal under App registrations > API permissions.

Step 3: Assign OneDrive Tools to Agents​

OneDrive tools are assigned to agents via the "OneDrive" Tool Group:

  1. Go to Build > AI Agents > Agents
  2. Edit the agent that should use OneDrive
  3. Go to the Tools tab
  4. In the Tool Groups section, enable the OneDrive group
  5. Save the agent

All four OneDrive tools (search, read, edit, save) are assigned together as a single unit. Any agent with the OneDrive tool group enabled can use all four operations.

tip

OneDrive tools are only available when the agent is triggered by an email or chat from someone on one of your organization's business domains. If an external sender (e.g., a customer) triggers the agent, OneDrive tools are not included in that execution.

Tool Scoping​

OneDrive tools are automatically scoped to a specific user's OneDrive at execution time. The agent does not choose whose OneDrive to access — the system determines this based on context:

Agent TypeWhose OneDriveDetails
Email agentsEmail senderThe person who sent the email that triggered the agent
Chat agentsChat userThe person who initiated the chat conversation
CAIOOBusiness Owner + VIPsConfigured Business Owner and VIP users from CAIOO settings
Scheduled agentsNot availableOneDrive tools are not injected for scheduled executions

Domain requirement: The target user's email domain must match one of your organization's verified business domains. If an external sender triggers an email agent, OneDrive tools are not added to that execution.

This scoping ensures:

  • Each execution can only access one user's OneDrive
  • Agents cannot accidentally read or write to the wrong person's files
  • External senders' OneDrive accounts are never accessible

Available Tools​

When OneDrive is enabled, four tools are created and grouped under the "OneDrive" Tool Group.

Search for documents in the scoped user's OneDrive by name or content. Returns metadata only (file names, IDs, paths) — not file content.

ParameterTypeRequiredDescription
querystringYesSearch query (matches file names and content)
folderPathstringNoLimit search to a specific folder path
fileTypesstring[]NoFilter by file extensions (e.g., ["txt", "md"])
limitnumberNoMaximum results to return (default: 10)

Example use: "Search for meeting notes from the Q4 review"

{
  "query": "Q4 review meeting notes",
  "fileTypes": ["txt", "md"],
  "limit": 5
}

2. OneDrive Read (onedrive_read)​

Read the content of a document. You can identify the file by its OneDrive file ID or by its path. Supports any file type — Office documents (docx, xlsx, pptx) are returned as extracted text.

ParameterTypeRequiredDescription
fileIdstringNo*OneDrive file ID (from search results)
filePathstringNo*File path (e.g., /Documents/notes.txt)
offsetnumberNoByte offset to start reading from (default: 0)
limitnumberNoMax bytes to return (default: 100KB)

*Either fileId or filePath is required.

Example use: "Read the project plan document"

{
  "filePath": "/Documents/project-plan.md"
}
info

Files larger than 100KB are truncated by default with a notice showing the total file size. The agent can use offset and limit parameters to page through larger files when needed (e.g., for editing).

3. OneDrive Edit (onedrive_edit)​

Update the content of an existing text file. The new content replaces the file's current content entirely. Requires a file ID (not path) — the agent must search or read first to obtain the ID.

ParameterTypeRequiredDescription
fileIdstringYesOneDrive file ID of the file to edit
contentstringYesNew file content (replaces existing content)
expectedETagstringNoETag from a prior read. If provided, edit fails if the file changed since it was read.

Example use: "Update the status report with today's progress"

{
  "fileId": "01ABCDEF123456",
  "content": "# Status Report\n\nUpdated: 2026-02-10\n\n- Completed Phase 1\n- Started Phase 2",
  "expectedETag": "aQzlGMDFENjRCQTYzLTY0MDEtNDdCNi05..."
}
warning

The edit operation replaces the entire file content. To append or modify specific sections, agents should first read the file with onedrive_read, modify the content, then write it back with onedrive_edit. The expectedETag parameter provides stale-write protection — if another user modifies the file between the read and edit, the edit will fail safely instead of overwriting their changes.

4. OneDrive Save (onedrive_save)​

Create a new text file in the scoped user's OneDrive.

ParameterTypeRequiredDescription
fileNamestringYesName for the new file (include extension)
contentstringYesFile content
folderPathstringNoFolder path to save in (default: root)
conflictBehaviorstringNoWhat to do if file exists: rename (default), replace, or fail

Example use: "Save a summary of this week's email activity"

{
  "fileName": "weekly-email-summary.md",
  "folderPath": "/Documents/Reports",
  "content": "# Weekly Email Summary\n\n## Processed: 142 emails\n...",
  "conflictBehavior": "rename"
}

Security & Limitations​

Security​

  • Application permissions with scoped access - Uses app-only authentication via the existing Entra application. While Files.ReadWrite.All is a broad permission, each agent execution is scoped to a single user's OneDrive determined by the email sender or chat user. Graph API does not offer a more granular permission scope.
  • Domain-scoped injection - OneDrive tools are only available when the trigger user's email domain matches a verified business domain. External senders do not get OneDrive access.
  • Tenant isolation - All operations are scoped to the authenticated Microsoft 365 tenant
  • Stale-write prevention - The expectedETag parameter on edit operations prevents silent content destruction when files change between read and write
  • Audit logging - Every file operation (search, read, edit, save) is logged with the agent, user, file, and operation details
  • Text files only for writes - The integration validates file MIME types and only permits text-based formats for edit and save operations
  • File size limit - Files larger than 10MB are rejected to prevent abuse
  • Read truncation - File reads are truncated at 100KB by default to prevent excessive context usage

Supported File Types​

For reading: All file types are supported. Office documents (docx, xlsx, pptx) are returned as extracted text.

For editing and saving: Only text-based file types are supported:

ExtensionDescription
.txtPlain text
.mdMarkdown
.jsonJSON
.csvComma-separated values
.htmlHTML

Limitations​

  • Text files only for writes - Cannot edit or create Office documents (docx, xlsx, pptx); only text-based formats are supported
  • OneDrive for Business only - Personal OneDrive accounts (Microsoft consumer accounts) are not supported
  • Single-user scope per execution - Each agent execution is locked to one user's OneDrive (the email sender or chat user)
  • No folder operations - Cannot create, delete, or rename folders
  • No sharing management - Cannot modify file or folder sharing permissions
  • 10MB file size limit - Files exceeding 10MB are rejected
  • 100KB read default - Large file reads are truncated; agents can paginate for full content
  • Full content replacement - The edit operation replaces the entire file; partial edits are not supported at the API level
  • No scheduled agent support - OneDrive tools require an email sender or chat user context (except CAIOO)
  • Business domain required - External email senders do not trigger OneDrive tool availability

Troubleshooting​

Connection Test Fails​

Problem: The test connection button returns an error

Solutions:

  1. Verify the Files.ReadWrite.All (Application) permission is granted in Azure Portal under App registrations > API permissions
  2. Ensure admin consent has been granted for the permission (look for the green checkmark in Azure Portal)
  3. Check that your Microsoft 365 subscription includes OneDrive for Business
  4. Wait a few minutes after granting permissions, as Azure AD permission changes can take time to propagate

Agent Cannot Find OneDrive Tools​

Problem: OneDrive tools do not appear when editing an agent

Solutions:

  1. Verify OneDrive is enabled at Build > Connections > OneDrive
  2. Check that the "OneDrive" Tool Group exists by navigating to Build > AI Agents > Tool Groups
  3. Ensure you are assigning the Tool Group (not looking for individual tools in the tools list)
  4. Refresh the page

OneDrive Tools Not Available During Execution​

Problem: Agent has the OneDrive tool group assigned but tools are not used during execution

Solutions:

  1. Verify the email sender or chat user is from one of your organization's business domains (external senders don't get OneDrive tools)
  2. For scheduled agents, OneDrive tools are not available (except for CAIOO)
  3. Check the agent execution log for domain check messages

File Not Found Errors​

Problem: Agent receives "file not found" when trying to read or edit

Solutions:

  1. Verify the file exists in the sender's OneDrive (tools are scoped to the email sender's account)
  2. Check that the file path is correct (paths are case-sensitive)
  3. If using fileId, ensure the ID came from a recent search result (IDs can change if files are moved)
  4. Confirm the sender has a OneDrive for Business account provisioned

Permission Denied Errors​

Problem: Agent receives "access denied" or "insufficient permissions"

Solutions:

  1. Re-run the connection test at Build > Connections > OneDrive
  2. Verify the Entra app has Files.ReadWrite.All with admin consent in Azure Portal
  3. Check that the sender's OneDrive is not restricted by Conditional Access policies
  4. Ensure the sender's email belongs to the same Microsoft 365 tenant

Edit or Save Rejected​

Problem: Agent cannot edit or save a file

Solutions:

  1. Check the file extension is a supported text type (txt, md, json, csv, html)
  2. Verify the file size does not exceed 10MB
  3. For edit operations, confirm the fileId is valid and the file still exists
  4. For save operations with conflictBehavior: "fail", check if a file with that name already exists
  5. If using expectedETag, the file may have been modified since it was last read — the agent should re-read and retry

Best Practices​

Agent Instructions​

Help your agents use OneDrive effectively by including guidance in their instructions:

When working with OneDrive documents:
1. Always search before creating to avoid duplicates
2. When editing a file, read it first to preserve existing content and get the eTag
3. Use the expectedETag parameter when editing to prevent overwriting others' changes
4. Use descriptive file names with dates (e.g., "weekly-report-2026-02-10.md")
5. Save reports to organized folder paths (e.g., "/Documents/Reports/Weekly")

Configuration​

  • Test the connection after onboarding to verify permissions are correctly configured
  • Assign the OneDrive tool group only to agents that need document access

Security​

  • Review agent execution logs regularly to monitor file operations
  • Use descriptive folder paths to keep OneDrive accounts organized
  • Consider which agents truly need write access (edit and save) versus read-only access