Skip to content

Connecting an AI Agent to SharePoint: Making Documents Searchable

For most organisations running Microsoft 365, SharePoint is where the working knowledge sits: standard operating procedures, proposal templates, project folders, manuals and meeting minutes. Turning that into an agent that answers questions raises three integration problems. How does the agent reach the content, how does it avoid showing people what they may not see, and how does it cope with file formats and metadata? This guide covers those three, as of November 2026.

What does connecting an AI agent to SharePoint involve?

It means giving an agent controlled read access to sites and document libraries so it can find the right passages and write an answer that cites them. In practice this almost always runs through Microsoft Graph, and the pattern is retrieval augmented generation: search first, then answer with sources attached.

Questions such an agent typically handles:

  • "What is the current torque value for assembly 4 in the latest work instruction?"
  • "Have we quoted a similar test rig before, and who wrote that proposal?"
  • "What did the steering committee decide about the delivery date last month?"

The general architecture of these systems, including chunking, embeddings, reranking and evaluation, is covered in Enterprise RAG: Architecture, Building Blocks and Pitfalls. App registration, Graph permissions in general and how a custom agent relates to Copilot are covered in Connecting an AI Agent to Microsoft 365. This guide stays with what is specific to SharePoint: indexing versus live search, permission trimming, and formats and metadata.

Should the agent use its own index or query SharePoint live?

There are two basic routes. With your own index, a service copies content, splits it into chunks and keeps it in sync through delta queries. With live search, the agent calls Microsoft's search at question time on behalf of the user. The first gives you control over retrieval quality; the second avoids copies and avoids having to replicate permissions yourself.

Route 1: your own index, synced with delta queries

The unit to sync is a document library, which Graph calls a drive. One site can hold several; GET /sites/{site-id}/drives lists them. For the first crawl and every later change, Microsoft points to the driveItem delta function:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/drive/root/delta

Your sync service follows @odata.nextLink until it receives an @odata.deltaLink, then stores that link. Calling it later returns only what changed in between. Deleted files come back with a deleted facet and must be dropped from the index. The documentation says to track items by id rather than by path, because renaming a folder does not resend its children. If an old token can no longer be served, the API returns 410 Gone with a link that restarts enumeration from scratch.

Rather than polling on a timer, Microsoft's guidance for scanning applications recommends webhooks. A subscription on the drive sends a notification, your service replies 202 Accepted straight away, then runs a delta query for the details. Microsoft also suggests a periodic delta run as a safety net, but no more than once a day. The cTag property tells you whether file content changed, so you only download again when it did.

Route 2: live search as the user

The Microsoft Search API searches SharePoint and OneDrive with delegated permissions, in the context of the signed-in employee. Microsoft states that results are scoped by the access controls on each item, so a user cannot find more through search than they could open directly. The agent sends a query with entityTypes such as driveItem or listItem, receives matching files and list items, and fetches their content where needed.

A related option is the Microsoft 365 Copilot Retrieval API. According to Microsoft it returns text chunks from the hybrid index that also powers Microsoft 365 Copilot, so you skip chunking and vector storage altogether. The documented constraints matter: at most 25 results per request, a query string of up to 1,500 characters, up to 200 requests per user per hour, semantic retrieval only for .doc, .docx, .pptx, .pdf, .aspx and .one, and lexical-only retrieval for everything else. It needs a Copilot licence for the user or pay-as-you-go billing, which Microsoft still calls a preview.

Side by side

CriterionOwn index (delta)Live search (Search/Retrieval API)
Copy of datayes, outside SharePointno
Permissionsyou replicate and maintain themenforced by SharePoint
Chunking and rankingfully under your controlset by Microsoft
Freshnessas good as your syncimmediate
Self-hosted model on own hardwarepossibleretrieval stays in Microsoft 365

Many organisations end up combining both. Live search covers broad questions across all sites, while a dedicated index serves the handful of libraries where answer quality and traceability matter most, such as quality procedures or a standards library.

How do you make sure the agent only shows permitted documents?

Permission trimming means every answer is built only from documents the person asking could open themselves. With live search, SharePoint handles it. With your own index you must store each document's access list and filter every query against the user's group memberships. This is the riskiest part of any SharePoint integration and deserves the most testing.

Keep app permissions narrow

An indexing service usually runs with application permissions and no signed-in user. Sites.Read.All opens every site in the tenant. The Selected permission scopes are narrower: Sites.Selected for individual sites, Lists.SelectedOperations.Selected for lists and libraries, and ListItems.SelectedOperations.Selected or Files.SelectedOperations.Selected down to folders and single files. Microsoft describes three conditions that must all hold: consent in Entra ID, an explicit grant on the resource with a role (read, write, owner or fullcontrol), and a token carrying the scope. Miss one and the app has no access.

POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
Content-Type: application/json

{
  "roles": ["read"],
  "grantedToIdentities": [{
    "application": { "id": "<app-id>", "displayName": "knowledge-agent-indexer" }
  }]
}

The same page warns that grants on lists, folders or files break permission inheritance, which counts against SharePoint's limits on unique permissions. Grants at site level do not.

If the agent runs with delegated permissions, the effective access is the intersection: the app can never exceed the user, and the user can never exceed, through the app, what the app was granted.

Replicating access in your own index

For a custom index you need the effective permissions of each document. The driveItem permissions endpoint returns direct and inherited permissions, with inherited ones marked by inheritedFrom. A caller who is not an owner only sees permissions that apply to them, so the indexing service needs sufficiently broad rights.

To avoid a separate call per document, delta supports two headers. Prefer: hierarchicalsharing returns sharing details only at the root of a permission hierarchy and on items with their own changes. Prefer: deltashowsharingchanges, combined with deltashowremovedasdeleted and deltatraversepermissiongaps, flags items that appear only because their permissions changed. Microsoft notes that processing permissions this way requires Sites.FullControl.All. That is a real trade-off: complete permission replication needs broad application rights. For webhooks, the prefer:includesecuritywebhooks header adds notifications when permissions change.

Store the allowed user and group IDs with each chunk and filter against the user's Entra ID group memberships before anything reaches the language model. Filtering afterwards is not enough: a model that saw a restricted passage can paraphrase it even if the source link is hidden.

Which file formats and metadata does the agent need to handle?

SharePoint libraries mix Word, Excel, PowerPoint, PDF, email files, pages and Loop components, usually alongside columns such as document type, status, effective date or project number. A useful agent extracts clean text and uses those columns as filters. Metadata is what separates a correct answer from one that quotes last year's draft.

Getting text out of files

Standard parsers cover Office files and PDFs that have a text layer. Graph's format conversion can also return many formats as PDF, including docx, xlsx, pptx, msg and loop, but only for files up to 2 MB. Larger files go through the regular /content download.

Common problems:

  • Scanned PDFs without a text layer are invisible until OCR runs. Microsoft says the Retrieval API does not use images or charts.
  • Tables in Excel or Word lose their structure when flattened. Store rows as "column: value" pairs instead.
  • SharePoint pages (.aspx) carry navigation and web parts; keep only the content area.
  • Versions and drafts end up next to the approved document unless you filter on status.

Using columns and metadata

Column values come from the list items endpoint with expand=fields:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items?expand=fields(select=Title,DocType,Status,EffectiveDate)&$filter=fields/Status eq 'Approved'

Microsoft notes that filtering works best on indexed columns and that only one indexed column can be filtered at a time. In your own index, keep the key columns as filterable fields next to the text. The agent can then narrow "the current work instruction" to status Approved and the latest effective date, instead of relying on text similarity alone. With the Search API, custom columns are only returned for the listItem entity type and only when they are configured as retrievable managed properties in the search schema.

What do you need in place before you start?

Before writing code, settle three questions: which sites and libraries are the source of truth, who maintains them, and who is allowed to see what. On the technical side you need an Entra ID administrator for app registration and consent, plus somewhere to run the index and the agent.

Content and ownership

  • A short list of libraries with named owners, not "all of SharePoint".
  • A rule for which version counts: a status column, an approved folder or versioning.
  • Tidy sharing. An agent surfaces whatever was technically accessible all along, and broadly shared folders become very visible.

Technology

  • An Entra ID app registration with the narrowest workable permissions (Sites.Selected rather than Sites.Read.All where possible).
  • For live search: delegated sign-in in the agent's front end, for example Teams or a web app.
  • For your own index: storage for text, vectors and access lists, a service handling delta and webhooks, and a public HTTPS endpoint for notifications.
  • A decision on where the language model runs. If content must stay on premises, a self-hosted model on your own hardware is an option; see Sovereign AI.

Operations

  • A User-Agent string in Microsoft's format NONISV|CompanyName|AppName/Version. According to the SharePoint throttling documentation, decorated traffic is prioritised over undecorated traffic.

What is a sensible step-by-step approach?

Start narrow: one library, one group of users, one set of real questions. Expand only once answers and permissions are right there. This keeps the risk of an access mistake small and shows early which formats and columns cause trouble.

  1. Collect questions. Gather 30 to 50 real questions from future users, each with the document that holds the answer. This becomes your test set.
  2. Pick a source. Choose one library with a clear owner and a status column.
  3. Set up access. Register the app, consent to Sites.Selected and grant the site with the read role.
  4. Choose a route. Try live search first. If hit quality is not good enough, build your own index on delta.
  5. Test permissions. Ask the same questions from two test accounts in different groups and confirm restricted documents are never cited.
  6. Evaluate answers. Run the test set and sort failures by cause: not found, wrong version, misread, badly phrased.
  7. Keep it current. Webhook plus a daily delta safety run, with monitoring of sync lag.
  8. Expand. Add libraries one at a time, each with its own test questions.

Step 1 is the one teams most often skip, and without it you end up tuning for questions nobody asks.

What are the limits and risks?

The biggest risks sit in the content rather than the code: oversharing, outdated documents and missing metadata. On top of that come platform limits such as SharePoint throttling, licensing conditions for the Retrieval API, and the effort of replicating permissions correctly in a custom index.

Oversharing becomes visible. The agent respects permissions, but it finds everything that is formally shared. A forgotten folder shared with the whole company suddenly shows up in answers. Review sharing on the chosen libraries before launch.

Throttling. Under load SharePoint returns 429 or 503 with a Retry-After header. Microsoft states that throttled requests still count against limits, and apps that ignore the header stay throttled longer or, in extreme cases, get blocked. Cost is measured in resource units: a delta call with a token or a file download costs 1, multi-item queries cost 2, permission operations cost 5. For tenants with up to 1,000 licences, Microsoft lists a default of 1,250 units per minute per app. An index that fetches permissions for every document separately can hit that ceiling on large libraries.

App-only search. If an app uses SharePoint search with Sites.Read.All and no user context, Microsoft says it can query all content, including users' private OneDrive files. Such queries are limited to 25 per second; delegated searches to 10 per second per user. For an agent answering employees, delegated search is nearly always the right choice.

Licence and preview dependency. The Retrieval API depends on Copilot licences or a pay-as-you-go preview whose terms may change. If you build on it, keep a fallback through the Search API or your own index.

When this approach does not fit. If the information you need lives mostly in drawings, scans without OCR, or line-of-business systems outside SharePoint, a SharePoint integration will not solve the problem. Sort out the data source first.

How do I get started?

Pick one library that people search often and that has a clear owner, such as work instructions or sales templates. Collect real questions, register an app with Sites.Selected, and test live search before you build an index of your own.

A realistic first milestone is an agent that answers one team's questions about one library with source links, where two test accounts with different rights demonstrably get different answers. That result tells you whether live search is enough or a custom index is worth the effort.

For how these agents are used in knowledge management, see AI agents for knowledge management; an overview of ready-made agent packages is on AI agents. To go deeper into custom index design, continue with Enterprise RAG; Graph access and Copilot basics are in Connecting an AI Agent to Microsoft 365.

Frequently asked questions

Do I need Microsoft 365 Copilot licences to connect my own agent to SharePoint?

No. Microsoft Graph, delta queries and the Microsoft Search API work without Copilot. Only the Copilot Retrieval API requires a Copilot licence per user or pay-as-you-go billing, which Microsoft currently labels as preview.

Is Sites.Read.All enough for a knowledge agent?

It works, but it lets the app read every site in the tenant. If the agent only needs a few libraries, Sites.Selected is the narrower choice: the app sees nothing until an administrator explicitly grants it a site.

How often should a custom index be refreshed?

As often as stale answers are acceptable. A common pattern is a webhook that triggers a delta query, plus a daily safety run, which is what Microsoft recommends for scanning applications.

Can the agent read scanned PDFs?

Only if the text is extracted with OCR first. Microsoft states that the Retrieval API does not use images or charts, and a custom index needs its own OCR step.

What happens when someone loses access to a folder?

With live search the change applies immediately because SharePoint does the filtering. With a custom index you have to detect the change through delta or security webhooks and update the access list stored with each chunk.

Sources

  1. Microsoft Graph: driveItem delta learn.microsoft.com
  2. Microsoft: Best practices for discovering files and detecting changes at scale learn.microsoft.com
  3. Microsoft Graph: Overview of Selected Permissions in OneDrive and SharePoint learn.microsoft.com
  4. Microsoft Graph: Use the Microsoft Search API to query data learn.microsoft.com
  5. Microsoft 365 Copilot Retrieval API Overview learn.microsoft.com
  6. Microsoft: Avoid getting throttled or blocked in SharePoint Online learn.microsoft.com
  7. Microsoft Graph: Convert to other formats learn.microsoft.com
  8. Microsoft Graph: List items learn.microsoft.com
  9. Microsoft Graph: List who has access to a file learn.microsoft.com