Skip to main content

Onedrive

View as Markdown

Exposes the Microsoft Graph drive API as agent tools: list and search files and folders, read metadata, download and upload content, create folders, copy/move/rename items, trash/restore, and manage sharing (links and permission grants). Operates on the acting user's OneDrive.

What it does​

An agent-invocable tool node — no data flows through lanes. Each operation is a @tool_function an agent calls on demand. Operational targets (item path or id, folder, permission id) are always tool-call parameters, never node config. Outputs are cleaned shapes (id, name, size, webUrl, folder/file, lastModifiedDateTime, parentReference.path), not raw Graph JSON.

Items are addressed by either a drive-relative path ('Reports/q3.pdf') or a drive item id — whichever the caller has on hand. The rule (shared looks_like_item_id() in client.py): the literal root, or a value that is 15+ characters drawn only from [A-Za-z0-9!] (Graph item ids look like 01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K), is treated as an item id; anything else — including a bare root-level filename such as report.pdf — is treated as a path under the drive root.

Configuration​

FieldNotes
microsoft.authTypeservice (Entra app, client credentials) or user (OAuth).
microsoft.tenantId / microsoft.clientId / microsoft.clientSecretEntra app credentials for service auth.
microsoft.userPrincipalNameActing user's UPN for service auth (app-only calls target /users/{upn}).
microsoft.oAuthButton / microsoft.userTokenUser OAuth: sign in to populate the access token.
onedrive.accessreadonly or write (default). Resolved by the shared ONEDRIVE spec in core/microsoft_access.py; scopes are never hand-entered.
onedrive.allowPublicSharingOff by default. Gates anonymous sharing links and invites to non-individual recipients.
onedrive.allowHardDeleteOff by default. Gates onedrive_permanently_delete; trash/restore are always available.

Access tiers → scopes​

TierScopeCapability
readonlyFiles.Readlist, search, read metadata, and download only
writeFiles.ReadWrite (+ requests User.ReadBasic.All at sign-in)full read/write (default); the optional directory scope backs the invite gate and is unavailable to personal accounts

Gate flags​

  • allowPublicSharing: off by default. When off, onedrive_create_sharing_link refuses scope="anonymous" links, and onedrive_invite looks up every recipient in the directory (GET /users/{email}) and refuses the whole invite if any recipient fails to resolve to an individual directory user — distribution lists and unresolvable addresses included. Fails closed: a lookup permission error is treated the same as a non-user address.
  • allowHardDelete: off by default. When off, onedrive_permanently_delete is refused; onedrive_trash is always available as the recoverable alternative (see the onedrive_restore limit below).

Tools​

  • Read: onedrive_list_items (a folder's children), onedrive_search, onedrive_get_metadata, onedrive_download (inline base64 ≤ 1 MiB, else a downloadUrl).
  • Write: onedrive_upload (simple PUT ≤ 4 MB, else a chunked resumable session), onedrive_create_folder, onedrive_copy, onedrive_move, onedrive_rename.
  • Trash / restore / delete (write): onedrive_trash, onedrive_restore, onedrive_permanently_delete (gated by allowHardDelete).
  • Sharing (write): onedrive_create_sharing_link (gated by allowPublicSharing for anonymous links), onedrive_list_permissions (read-only), onedrive_invite (gated by allowPublicSharing; recipients must resolve to individual directory users otherwise), onedrive_delete_permission.
  • Diagnostics: onedrive_check_connection verifies that granted OAuth scopes cover the configured access tier.

Setup​

Authenticate with either an Entra app (microsoft.tenantId / microsoft.clientId / microsoft.clientSecret / microsoft.userPrincipalName, client-credentials flow) or user OAuth (click sign-in to populate microsoft.userToken). See microsoft-oauth.md for the Entra app / consent setup shared by every Microsoft 365 tool service. The Graph permissions differ by auth mode:

Auth modeTierGraph permissionInvite directory lookup (allowPublicSharing off)
User OAuth (delegated)readonlyFiles.ReadUser.ReadBasic.All (requested at sign-in; unavailable to personal accounts)
User OAuth (delegated)writeFiles.ReadWriteUser.ReadBasic.All
Entra app (application, admin consent)readonlyFiles.Read.AllUser.Read.All
Entra app (application, admin consent)writeFiles.ReadWrite.AllUser.Read.All

Application permissions always require admin consent. The directory-lookup permission is only needed when onedrive.allowPublicSharing is off and the agent calls onedrive_invite; without it the invite fails closed with a hint naming the missing scope.

Limits​

  • onedrive_copy runs asynchronously on Graph's side; the tool returns once the copy is accepted, not once it completes.
  • onedrive_upload chunks large files at 5 MiB per PUT to the resumable upload session, per Graph's recommended chunk size.
  • Rate limits are per Entra app / tenant; the node retries 429/5xx with exponential backoff (chunked-upload PUTs included — they are idempotent by Content-Range).
  • onedrive_restore is OneDrive Personal only — Microsoft Graph does not support POST /drive/items/{id}/restore for work or school accounts. The tool refuses up front under Entra app (service) auth; a work/school user OAuth account surfaces Graph's own error. Use the OneDrive web recycle bin instead.

Examples​

An agent uploads a report, then shares it with a named colleague:

onedrive_upload  { "path": "Reports/q3.pdf", "content_base64": "..." }
onedrive_invite  { "item": "Reports/q3.pdf", "emails": ["alex@contoso.com"],
                    "role": "read" }

Upstream docs​

Troubleshooting​

  • Scope / 403 errors: call onedrive_check_connection; if scopes are missing, disconnect and reconnect the Microsoft account (user auth) or grant/consent the Entra app permission (service auth) at the required tier.
  • access is read-only: write tools raise MicrosoftAccessError; raise onedrive.access to write.
  • Sharing/invite refused: anonymous links, and invites to any recipient that doesn't resolve to an individual directory user (including a lookup permission error), need onedrive.allowPublicSharing enabled; permanent delete needs onedrive.allowHardDelete enabled.
  • Item not found: confirm whether the caller meant a path or an item id — a value without / is always treated as an item id, never a bare root-level filename.
Last updated on