Skip to main content

​
SharePoint Export (export_to_sharepoint)

This document covers export_to_sharepoint (display name “SharePoint Upload”), the tool that uploads a file to a SharePoint document library or a user’s OneDrive and optionally sets the file’s metadata columns.

​
When to use

Use this tool when an agent has produced or fetched a file (generate_file, python_code, extraction output, platform storage) and it must land in SharePoint. Use import_from_sharepoint for the opposite direction. Where the destination library has metadata columns that a downstream system reads — a case reference, a review status — set them with column_values in the same step, so the file is never left in the library without them.

​
Authentication and enablement

The tool uses the workspace’s SharePoint connector (integrations.service_name = 'sharepoint'). Its OAuth token is injected by the platform and excluded from the LLM-visible schema. Microsoft Graph calls go through the audited HTTP client with firehose.ProviderSharePoint. The tool registers only when SHAREPOINT_CLIENT_ID is configured. DefaultEnabled is false, so enable it explicitly on each agent that needs it. Writing metadata columns needs write access to the document library’s list items, not only to the drive.

​
Inputs

  • file_url (required): URL of the file to upload (platform storage URL, presigned URL, or any HTTP/HTTPS URL).
  • file_name (required): Destination filename.
  • site_name: SharePoint site display name, fuzzy-matched against the sites the token can see. Omit to upload to the user’s OneDrive.
  • drive_name: Document library within that site. Defaults to the site’s first library.
  • folder_path: Slash-separated path, created if it does not exist. Omit for the library root.
  • mime_type: Defaults to the type inferred from the file_name extension.
  • column_values: Optional metadata columns, as a JSON object string keyed by column API name — for example {"CaseNumber":"00012345","ReviewStatus":"Verified"}.
column_values is a JSON string rather than a nested object because a library’s columns are per-tenant and cannot be declared in the schema, and Gemini’s function-calling rejects an object property with no declared sub-properties. A column’s display name is accepted in place of its API name and is resolved to the API name before the write; the outcome records that it was matched that way.

​
Upload path

  • Files up to 4 MB are uploaded with a single PUT .../content.
  • Larger files go through a resumable upload session in 10 MB chunks (Graph requires a multiple of 320 KiB), with inclusive Content-Range headers.
Graph calls retry up to 5 times on 408, 429, 500, 502, 503, and 504. When the response carries Retry-After, that interval is waited out instead of the exponential schedule, capped at 60 seconds. The client carries no blanket timeout. Each call sets its own deadline instead: 2 minutes for the small JSON calls (drive and site lookup, folder resolve and create, column definitions, the metadata PATCH) and 8 minutes for a call carrying file bytes. Both are sized to clear a throttled retry chain rather than a single attempt, so a throttled request is not lost to its own deadline part-way through backing off, and a hung read is not held open for as long as an upload. A shorter deadline from the caller still wins.

​
Metadata outcome

The upload and the metadata write are two Graph calls. SharePoint rejects the entire listItem/fields PATCH when one column is unrecognised, and its error names only the first offender, so the tool reads the library’s column definitions first, sends only the columns the library will accept, and reports the rest individually. metadata_status in the result is one of: metadata_columns carries one entry per requested column: applied, rejected (never sent — unknown column, read-only column, or two keys resolving to the same column), or failed (sent, but the PATCH did not succeed). metadata_error holds the Graph error when the PATCH itself failed. A metadata failure does not mark the step as failed: the file is already in SharePoint and a retried step would upload it a second time. The failure is reported instead — in metadata_status, in _meta, and as a warning line in the text result. Treat partial and failed as an incomplete export and fix the column names; re-uploading the file does not fix them. When the library’s column definitions cannot be read, every requested column is sent and Graph decides, so the outcome is applied or failed with Graph’s own error rather than a per-column breakdown. Metadata columns belong to a SharePoint document library, so column_values goes with a site_name. A OneDrive destination (site_name omitted) is not rejected up front: the columns are attempted and whatever Graph answers is reported. What that answer is has not been verified against a live personal drive — OneDrive for Business is itself backed by a document library and may well accept the write. Either way the outcome is reported rather than quietly dropped, which is the point of the reporting.

​
Output

The structured result contains file_id, file_name, file_url, mime_type, file_size, drive_id, folder_path, completed_at, and the metadata fields above.

​
Errors

  • Missing file_url or file_name, and a malformed column_values string, fail validation before anything is uploaded.
  • A missing access token, an unavailable file-storage service, an empty download, and an unresolvable site or library return structured tool errors.
  • Upload failures (after retries) return a structured tool error; metadata failures do not — see above.