FrançaisBook a call

Azure AI Foundry Intermediate · Updated on

Install Foundry Agents in SharePoint and Teams

Build the .sppkg package from the GitHub repository, deploy it to the tenant app catalog, then approve its three API permissions. Grant users the Foundry User role (formerly Azure AI User) on the Azure AI Foundry project. Add the web part to a page, enter the agent ID and project endpoint URL, then sync the solution to Teams.

Before you start

  • A Microsoft 365 tenant with SharePoint Online and Microsoft Teams.
  • An Azure subscription with at least one Azure AI Foundry project and an agent created in that project.
  • An admin account that can deploy to the app catalog and approve Microsoft Graph API permissions.
  • Permission to assign Azure roles on the Foundry resource (for example, the Owner role).
  • Node.js 22 (version >=22.14 and <23) and Git to build the package.

Step 1: Get the project endpoint and the agent name

Open your project in Azure AI Foundry. Copy the project endpoint URL. It has the form https://<resource>.services.ai.azure.com/api/projects/<project>.

Also note the agent name as it appears in Foundry, for example hr-assistant. The web part references the agent by this name.

The project must exist before you deploy the package. Without it, the Azure Machine Learning Services permission isn't recognized.

Check: You have a URL that ends with /api/projects/<project name> and the exact name of an agent.

Step 2: Build the .sppkg package

The repository doesn't publish releases: you build the package from source.

Clone the repository, install the dependencies, then run a production build.

git clone https://github.com/Youssef-El-Garmit/spfx-foundry-agents.git
cd spfx-foundry-agents
npm ci
npx gulp bundle --ship
npx gulp package-solution --ship

Check: The file sharepoint/solution/spfx-foundry-agents.sppkg exists.

Step 3: Deploy the solution to the app catalog

Open the tenant app catalog. Upload the spfx-foundry-agents.sppkg file.

In the dialog, select the option that makes the solution available to all sites in the organization, then select Deploy. This tenant-wide deployment is also required to use the solution in Teams.

Check: The “Foundry Agents by Nemoura” solution appears in the app catalog, with nothing in the App Package Error Message column.

Step 4: Approve the API permissions

Deployment creates three permission requests. Open the SharePoint admin center, go to the API access page, and approve them.

Azure Machine Learning Services / user_impersonation: call your Foundry agents on behalf of the signed-in user.

Microsoft Graph / User.Read: user profile and audience targeting.

Microsoft Graph / Files.ReadWrite.All: attachments, the document panel, and delegated function calls on files.

These are delegated permissions: users never get more than their own access rights.

Check: All three requests appear in the list of approved requests on the API access page.

Step 5: Give users access to the Foundry project

In the Azure portal, open the Foundry resource, then Access control (IAM). Add a Foundry User role assignment. Microsoft renamed this role: it used to be called Azure AI User, and the project README still uses the old name.

Under Members, choose User, group, or service principal. Select the users or a Microsoft Entra group, then Review + assign.

Seeing the web part only requires access to the page. Chatting with an agent requires this role.

Check: The role appears on the resource's Role assignments tab for the selected users or group.

Step 6: Add the web part and configure an agent

Edit a SharePoint page and add the Foundry Agents web part (Advanced category). In the “Agent configuration” section, select “Add agent”.

Fill in “Display name”, “Agent ID” (the agent name in Foundry), and “Endpoint URL” (the project endpoint). These three fields are required.

The “Audience” field is optional: if left empty, the agent is offered to everyone. Otherwise, choose users, Microsoft Entra groups, or SharePoint groups.

Message suggestions, the icon, attachments, function calls, and voice dictation are optional. Function calls are disabled by default, and the DELETE and PATCH methods are blocked by default.

You can export and import the configuration as a JSON array, which makes it easy to reuse on another page.

[
  {
    "displayName": "HR Assistant",
    "agentId": "hr-assistant",
    "endpointUrl": "https://<resource>.services.ai.azure.com/api/projects/<project>",
    "iconType": "fluent",
    "fluentIconName": "Bot24Regular"
  }
]

Check: Once the page is published, a user with the role sends a message and receives a streamed response.

Step 7: Make the solution available in Teams

In the app catalog, select the package, then Sync to Teams on the Files tab of the ribbon.

In Teams, open Apps: after a few minutes, the app appears under the apps built for your organization.

For a channel tab, select + in the channel, choose the app, then Add and Save. To configure the tab, right-click its name and choose “Settings”.

The solution also works as a Teams personal app. In that case, you configure it from the app's “Settings” button.

Check: A sync success message appears and the app is available in Teams.

Common errors

The admin center shows “The requested permission isn't valid” for Azure Machine Learning Services.
This permission is valid only once at least one Azure AI Foundry project exists in the tenant. Create the project, then redeploy the package.
The SharePoint admin can't approve the Microsoft Graph permissions.
For Microsoft Graph and other Microsoft APIs, approval requires a Global Administrator. The SharePoint Administrator role alone isn't enough.
The web part displays, but the agent doesn't respond.
Check that the user has the Foundry User role (formerly Azure AI User) on the resource or project, and that the agent ID and endpoint URL are correct.
Sync to Teams fails after a package update.
Delete the previous version of the app in Teams (Add a tab, More apps, … menu, Delete), then run the sync again.

Sources

Questions

Frequently asked questions

Do I need a server or an API key?

No. The web part runs in the browser and calls Azure AI Foundry with the signed-in user's Microsoft Entra token. No key is stored.

Can one Foundry project serve several Microsoft 365 tenants?

No. A Foundry resource serves users in its own tenant. Plan one Foundry project per Microsoft 365 tenant.

Can a single web part show several agents?

Yes. Each agent has its own name, icon, suggestions, and audience. The Audience field limits who sees the agent; the Azure role is still what authorizes the call.

Is the solution paid?

No. Foundry Agents is open source under the MIT license. Microsoft bills only the Azure AI Foundry consumption on your subscription.

Need a hand?

We can do it with your team, or train your team to do it on its own.

Book a callAzure AI Foundry agents

See also

Other guides