Use SharePoint content with agent API

Learn how to ground Microsoft Foundry agents with SharePoint content using the agent API. Connect to SharePoint sites or folders, use identity passthrough, and keep enterprise access controls intact.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

• This article describes the Microsoft SharePoint tool for Foundry Agent Service. For information on using and deploying SharePoint sites, see the SharePoint documentation.
• See best practices for information on optimizing tool usage.

Use the SharePoint tool (preview) for SharePoint grounding in Microsoft Foundry Agent Service by retrieving content from a SharePoint site or folder (for example, contoso.sharepoint.com/sites/policies). When a user asks a question, the agent can invoke the SharePoint tool to retrieve relevant text from documents the user can access. The agent then generates a response based on that retrieved content.

This integration uses identity passthrough (On-Behalf-Of) so SharePoint permissions continue to apply to every request. For details on the underlying Microsoft 365 Copilot Retrieval API integration, see How it works.

Before you start: The SharePoint tool requires user identity authentication (no app-only/service principal), your SharePoint site and Foundry agent must be in the same tenant, and only one SharePoint tool per agent is supported. The tool doesn’t work when the agent is published to Microsoft Teams. See Limitations for the full list.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

• Eligible license or pay-as-you-go model:
  • Developers and end users have a Microsoft 365 Copilot license, as required by the Microsoft 365 Copilot Retrieval API.
  • If developers and end users don’t have a Microsoft 365 Copilot license, you can enable the pay-as-you-go model.
• Developers and end users have at least Foundry User RBAC role assigned on the Foundry project. For more information about Azure role-based access control, see Azure role-based access control in Foundry.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• Developers and end users have at least READ access to the SharePoint site.
• Ensure your SharePoint tenant and your Foundry project are in the same Microsoft Entra tenant. Cross-tenant token exchange isn’t supported.
• The required SDK package installed:
  • Python: pip install "azure-ai-projects>=2.0.0"
  • C#: Install the Azure.AI.Projects NuGet package
  • TypeScript/JavaScript: npm install @azure/ai-projects
  • Java: Add com.azure:azure-ai-agents:2.0.0 to your pom.xml
• Environment variables configured:
  • FOUNDRY_PROJECT_ENDPOINT: Your Foundry project endpoint URL
  • FOUNDRY_MODEL_DEPLOYMENT_NAME: Your model deployment name (for example, gpt-4)
  • SHAREPOINT_PROJECT_CONNECTION_ID: Your SharePoint connection ID in the format /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}
  • For REST samples: AGENT_TOKEN
• See the quickstart for additional authentication setup details.

Parameters

The SharePoint tool uses your project connection to determine which SharePoint site or folder it can retrieve from.

Parameter	Required	Notes
type	Yes	Use sharepoint_grounding_preview.
sharepoint_grounding_preview.project_connections[].project_connection_id	Yes	Use the value of SHAREPOINT_PROJECT_CONNECTION_ID.

If you need to create a SharePoint connection for your project, see Add a new connection to your project.

Code example

Limitations

• The SharePoint tool only supports user identity authentication. App-only (service principal) authentication isn’t supported.
• Your SharePoint site and your Microsoft Foundry agent must be in the same tenant.
• You can add only one SharePoint tool per agent.
• The underlying Microsoft 365 Copilot Retrieval API returns text extracts. Retrieval from nontextual content, including images and charts, isn’t supported.
• For semantic and hybrid retrieval, the Microsoft 365 Copilot Retrieval API supports .doc, .docx, .pptx, .pdf, .aspx, and .one file types. For details, see the Microsoft 365 Copilot API.

Setup

Start with SharePoint sites that have a simple folder structure and a small number of short documents.

1. Select SharePoint and follow the prompts to add the tool. You can only add one per agent.

2. Add a SharePoint connection.

   For step-by-step instructions, see Add a new connection to your project.

3. In the SharePoint connection configuration, enter the site URL or folder URL.

   • Site URL example: https://<company>.sharepoint.com/sites/<site_name>
   • Folder URL example: https://<company>.sharepoint.com/sites/<site_name>/Shared%20documents/<folder_name>

Your site_url needs to follow the format above. If you copy the entire value from the address bar of your SharePoint, it doesn’t work.

1. Save the connection, and then copy its connection ID.
2. Set the connection ID as SHAREPOINT_PROJECT_CONNECTION_ID.

How it works

The SharePoint tool makes it possible by enabling seamless integrations between AI agents and business documents stored in SharePoint. This capability is empowered by the Microsoft 365 Copilot API. To ground your SharePoint documents, enter the sites or folders to connect with. The SharePoint tool leverages built-in indexing capabilities to enhance the search and retrieval experience, including intelligent indexing, query processing, and content chunking.

For more information about delegated access and identity passthrough in Foundry, see Agent identity concepts in Microsoft Foundry.

Instead of requiring developers to export SharePoint content, build a custom semantic index, manage governance controls, and configure refresh logic, this capability automates the entire retrieval pipeline. It dynamically indexes documents, breaks content into meaningful chunks, and applies advanced query processing to surface the most relevant information. By using the same enterprise-grade retrieval stack that powers Microsoft 365 Copilot, this capability ensures AI agent responses are grounded in the most up-to-date and contextually relevant content.

Customers rely on data security in SharePoint to access, create, and share documents with flexible document-level access control. Enterprise features such as identity passthrough (On-Behalf-Of) authentication ensure proper access control. End users receive responses generated from SharePoint documents they have permission to access. By using OBO authentication, Foundry Agent Service uses the end user’s identity to authorize and retrieve relevant SharePoint documents, generating responses tailored to specific end users.

Troubleshooting

Issue	Cause	Resolution
AuthenticationError: AppOnly OBO tokens not supported by target service	Using application identity instead of user identity	The SharePoint tool requires user identity (identity passthrough). Don’t use application-only authentication.
Forbidden: Authorization Failed - User does not have valid license	Missing Microsoft 365 Copilot license or pay-as-you-go model	Assign a Microsoft 365 Copilot license to the user or enable pay-as-you-go. See Prerequisites.
401 or authentication failures	Cross-tenant access attempt	Confirm the user in Foundry and Microsoft 365 is in the same tenant.
Tool returns no results	User lacks access to SharePoint content	Verify the user has read access to the SharePoint sites and documents being queried.
Slow response times	Large document search scope	Narrow the search scope by specifying specific sites or libraries. Consider using more specific search queries.
Incomplete document retrieval	Content not indexed	Confirm the SharePoint content is indexed by Microsoft Search. Recently added content might need time to be indexed.
Resource not found errors	Invalid site or library path	Verify the SharePoint site URL and library paths are correct and accessible to the user.
Inconsistent search results	Semantic index sync delay	Wait for the semantic index to sync. Large content changes might take time to propagate. See Semantic indexing for Microsoft 365 Copilot.

Next steps

• For reference, see articles about content retrieval used by the tool:
  • Overview of the Microsoft 365 Copilot Retrieval API.
  • Semantic indexing for Microsoft 365 Copilot