Skip to main content
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.

​
Prerequisites

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.
  • Install the required SDK package:
    • 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 the latest com.azure:azure-ai-agents dependency to your pom.xml
  • Configure the environment variables used by your sample:
    • 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.

​
Set up the SharePoint connection and delegated user

The SharePoint tool uses delegated user authentication. Run the agent with the signed-in user’s identity so SharePoint can apply that user’s site, folder, and document permissions. App-only and service-principal authentication aren’t supported.
Start with a SharePoint site that has a simple folder structure and a small number of short documents.
  1. Select SharePoint and follow the prompts to add the tool. You can add only one SharePoint tool per agent.
  2. Add a SharePoint connection. For the complete connection workflow, see Add a new connection to your project.
  3. In the SharePoint connection configuration, enter the site URL or folder URL:
  • Site URL: https://<company>.sharepoint.com/sites/<site_name>
  • Folder URL: https://<company>.sharepoint.com/sites/<site_name>/Shared%20documents/<folder_name>
Use the site or folder URL in one of these formats. Don’t copy the full browser address, which can include unsupported path or query-string values.
  1. Save the connection, and then copy its connection ID.
  2. Set the connection ID as SHAREPOINT_PROJECT_CONNECTION_ID.
  3. Sign in as a user who has at least READ access to the configured SharePoint scope, and run the agent with that user’s delegated identity.

​
Verify permission-trimmed retrieval

Verify both successful retrieval and denied retrieval before you make the agent available to users:
  1. Choose a document in the configured scope that one test user can read and a second test user can’t read.
  2. Sign in as the user with access, ask a question whose answer is in that document, and confirm that the response includes the expected information and a citation to the document.
  3. Sign in as the user without access and ask the same question. Confirm that the response doesn’t include information or citations from the restricted document.
Run both checks with delegated user authentication. A response from the first user confirms retrieval; the different result for the second user confirms that SharePoint permission trimming is applied.

​
Usage support

The following table shows SDK and setup support.

​
Parameters

The SharePoint tool uses your project connection to determine which SharePoint site or folder it can retrieve from. If you need to create a SharePoint connection for your project, see Add a new connection to your project.

​
Create an agent with the SharePoint tool

The SDK samples use DefaultAzureCredential. When you run them locally, this credential must resolve to the signed-in user’s identity, such as the identity established by az login. Exclude managed identity and service-principal credentials from the local credential chain. In a production application, authenticate each request with the current user’s delegated identity and use an on-behalf-of flow. Don’t run SharePoint tool calls with the application’s managed identity or service principal.

​
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.
  • The underlying Retrieval API returns at most 25 results and allows 200 requests per user per hour. The query string can contain at most 1,500 characters.

​
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

​
Related content