Grounding Declarative Agents with SharePoint

When your agents need to work with large, evolving document libraries that already live in SharePoint, embedded knowledge isn’t the right fit. Your organization’s real brain lives in SharePoint document libraries, and the OneDriveAndSharePoint capability lets your agent tap directly into that knowledge with full permission enforcement, live content, and source citations.

Why SharePoint Grounding Changes Everything

Grounding gives an AI model access to specific, authoritative data so responses are rooted in facts rather than training knowledge. Without it, your agent guesses. With it, the agent retrieves actual documents and synthesizes answers with citations.

SharePoint grounding stands out for four reasons:

• Scale: You’re not limited to 10 files. Point at an entire document library, a site, or multiple sites across your tenant.
• Living content: SharePoint documents get updated. Your agent always reads the latest version, not a stale snapshot you uploaded three months ago.
• Permission enforcement: This is the killer feature. The agent respects SharePoint’s existing access control. If a user doesn’t have permission to read a document, the agent won’t surface it. No data leakage. No extra configuration. It just works.
• Citations: Every answer includes clickable references back to the source document. Your users can verify the information themselves.

No RAG pipeline. No embeddings to manage. No vector database to maintain. You point the agent at a URL and the platform does the rest.

Configuring OneDriveAndSharePoint

For the Zava Insurance HR Buddy, I have a SharePoint site called HR with a document library called Onboarding containing our three core documents. Instead of embedding copies in the app package, we’ll point the agent at the library directly.

The simplest approach uses items_by_url to point at a SharePoint URL:

{
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://zavainsurance.sharepoint.com/sites/HR/Shared Documents/Onboarding"
        }
      ]
    }
  ]
}

One capability, one URL.

You can also point at multiple sources:

{
  "name": "OneDriveAndSharePoint",
  "items_by_url": [
    {
      "url": "https://zavainsurance.sharepoint.com/sites/HR/Shared Documents/Onboarding"
    },
    {
      "url": "https://zavainsurance.sharepoint.com/sites/IT/Shared Documents/New Hire Setup"
    }
  ]
}

Each entry in items_by_url can scope to a site, a document library, or a specific file.

Using Site IDs and List IDs for Precision

For more complex scenarios, or when URLs might change, you can reference SharePoint content using items_by_sharepoint_ids. This approach uses stable GUIDs that won’t break if someone renames a site or moves a library:

{
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_sharepoint_ids": [
        {
          "site_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "web_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "list_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
        }
      ]
    }
  ]
}

You can also scope to a specific folder or document within a list by adding unique_id:

{
  "items_by_sharepoint_ids": [
    {
      "site_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "web_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "list_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "unique_id": "d4e5f6a7-b8c9-0123-defa-234567890123"
    }
  ]
}

How to Get the Right URL

This trips people up more often than you’d think. The URL you need is the SharePoint site or library URL, not the URL from your browser’s address bar when you’re viewing a document.

The quickest approach:

1. Navigate to the document library in SharePoint
2. Look at the URL in your browser; it should look like https://yourtenant.sharepoint.com/sites/YourSite/Shared Documents/YourFolder
3. Copy everything up to and including the folder path you want to scope

Permission Enforcement: The Enterprise Superpower

When your agent retrieves content from SharePoint, it doesn’t bypass any permissions. The platform checks the current user’s access against SharePoint’s permission model before returning any content. If the user asking the question doesn’t have read access to the Benefits Guide (maybe they’re a contractor on a limited permission set), the agent simply won’t include that document in its response.

No configuration needed; SharePoint’s existing security trimming applies automatically.

Point the agent at a broad library with mixed permission levels, and each user only gets answers based on what they’re allowed to see.

For Zava Insurance, this matters a lot. The Onboarding library has documents that all new hires can see, but the HR site also has folders with compensation data, performance reviews, and org restructuring plans. By pointing the agent at the Onboarding folder specifically, we scope the content appropriately, and even if someone tried to ask about compensation data, the permission model would prevent leakage anyway. Defense in depth, handled by the platform.

Citations: Trust Through Transparency

When the agent answers a question using SharePoint content, every response includes citations: clickable references linking directly to the source document.

Ask the HR Buddy “How many PTO days do I get?” and the response looks something like:

That [1] links right back to the Employee Handbook in SharePoint. Users can click through and verify the information themselves, which is essential for driving adoption beyond the initial demo.

Citations also create an accountability chain. If the agent ever surfaces incorrect information, you can trace exactly which document it came from and fix the source.

The Value You Just Unlocked

A few lines of JSON gave us:

• Eliminated file size limits: No more cramming documents into 1 MB embedded files
• Connected to living documents: Content updates in SharePoint are immediately available to the agent
• Enforced enterprise security: Every response respects the user’s SharePoint permissions
• Added source citations: Users can verify every answer with one click
• Removed infrastructure overhead: No RAG pipeline, no embeddings, no vector database

The agent went from a chatbot with static files to an enterprise knowledge worker backed by your organization’s document infrastructure, with zero orchestration code.

Resources

• OneDriveAndSharePoint Capability Reference
• Declarative Agents Overview
• Microsoft 365 Agents Toolkit
• Content Sources for Declarative Agents