Microsoft 365 Agents SDK · validated 7 Oct 2026

Authenticated Copilot Studio agents on any SharePoint site

Tutorial, use cases and test scenarios for publishing a Copilot Studio agent through the Microsoft 365 Agents SDK - one SharePoint web part for the whole tenant, single sign-on with Microsoft Entra ID, and Copilot Studio sharing as the access control. Built and tested end to end in a live Microsoft demo tenant.

use cases - 9 validated in the demo tenant

tutorial steps with checkpoints and screenshots

test scenarios with expected and actual results

16 / 27

passed; 1 limitation, 1 finding, 9 to validate in your tenant

Overview

How the Agents SDK web part works

The page talks to Copilot Studio directly with the user's own Entra ID token - no host site, no hidden files, no anonymous path.

What you get

One SPFx package and one Entra SPA app for every site in the tenant.
Silent single sign-on with the SharePoint session, including MFA; one-click fallback when a browser blocks it.
The agent knows who is chatting (System.User.DisplayName and more).
Copilot Studio sharing enforced on every site; changes apply on the next page load.
Inline, themable chat; several agents per page; no Microsoft 365 Copilot license needed.

Three independent gates

Microsoft Entra ID - the user is signed in (token for CopilotStudio.Copilots.Invoke).
Copilot Studio sharing - the agent is shared with the user or their group.
SharePoint permission - the user can open the page (Visitor is enough).

Authentication deep dive · configuration re-verified 13 Oct 2026

How this implementation uses authorization code + PKCE

Microsoft deprecated the older implicit grant, not the SPA application type. This web part uses MSAL Browser 4.30, which uses the OAuth 2.0 authorization-code flow with Proof Key for Code Exchange (PKCE). The deployed Entra app has both implicit-token settings turned off.

Deprecated - not used

Implicit grant

Requested tokens directly from the authorization endpoint.
Returned tokens in the browser URL fragment.
No PKCE binding for the authorization response.
Implicit access-token and ID-token issuance are disabled on our app registration.

Current Microsoft model - used here

SPA + authorization code + PKCE

MSAL requests a short-lived authorization code.
A one-time PKCE verifier binds the code to the browser request.
MSAL redeems the code at the token endpoint and manages renewal.
No client secret is placed in SharePoint or JavaScript.

What we verified: the actual demo-tenant app is single-tenant, has one SPA redirect URI at the SharePoint origin, has delegated CopilotStudio.Copilots.Invoke, and reports enableAccessTokenIssuance: false plus enableIdTokenIssuance: false.

FlowFrom the SharePoint page to the agent

1SharePoint + SPFxLoads the web part with the signed-in user and agent connection string.

2MSAL + PKCERequests an authorization code silently, with a one-time code challenge.

3Microsoft Entra IDReuses the existing session, validates policy and returns the code.

4Power Platform tokenMSAL redeems the code and receives a delegated user token.

5Copilot StudioValidates identity and agent sharing, then streams the conversation to Web Chat.

Step by stepWhat the code does

SharePoint loads the tenant-wide SPFx web part

The page supplies the current tenant, signed-in SharePoint user and the agent's Microsoft 365 Agents SDK connection string.

No Copilot Studio credential or secret is stored in the page configuration.

The web part initializes MSAL as a public client

MSAL receives the single-tenant client ID, tenant authority and the SharePoint origin as its SPA redirect URI. A public client has no client secret.

Microsoft Entra ID recognizes the request as a browser SPA request.

MSAL first checks its token cache

acquireTokenSilent looks for the correct account (matched to the SharePoint UPN) and a usable delegated token.

A valid cached token avoids another round trip and no user interface appears.

MSAL reuses the existing Entra session

If the cache has no usable token, ssoSilent starts an authorization-code request in a hidden frame with login_hint set to the SharePoint user.

The existing SharePoint / Entra session normally satisfies sign-in and MFA without another prompt.

PKCE binds the authorization code to this browser request

MSAL creates a one-time code verifier and sends its derived challenge to Microsoft Entra ID. The returned authorization code can only be redeemed with that verifier.

A stolen authorization code cannot be redeemed by a different client.

MSAL redeems the code for a delegated Power Platform token

MSAL calls the Microsoft identity platform token endpoint and requests the scope derived from the connection string (for example https://api.powerplatform.com/.default).

The token represents the signed-in user and contains the consented CopilotStudio.Copilots.Invoke permission.

The Copilot Studio client starts the conversation

The web part gives the access token and connection settings to CopilotStudioClient, then bridges its activity stream to Bot Framework Web Chat.

The token is sent only to the Power Platform / Copilot Studio endpoint.

Copilot Studio checks both identity and sharing

Copilot Studio validates the token, identifies the user and enforces whether the agent is shared with that user or one of their groups.

Shared users chat; unshared users receive the agent's access-denied response.

Interactive fallback uses the same secure flow

If silent sign-in is blocked by browser privacy controls or Conditional Access, the user selects Sign in with Microsoft. acquireTokenPopup still uses authorization code + PKCE.

The popup does not switch to implicit grant. One completed sign-in reconnects the other agent web parts on the page.

ConfigurationVerified Entra settings

Setting	Value used by this implementation	Status
Application type	Single-page application (public client)	Supported
OAuth flow	Authorization code with Proof Key for Code Exchange (PKCE)	Supported
Implicit access-token issuance	Disabled (`enableAccessTokenIssuance: false`)	Verified
Implicit ID-token issuance	Disabled (`enableIdTokenIssuance: false`)	Verified
Sign-in audience	Single tenant (`AzureADMyOrg`)	Verified
SPA redirect URI	`https://<tenant>.sharepoint.com`	Verified
Copilot Studio permission	Power Platform API / `CopilotStudio.Copilots.Invoke` (delegated)	Verified
Client credential	None - a browser public client must not contain a secret	Verified
Authentication library	MSAL Browser 4.30 (`PublicClientApplication`)	Verified
Current token cache	`localStorage`; use `sessionStorage` or `memoryStorage` if policy requires less persistence	Optional hardening

Code pathMSAL configuration and token acquisition

Public-client configuration

A browser SPA has a client ID and redirect URI, but no client secret.

const pca = new PublicClientApplication({
  auth: {
    clientId: "<single-tenant-app-client-id>",
    authority: "https://login.microsoftonline.com/<tenant-id>",
    redirectUri: window.location.origin,
    navigateToLoginRequestUrl: false
  },
  cache: {
    cacheLocation: "localStorage"
    // Use "sessionStorage" or "memoryStorage" for less persistence.
  }
});
await pca.initialize();

Silent first, interactive only when required

All three MSAL APIs below use authorization code + PKCE in MSAL Browser 4.

const scopes = [CopilotStudioClient.scopeFromSettings(settings)];

// 1. Cache / refresh token.
const account = findAccount(pca, sharePointUserUpn);
if (account) {
  return await pca.acquireTokenSilent({ scopes, account });
}

// 2. Existing SharePoint / Entra session (authorization code + PKCE).
return await pca.ssoSilent({ scopes, loginHint: sharePointUserUpn });

// 3. User-initiated fallback; still authorization code + PKCE.
return await pca.acquireTokenPopup({ scopes, loginHint: sharePointUserUpn });

VerifyHow to confirm implicit grant is disabled

Portal checks

Entra admin center > App registrations > your app > Authentication.
Confirm the redirect URI is under Single-page application.
Under Implicit grant and hybrid flows, leave both token checkboxes clear.
Under API permissions, confirm delegated Power Platform API / CopilotStudio.Copilots.Invoke.
Confirm Supported account types is your organization only.

Azure CLI check

az ad app show --id <app-client-id> --query "{
  signInAudience: signInAudience,
  spaRedirectUris: spa.redirectUris,
  implicitAccessToken: web.implicitGrantSettings.enableAccessTokenIssuance,
  implicitIdToken: web.implicitGrantSettings.enableIdTokenIssuance
}" -o json

Expected shape:

{
  "signInAudience": "AzureADMyOrg",
  "spaRedirectUris": ["https://<tenant>.sharepoint.com"],
  "implicitAccessToken": false,
  "implicitIdToken": false
}

Current cache and hardening choice

The tested package uses localStorage so several web parts and browser tabs can reuse the account. MSAL Browser 4 encrypts local-storage artifacts while the browser session exists, but Microsoft states that cache encryption is not a replacement for XSS prevention.

Where policy requires less persistence, change the MSAL cache to sessionStorage (Microsoft default) or memoryStorage (strongest isolation, but sign-in state is lost on refresh).

Microsoft references

Use cases

What the Agents SDK web part enables

Status reflects this engagement: Validated = executed in the demo tenant, To validate = run it in your tenant before relying on it, By design = supported pattern that was not tested here.

UC-01Validated

One assistant on every intranet site

Employees open the intranet home, HR, IT or a project site and chat with the same company agent, already signed in.

How: One tenant-wide SPFx package and one Entra SPA app serve every site. Each page stores only the agent's connection string.

Evidence: Agent A answered every shared tester on every site they could open (8 of 8 runs across Sites A, B and C).

UC-02Validated

Only approved people can chat

HR shares the HR agent with the HR team. Anyone else who opens the page is refused, on every site.

How: Copilot Studio sharing (End user access) is enforced on every Agents SDK call. Use Entra security groups in production.

Evidence: Unshared users got You don't have access to talk to this bot on every site. Revoking and re-sharing took effect on the next page load.

UC-03Validated

The agent knows who is chatting

The agent greets employees by name and can use their identity in topics, for example to look up their own requests.

How: With Authenticate with Microsoft, Copilot Studio receives the signed-in user, so System.User.* variables are filled in.

Evidence: Every greeting used the tester's name (Hello Agents SDK User A!). The web part footer shows the signed-in account.

UC-04Validated

Single sign-on, also with MFA

People already signed in to SharePoint start chatting without another prompt. If the browser blocks silent sign-in, one click fixes it.

How: MSAL acquireTokenSilent, then ssoSilent with the SharePoint user as login hint. Fallback: Sign in with Microsoft popup; one sign-in serves every agent on the page.

Evidence: 24 of 24 Agents SDK sessions signed in silently. With silent SSO blocked, one click on the sign-in button led to an answer in about 20 s.

UC-05Validated

Several agents on one page, or one agent per site

A hub page shows an HR agent and an IT agent side by side; each department site shows its own agent.

How: Every web part instance has its own connection string and conversation.

Evidence: Each test page hosted three agent web parts with independent results.

UC-06Validated

No host site to open up

A person may use the agent but must not see the agent owner's site. They still chat from their own site.

How: The web part calls Copilot Studio directly - there is no .agent file or host site in the path.

Evidence: Shared User C with no access to Site A chatted from Site B. The Agent link (SharePoint channel) blocked the same user.

UC-07Validated

Employees without Microsoft 365 Copilot

Employees without a Microsoft 365 Copilot license use the agent; usage is billed to Copilot Studio capacity.

How: Standard-harness agents reached through the Agents SDK consume the tenant's Copilot Studio capacity (Copilot Credits).

Evidence: Every test user had Microsoft 365 E5 (no Teams) only - no Microsoft 365 Copilot or Copilot Studio license.

UC-08Validated

Never reachable anonymously

Security requires that the agent cannot be used without an Entra sign-in, even if a URL leaks.

How: Agents SDK endpoints accept only user tokens for CopilotStudio.Copilots.Invoke.

Evidence: Anonymous calls to both connection strings returned HTTP 401 (re-checked on 7 Oct 2026). The hosted embed of the GitHub Copilot harness agent did not enforce sign-in.

UC-09Validated

Update once, every site follows

IT ships a new web part version once and every site gets it; makers publish agent changes without touching pages.

How: Tenant app catalog with Enable this app and add it to all sites; agent changes go live when the agent is published.

Evidence: Package 1.0.1.0 -> 1.0.3.0 was rolled out tenant-wide without editing a page; the regression run on Site A passed.

UC-10To validate

Answers that respect SharePoint permissions

The agent answers from policy documents in SharePoint and only uses documents the user can read.

How: SharePoint knowledge with Microsoft authentication runs generative answers on behalf of the signed-in user (documented for Teams, Power Apps and Microsoft 365 Copilot).

Evidence: Not tested through the Agents SDK in this engagement - validate before relying on it.

UC-11By design - not tested here

Agent that knows the page it is on

On a project site the agent already knows the project and tailors its answers.

How: Post a custom event with site/page context after the first agent message and read it in an OnEventActivity topic (Microsoft Learn pattern). Needs a small web part extension.

Evidence: Not implemented in this web part yet.

UC-12By design - not tested here

Same agent in other web apps

The agent is also embedded in a line-of-business portal or a native app with the same sign-in.

How: Copilot Studio client library for JavaScript, .NET or Python with the same connection string and a user token (service principal tokens are not supported).

Evidence: Integrate with web or native apps - not tested here.

Tutorial

Build it step by step

About 60-90 minutes the first time; adding the agent to another site takes about 2 minutes. Scripts and the SPFx solution are in the repository. Every checkpoint below was observed in the demo tenant.

You need: Copilot Studio maker access and capacity · permission to register an Entra app and grant tenant-wide consent · SharePoint Administrator + app catalog site admin · Windows with PowerShell 7, Azure CLI and Node.js 22.

Part 1Prepare the agent in Copilot Studio

Create a standard-harness agent

The Copilot Studio client library (Agents SDK) supports agents built on the standard harness.

Copilot Studio > Home > Other ways to build > Agent (Standard), enter a name, select Create.
Add a description and instructions on the Overview page.

Checkpoint: The agent opens with Overview, Knowledge, Topics and Channels tabs.

Home > Other ways to build > Agent (Standard)

Require Microsoft sign-in

The Agents SDK only works with authenticated agents, and it is what makes the agent know the user.

Settings > Security > Authentication > Authenticate with Microsoft (default for new agents) > Save.

Checkpoint: Channels shows You're using Microsoft authentication, so only Teams and Microsoft 365 and SharePoint channels are available.

Greet the user by name (recommended)

A personalised greeting proves on every page that the user's identity reaches the agent.

Topics > System > Conversation Start > ... > Open code editor.
Replace only the text of the first message (keep the existing id), then Save.

    text:
      - "Hello {System.User.DisplayName}! I'm {System.Bot.Name}. How can I help?"

Checkpoint: The topic saves without errors. After you publish, the greeting shows the signed-in user's name (seen on every test page).

Conversation Start topic in the code editor

Publish and copy the connection string

Pages connect to the published agent through this string. It contains no secret.

Select Publish.
Channels > Web app (or Native app) > Microsoft 365 Agents SDK > Copy.

https://<environment>.environment.api.powerplatform.com/copilotstudio/dataverse-backed/authenticated/bots/<schema-name>/conversations?api-version=2022-03-01-preview

Checkpoint: The string ends with /bots/<agent schema name>/conversations?api-version=....

Channels > Web app > Microsoft 365 Agents SDK

Share the agent

Sharing decides who can chat - on every site and page.

... > Share > add users or Entra security groups > keep End user access > Share.

Checkpoint: The people or groups appear under Existing users as Viewer.

Part 2One-time tenant setup

Register the Entra SPA app

SPFx's built-in token provider cannot get the Copilot Studio scope, so the web part signs in with its own app.

Copy scripts/variables.sample.ps1 to scripts/variables.ps1 and fill it in.
Run the script (idempotent). It adds the SPA redirect URI (your SharePoint origin), the delegated Power Platform API > CopilotStudio.Copilots.Invoke permission and tenant-wide consent.

. .\scripts\variables.ps1
az login --tenant $TenantDomain --allow-no-subscriptions
.\scripts\New-AgentsSdkSpaApp.ps1 -TenantId $TenantDomain -SharePointRootUrl $SharePointRootUrl

Checkpoint: The output shows "adminConsent": "granted"; note the appClientId.

Build the SharePoint package

The package carries the app ID as tenant default, so page authors only paste a connection string.

Node 22 is required for SPFx 1.21.1. MSAL, the Agents SDK client and Web Chat are bundled - no CDN or API-access approvals.

.\scripts\Build-SpfxPackage.ps1 -AppClientId $AppClientId -Version $PackageVersion -NodePath $Node22Path
# -> spfx-copilot-agent\sharepoint\solution\copilot-studio-agent-webpart.sppkg

Checkpoint: copilot-studio-agent-webpart.sppkg is created.

Deploy it to every site

One deployment makes the web part available on all current and future sites.

SharePoint admin center > Active sites > Apps > Membership > add yourself as site admin of the app catalog.
App catalog > Manage apps > Upload the .sppkg (Replace for updates) > Enable this app and add it to all sites > Enable app.

Checkpoint: Manage apps lists the package as Enabled and Added to all sites: Yes.

Part 3Add the agent to your sites

Add the web part and paste the connection string

Each page decides which agent it shows; repeat on as many sites as you like.

Edit the page > + > Copilot Studio Agent (Agents SDK).
Edit properties > Integration mode Microsoft 365 Agents SDK > paste the connection string. Leave app and tenant ID empty (package defaults).
Republish the page.

Checkpoint: The chat shows your personalised greeting, even in edit mode.

Toolbox: Copilot Studio Agent (Agents SDK)

Property pane: paste the connection string

Give people access to the site

SharePoint still decides who can open the page. Visitor (Read) is enough.

Grant site or page access as usual. Agent sharing and site permissions are independent - people need both.

Checkpoint: A test user opens the page and sees the chat.

Part 4Verify

Run the core test scenarios

Five checks prove sign-in, identity, access control and the security boundary.

Shared user: greeting by name and an answer (TC-01, TC-02, TC-05).
Unshared user: You don't have access to talk to this bot (TC-06).
Anonymous call to the connection string returns HTTP 401 (TC-04).

Invoke-WebRequest -Method Post -Uri $AgentConnectionString -ContentType 'application/json' `
  -Body '{"emitStartConversationEvent":true}' -SkipHttpErrorCheck | Select-Object StatusCode   # 401

Checkpoint: All five results match the expected results in the test scenarios.

Shared user: personalised greeting and answer

Unshared user: blocked by Copilot Studio

Run the resilience checks

Confirms the experience when silent sign-in is blocked, access changes, or a user restarts.

Silent sign-in blocked: Sign in with Microsoft opens the popup on the first click (TC-03).
Remove and re-add a user on the agent (TC-07, TC-08); select New chat (TC-22).

Checkpoint: The chat connects after one click and access changes apply on the next page load.

Silent sign-in blocked: one-click sign-in

Automate the regression run (optional)

Re-run the same scenarios after every agent or package change.

Edit tests/agents-sdk-matrix/settings.py, then run the harness (Edge + Playwright, one profile per test user).

cd tests\agents-sdk-matrix
.\launch-edge.ps1
foreach ($p in 'mario','a','b','c','d') { python run_matrix.py $p }
python run_extra_scenarios.py a A      # TC-03 sign-in fallback + TC-22 New chat
python summarize.py

Checkpoint: output/results/summary.md shows the expected result for every persona and site.

Test scenarios

27 scenarios with expected and actual results

Executed in the demo tenant on 7 Oct 2026 with 4 test users, 3 sites, 2 agents and the maker as control (web part 1.0.3.0). Select a row for steps, expected result, actual result and evidence.

Results in the demo tenant

Pass: 16Confirmed limitation: 1Security finding: 1Not run: 9

Defect found and fixed during testing: TC-03 (sign-in popup blocked on pages with several agents) - fixed in web part 1.0.2.0/1.0.3.0 and re-tested.

By area

Area	Scenarios	Pass	Limitation / finding	Not run
Sign-in and identity	4	4	0	0
Access control	6	5	0	1
Sites and pages	5	4	0	1
Licensing and capacity	2	1	0	1
Agent types	2	0	2	0
Lifecycle and operations	4	2	0	2
Extended scenarios	4	0	0	4

ID	Scenario	Area	Priority	Result in the demo tenant
▸ TC-01	Silent single sign-on for MFA-protected users	Sign-in and identity	P1	Pass
Preconditions User signed in to SharePoint (MFA satisfied); agent shared with the user. Steps Open the page with the web part. Watch the web part while it loads. Expected The chat connects without a prompt or popup; the footer shows `Microsoft Entra ID SSO · <user>`. Actual (demo) 24 of 24 Agents SDK sessions (12 page loads, 5 personas) connected silently with the user's account in the footer. Automation `run_matrix.py` Raw results: `docs/test-results/a.json` User A: greeting by name and answer; footer shows the signed-in account
▸ TC-02	The agent knows who is chatting	Sign-in and identity	P2	Pass
Preconditions Conversation Start greets with `{System.User.DisplayName}`. Steps Open the page. Read the greeting. Expected The greeting contains the user's display name. Actual (demo) `Hello Agents SDK User A! ...` - every shared tester and the maker were greeted by name on every site. Automation `run_matrix.py` User A: greeting by name and answer; footer shows the signed-in account
▸ TC-03	One-click sign-in when silent SSO is blocked	Sign-in and identity	P1	Pass
Preconditions Silent SSO cannot complete (third-party cookies blocked, Conditional Access needing interaction, or an embedding host). Simulated by clearing the MSAL cache and blocking the hidden sign-in frame; two Agents SDK web parts on the page. Steps Open the page and wait for Sign in to chat with this agent. Select Sign in with Microsoft right away. Complete the popup if prompted, then ask a question. Expected The popup opens on the first click, the chat connects and answers, and the other agent on the page connects without a second sign-in. Actual (demo) Pass on 1.0.3.0: answer 20.5 s after the click; the second web part reconnected by itself. Defect found and fixed: on 1.0.1.0 the first click was blocked by the popup blocker while another web part was still trying silent sign-in. Automation `run_extra_scenarios.py` Raw results: `docs/test-results/tc03-tc22-userA-siteA-v1.0.3.json` Silent sign-in blocked: one-click sign-in offered After one click: greeting and answer (1.0.3.0) Before the fix (1.0.1.0): first click blocked by the popup blocker
▸ TC-04	No anonymous access to the agent endpoint	Sign-in and identity	P1	Pass
Preconditions The agent's connection string. Steps POST to the connection string without an `Authorization` header (command in tutorial step 11). Expected HTTP 401. Actual (demo) HTTP 401 for Agent A and Agent B (re-checked on 7 Oct 2026). Automation `Manual (one command)` No screenshot - see the result text.
▸ TC-05	Shared users can chat	Access control	P1	Pass
Preconditions Agent shared with the user (End user access), or the user owns it. Steps Open the page. Send Give me one tip for running shorter meetings. Expected Greeting and an on-topic answer (`Agent A (standard harness): ...`). Actual (demo) 8 of 8 runs: User A on Sites A-C, User B on Sites A-B, MarioR on Sites A-C. Automation `run_matrix.py` Raw results: `docs/test-results/summary.md` User A: greeting by name and answer; footer shows the signed-in account
▸ TC-06	Unshared users are blocked	Access control	P1	Pass
Preconditions Agent not shared with the user; the user can open the page. Steps Open the page. Send a question. Expected You don't have access to talk to this bot, contact the owner. and no answer. Actual (demo) 4 of 4 runs blocked: User C on Sites B-C, User D on Sites A and C. Automation `run_matrix.py` User D (not shared): blocked by Copilot Studio
▸ TC-07	Removing a user from sharing blocks them	Access control	P1	Pass
Preconditions User B is shared and can chat. Steps Remove User B from the agent's sharing. Reload the page about 2 minutes later. Expected The blocked message instead of an answer. Actual (demo) You don't have access to talk to this bot, contact the owner. Automation `Manual change + run_matrix.py` Raw results: `docs/test-results/b-after-revocation.json` User B right after removal from sharing
▸ TC-08	Re-sharing restores access	Access control	P2	Pass
Preconditions User B was removed (TC-07). Steps Share the agent with User B again. Reload the page. Expected Greeting by name and an answer. Actual (demo) `Hello Agents SDK User B! ...` and an answer. Automation `Manual change + run_matrix.py` Raw results: `docs/test-results/b-after-regrant.json`
▸ TC-09	Access through an Entra security group	Access control	P1	Not run
Preconditions Agent shared with a security group; the test user is a member and not shared individually. Steps Open the page as the member. Remove the user from the group, wait for the change to apply, reload. Expected The member can chat; after removal the user is blocked. Actual (demo) Not run - individual sharing was tested. Recommended before go-live because production access should be group-based. Automation `run_matrix.py (after the group change)` No screenshot - see the result text.
▸ TC-10	Agent sharing and site permissions stay independent	Access control	P1	Pass
Preconditions One shared user without site access; one unshared user with site access. Steps Open the page as the shared user without site access. Open it as the unshared site member. Expected 1: SharePoint You need access - the web part never loads. 2: The page opens and the agent refuses. Actual (demo) 3 access-denied runs (User B Site C, User C Site A, User D Site B) and 4 agent-blocked runs. Automation `run_matrix.py` Raw results: `docs/test-results/summary.md` No site permission: SharePoint blocks the page
▸ TC-11	One package and one Entra app serve many sites	Sites and pages	P1	Pass
Preconditions Web part deployed tenant-wide. Steps Add the web part with the same connection string on Sites A, B and C. Open each page as a shared user. Expected The agent works on every site without per-site app registrations or packages. Actual (demo) Agent A worked on all three sites with one package and one SPA app registration. Automation `run_matrix.py` One page, several agents: Agent A answers, Agent B is rejected
▸ TC-12	Visitor (Read) permission is enough	Sites and pages	P2	Pass
Preconditions Shared users with Visitor, Member or Owner permission. Steps Open the page with each permission level. Expected The chat works for every level. Actual (demo) User A: Visitor (Site A), Member (B), Owner (C). User B: Member (A), Visitor (B). All worked. Automation `run_matrix.py` Raw results: `docs/test-results/summary.md`
▸ TC-13	No host-site dependency	Sites and pages	P2	Pass
Preconditions Agent shared with User C, who has no access to Site A. Steps Open the Site B page as User C. Ask a question. Expected The chat works; no access to any other site is needed. Actual (demo) Greeting and answer. The Agent link (SharePoint channel) blocked the same user with You need a Microsoft 365 Copilot license.... Automation `run_matrix.py` Raw results: `docs/test-results/c-sdk-shared-no-site-a.json` User C without Site A access chats from Site B
▸ TC-14	Several agents on one page	Sites and pages	P3	Pass
Preconditions Two or more web parts with different connection strings on one page. Steps Open the page. Expected Each web part connects to its own agent and behaves independently. Actual (demo) Every test page hosted three agent web parts; Agent A answered while Agent B returned its harness message. Automation `run_matrix.py` One page, several agents: Agent A answers, Agent B is rejected
▸ TC-15	Page opened in Teams, Viva Connections or the mobile app	Sites and pages	P2	Not run
Preconditions Applies when these entry points are used. Steps Open the page inside the host. Chat. Expected The chat connects silently, or the one-click sign-in appears and its popup is allowed by the host. Actual (demo) Not run. Embedded hosts can block the hidden sign-in frame or popups - validate before announcing these entry points. Automation `Manual` No screenshot - see the result text.
▸ TC-16	Users without Microsoft 365 Copilot licenses	Licensing and capacity	P2	Pass
Preconditions Test users without Microsoft 365 Copilot or Copilot Studio licenses. Steps Chat as these users. Expected Chat works. Actual (demo) Every test user had Microsoft 365 E5 (no Teams) only; all shared users chatted. Automation `run_matrix.py` No screenshot - see the result text.
▸ TC-17	Usage is billed to Copilot Studio capacity	Licensing and capacity	P2	Not run
Preconditions A few completed conversations. Steps Open the environment's Copilot Studio consumption (Copilot Credits) in the Power Platform admin center. Expected Agents SDK conversations appear as Copilot Studio consumption. Actual (demo) Not run. Automation `Manual` No screenshot - see the result text.
▸ TC-18	GitHub Copilot harness agent through the Agents SDK	Agent types	P3	Confirmed limitation
Preconditions Agent built on the GitHub Copilot harness, shared with the user. Steps Open a page whose web part points to that agent. Expected Not supported (Microsoft Learn: the client library supports standard-harness agents). Actual (demo) This action doesn't support agents built with the GitHub Copilot harness. - 12 of 12 page loads, including the owner. Automation `run_matrix.py` GitHub Copilot harness agent through the Agents SDK
▸ TC-19	Hosted web chat embed is not an access boundary (comparison)	Agent types	P1	Security finding
Preconditions GitHub Copilot harness agent set to Authenticate with Microsoft, App-channel embed on a page. Steps Open the page as a user the agent is not shared with. Open the embed URL in a signed-out browser. Expected Users without access are refused. Actual (demo) The embed answered unshared users (4 page loads) and a signed-out browser. Use the Agents SDK path for access-controlled agents. Automation `run_matrix.py` Hosted embed answering a user it is not shared with Hosted embed answering a signed-out browser
▸ TC-20	A web part update reaches every site	Lifecycle and operations	P2	Pass
Preconditions Web part deployed tenant-wide. Steps Increase the version, rebuild and upload with Replace > Enable app. Reload a page on any site. Expected The new version runs on every site without editing pages. Actual (demo) 1.0.1.0 -> 1.0.2.0 -> 1.0.3.0 on 7 Oct 2026: pages loaded the new bundle right away and the regression run passed. Automation `Manual + run_matrix.py` Raw results: `docs/test-results/regression-v1.0.3-userA-siteA.json` Version 1.0.3.0 enabled for all sites
▸ TC-21	Published agent changes reach every site	Lifecycle and operations	P2	Not run
Preconditions Agent in use on several pages. Steps Change the agent (for example the greeting) and publish. Select New chat on any page. Expected The next conversation uses the change; no page or package change is needed. Actual (demo) Not run. Automation `Manual` No screenshot - see the result text.
▸ TC-22	New chat starts a fresh conversation	Lifecycle and operations	P3	Pass
Preconditions An ongoing conversation. Steps Select New chat. Ask a question. Expected Transcript cleared, greeting shown again, the agent answers. Actual (demo) Pass on 1.0.3.0. Automation `run_extra_scenarios.py` Raw results: `docs/test-results/tc03-tc22-userA-siteA-v1.0.3.json` New chat: transcript cleared, greeting shown again
▸ TC-23	Conversation longer than the token lifetime	Lifecycle and operations	P3	Not run
Preconditions A conversation left open for more than about an hour. Steps Send a message after the access token has expired. Expected If the message fails, New chat signs in again silently and the chat continues. Actual (demo) Not run. Known design limit: the client receives a token, not a token provider. Automation `Manual` No screenshot - see the result text.
▸ TC-24	Clear error for a wrong connection string	Extended scenarios	P3	Not run
Preconditions Web part with a mistyped agent schema name or an unpublished agent. Steps Open the page. Expected A readable error, for example Agent not found (404). Verify the connection string / schema name and that the agent is published. Actual (demo) Not run. Automation `Manual` No screenshot - see the result text.
▸ TC-25	Page context reaches the agent (extension)	Extended scenarios	P3	Not run
Preconditions Web part extended to post a context event after the first message; `OnEventActivity` topic stores it. Steps Open the page on a project site. Ask a project question. Expected The agent uses the site or page context. Actual (demo) Not run - not implemented in this web part. Automation `Manual` No screenshot - see the result text.
▸ TC-26	SharePoint knowledge respects the user's permissions	Extended scenarios	P1	Not run
Preconditions Applies when the agent uses SharePoint knowledge. User X can read a document, User Y cannot. Steps Ask X and Y the same question about that document. Expected X gets a grounded answer; Y gets no content from the document. Actual (demo) Not run through the Agents SDK (documented by Microsoft for Teams, Power Apps and Microsoft 365 Copilot). Automation `Manual` No screenshot - see the result text.
▸ TC-27	Guest (B2B) users	Extended scenarios	P3	Not run
Preconditions Applies when guests use the sites. A guest with page access and agent sharing. Steps Open the page as the guest. Chat. Expected The guest signs in (silently or with one click) and chats if shared; otherwise the agent refuses. Actual (demo) Not run. Automation `Manual` No screenshot - see the result text.

Test setup

Agent A = standard harness, shared with User A and User B. Agent B (Weather) = GitHub Copilot harness, shared with User A and User C. User D has no agent. Every site page hosts Agent A and Agent B via the Agents SDK web part plus Agent B's hosted embed for comparison. Test users: Microsoft 365 E5 (no Teams), no Copilot licenses, MFA.

Persona	Agent sharing	Site A	Site B	Site C
User A	Agent A + Agent B	Visitor	Member	Owner
User B	Agent A	Member	Visitor	No access
User C	Agent B	No access	Member	Visitor
User D	None	Visitor	No access	Member
MarioR (maker)	Owner of both	Owner	Owner	Owner

Reading the results

Pass behaved as expected. Confirmed limitation documented product limitation reproduced. Security finding behaviour to be aware of (not the Agents SDK path). Not run recommended for your tenant - the expected result is the requirement to verify.

The core set (TC-01, TC-02, TC-04, TC-05, TC-06) is the quick regression after any agent or package change.

Run it in your tenant

From demo results to your sign-off

1. Use the Excel test plan

The Excel test plan lists every scenario with preconditions, steps, expected result and the demo result. Fill in Your result, Tester, Date and Notes; the Summary sheet counts passes, failures and the P1 pass rate.

2. Start with P1 and the core set

11 scenarios are P1 (must pass before go-live), including the ones this engagement could not run: security-group sharing (TC-09) and SharePoint knowledge permissions (TC-26, when used).

3. Automate the regression

The Playwright harness drives real Edge windows, one profile per test user, and records greeting, answer, errors and a screenshot per web part.

cd tests\agents-sdk-matrix
.\launch-edge.ps1
foreach ($p in 'mario','a','b','c','d') { python run_matrix.py $p }
python run_extra_scenarios.py a A   # TC-03 + TC-22
python summarize.py

4. Keep test accounts safe

Test-user passwords and MFA seeds stay in a secrets folder outside the repository ($env:AGENTS_SDK_TEST_SECRETS_DIR). Delete the test users and the SPA app registration when you are done (guide section 13).

Limits

Not supported, and known design limits

Not supported

GitHub Copilot harness agents through the Agents SDK - Copilot Studio replies This action doesn't support agents built with the GitHub Copilot harness. - verified for every user including the owner. Build SharePoint-facing agents on the standard harness.
SPFx built-in token provider (AadTokenProvider) - Cannot obtain CopilotStudio.Copilots.Invoke (sp-dev-docs #10775). The web part uses MSAL.js with its own SPA app instead.
App-only (service principal) tokens - Not supported by the Agents SDK client (Microsoft Learn). Use Direct Line for server-to-server scenarios.
Hosted web chat embed as an access boundary - Copilot Studio offers the embed code only for agents without authentication. The GitHub Copilot harness embed answered unshared and signed-out users in this test.

Design limits of this web part

Token lifetime - the client receives an access token, not a token provider. If a long-open conversation stops answering, New chat signs in again silently (TC-23).
Embedded hosts - Teams, Viva Connections or the mobile app can block the hidden sign-in frame or popups; validate TC-15 before using these entry points.
Page context - not passed to the agent yet; the documented event pattern needs a small extension (UC-11).
Capacity - unlicensed users consume Copilot Studio capacity; monitor it (TC-17).

Resources

Companion material and references

Companion material

Customer pattern: SharePoint channel + Agent link vs. Agents SDK - the customer's setup reproduced in the same tenant and compared
Test plan (Excel) - record your own results

Source code and guide

https://github.com/patmeh1/copilot-studio-agents-sdk-sharepoint

docs/Agents-SDK-SharePoint-Tutorial.md and docs/Agents-SDK-SharePoint-Use-Cases-and-Test-Scenarios.md - this page as markdown
docs/Agents-SDK-SharePoint-Guide.md - full guide, findings and troubleshooting
spfx-copilot-agent/, scripts/, tests/agents-sdk-matrix/ - web part, setup scripts, test harness

Authenticated Copilot Studio agents on any SharePoint site

How the Agents SDK web part works

What you get

Three independent gates

How this implementation uses authorization code + PKCE

Implicit grant

SPA + authorization code + PKCE

FlowFrom the SharePoint page to the agent

Step by stepWhat the code does

SharePoint loads the tenant-wide SPFx web part

The web part initializes MSAL as a public client

MSAL first checks its token cache

MSAL reuses the existing Entra session

PKCE binds the authorization code to this browser request

MSAL redeems the code for a delegated Power Platform token

The Copilot Studio client starts the conversation

Copilot Studio checks both identity and sharing

Interactive fallback uses the same secure flow

ConfigurationVerified Entra settings

Code pathMSAL configuration and token acquisition

Public-client configuration

Silent first, interactive only when required

VerifyHow to confirm implicit grant is disabled

Portal checks

Azure CLI check

Current cache and hardening choice

Microsoft references

What the Agents SDK web part enables

One assistant on every intranet site

Only approved people can chat

The agent knows who is chatting

Single sign-on, also with MFA

Several agents on one page, or one agent per site

No host site to open up

Employees without Microsoft 365 Copilot

Never reachable anonymously

Update once, every site follows

Answers that respect SharePoint permissions

Agent that knows the page it is on

Same agent in other web apps

Build it step by step

Part 1Prepare the agent in Copilot Studio

Create a standard-harness agent

Require Microsoft sign-in

Greet the user by name (recommended)

Publish and copy the connection string

Share the agent

Part 2One-time tenant setup

Register the Entra SPA app

Build the SharePoint package

Deploy it to every site

Part 3Add the agent to your sites

Add the web part and paste the connection string

Give people access to the site

Part 4Verify

Run the core test scenarios

Run the resilience checks

Automate the regression run (optional)

27 scenarios with expected and actual results

Results in the demo tenant

By area

Test setup

Reading the results

From demo results to your sign-off

1. Use the Excel test plan

2. Start with P1 and the core set

3. Automate the regression

4. Keep test accounts safe

Not supported, and known design limits

Not supported

Design limits of this web part

Companion material and references

Companion material

Source code and guide

Microsoft documentation