Skip to main content
This document covers import_from_onedrive (display name “OneDrive Import”), the tool that downloads a file from the connected user’s OneDrive into platform storage and returns a storage_url consumable by downstream tools. It is the inverse of export_to_onedrive; the Google Drive analogue is search_and_download_google_drive_file.

​
When to use — and when not

Use this tool when an agent needs one specific file, on demand, mid-task — e.g. “take the rates file from my OneDrive and reconcile it”. Do not use it as a polling loop over a folder: watching OneDrive/SharePoint locations for new files is what file_import triggers are for (they start tasks when files appear). The 250 MB limit is also a deliberate boundary — bulk or oversized ingestion belongs in the trigger pipeline. The import is a point-in-time copy. Later changes to the file in OneDrive are not reflected in the imported copy; re-import to refresh.

​
Authentication

Uses the OneDrive connector. The access token is injected by the platform and not shown as a per-run input. Registers only when OneDrive OAuth is configured. Outbound Microsoft Graph calls are audited. Off by default — enable it in the agent’s Tools panel.

​
Inputs

Exactly one of the four selectors is required:
  • file_path: exact slash-separated path in the connected account’s OneDrive (e.g. Data/CSV/report.csv). Preferred when the location is known — unambiguous and cheapest.
  • item_id: Microsoft Graph drive item ID, e.g. from a previous tool result.
  • file_url: a OneDrive/SharePoint sharing link, resolved via the Graph shares API. This is the only selector that reaches files living in someone else’s OneDrive that are shared with the connected account.
  • file_name: searches the drive by name.

​
Search semantics (file_name)

Deliberately conservative — this platform moves healthcare data, and importing a wrongly-guessed file into an agent’s context is worse than asking:
  • Exactly one case-insensitive exact name match → import it.
  • Zero exact matches → error listing up to 10 near-miss candidates (name, path, size).
  • Multiple exact matches (same name, different folders) → error listing the candidates and instructing a retry with file_path.
Folders are never matched. There is no fuzzy “best guess” pick.

​
Size limit

250 MB, enforced twice:
  1. From item metadata (size) — oversized files are refused before a single byte is downloaded, with the actual size in the error.
  2. Via io.LimitReader during download — the hard guarantee when metadata is stale or missing.
The limit is a package constant, not an LLM-facing parameter. Content is streamed to a temp file on disk (never fully buffered in memory) and the temp file is deleted after the storage upload.

​
Output

Structured result with file_id (platform files row ID), file_name, onedrive_url (web link to the source), storage_url (pass this to structured_data_extraction, csv, python_code, or export tools), mime_type, file_size, and completed_at. No inline/base64 file content is returned — downstream tools read from storage. On react tasks storage_url is surfaced as a ${VAR_N} task-variable reference (registered via FileURLForResult, like generate_file/combine_pdf/file_utils) rather than the raw S3 URL — the reference resolves automatically when the agent passes it to the next tool, and the long URL stays out of later steps. CodeAct tasks receive the raw URL. A files table row is registered (task/agent/workspace from execution context) so the import appears in the file lookup API like a manual upload; storage key format is onedrive/{file-id}-{sanitized-name}.

​
Errors

  • No selector, or more than one selector → validation error before any network call.
  • Path/item/share-link not found → structured error with the Graph failure.
  • Target is a folder → explicit “is a folder, not a file” error.
  • Oversized (metadata or actual) → structured error naming the 250 MB limit and pointing at file_import triggers.
  • Empty file (0 bytes) → explicit error rather than a useless empty import.