Customer use case · validated 7 Oct 2026

One authenticated Copilot Studio agent on every SharePoint site

How your customer's SharePoint-channel setup compares with publishing the same agent through the Microsoft 365 Agents SDK - built, deployed and tested end-to-end in a live tenant with four test users, three sites, two agents and two harnesses.

persona × site runs (5 personas, 3 sites)

web-part test cells

8 / 4

Agent A via SDK: works for shared users / blocked for unshared - exactly as shared

extra site permissions needed with the SDK web part

Works

Standard-harness agent + Agents SDK web part on any number of sites, silent Entra SSO, user identity reaches the agent, sharing enforced (incl. revoke & re-grant).

Works, with a dependency

Customer pattern (SharePoint channel + Agent link): users need Read on the .agent file in Site A - verified that file-only Read is enough.

Not today

GitHub Copilot harness agents via the Agents SDK (This action doesn't support agents built with the GitHub Copilot harness); their embed code is not authenticated.

The use case

What the customer built and observed

Goal: let authenticated employees chat with the same Copilot Studio agent from many SharePoint sites.

Customer setup (paraphrased)

Agent deployed to Site A with the Copilot Studio SharePoint channel.
On Site B, Site C and others: an Agent link web part pointing to that agent.
Users are added (shared) on the agent.
Users get access to Site A, Site B and every site where the agent appears.

Customer observations

Users can chat from any site that has the Agent link web part.
Removing a user from the agent blocks them (You don't have access to this agent); adding them back restores access.
Users must have access to Site A even when they use the agent from another site.
Same behaviour for users with and without a Microsoft 365 Copilot license.

Question: any concerns or potential issues with this approach?

Short answer: the approach is valid and supported (no code). We reproduced every observation. The real cost is the Site A dependency: it is a single point of failure and pushes you to over-grant Site A. Narrow it to Read on just the .agent file, or use the Agents SDK web part, which has no host-site dependency at all.

Two patterns, one runtime

How each pattern reaches the agent

Both end up in the same Copilot Studio runtime on api.powerplatform.com - the SharePoint channel's .agent file literally contains botSchema, environmentID and transport: "rest". That is why sharing, revocation and licensing behave the same; the difference is the extra hop through the file in Site A.

Customer pattern - SharePoint channel + Agent link

This implementation - Agents SDK web part

Copilot Studio SharePoint channel: only one site at a time

The deployment creates Site A/Documents/Copilot Studio Agents/<agent>.agent

Agent link web part on Site B pointing to Site A's .agent file

Agents SDK web part: inline chat, any site

Head-to-head on Site B

Does the user need Site A?

Same agent (Agent A, standard harness), same page site, same users. Only the integration pattern changes.

#	User	State	Agent link (customer)	Agents SDK web part
1	User A	Shared on Agent A · Read on Site A · no M365 Copilot license Agent link: side pane greets User A and answers	WORKS	WORKS
2	User C	Not shared · no Site A access Agent link shows a license message; SDK shows 'You don't have access to talk to this bot'	BLOCKED	BLOCKED
3	User C	Shared on Agent A · no Site A access Agent link: 'You need a Microsoft 365 Copilot license...' (misleading)	BLOCKED	WORKS
4	User C	Shared · Read on only the .agent file (Site A still Access Denied) Agent link works with file-only Read	WORKS	WORKS

Test 1 - Agent link works for User A (no M365 Copilot license)

Test 3 - Shared user without Site A: misleading license message

Test 3 - Same user via Agents SDK web part: works

Test 4 - Read on only the .agent file fixes Agent link

Comparison

SharePoint channel + Agent link vs. Agents SDK web part

	SharePoint channel + Agent link	Agents SDK web part
Effort	No code	One-time SPFx package + Entra SPA app + app catalog deployment
Host-site dependency	Yes - Read on the .agent file in the deployment site; one deployment site at a time	None - each page stores the connection string
Agent sharing & revocation	Enforced (customer test)	Enforced (verified: unshared blocked, revoke and re-grant)
Microsoft 365 Copilot license	Not required (verified); consumes Copilot Studio capacity	Not required (verified); consumes Copilot Studio capacity
User experience	Card on the page -> Copilot side pane	Inline chat on the page, themable, several agents per page
Error when access is missing	Misleading license message	Agent's own access message / explicit web part errors
Governance	Site A editors can delete/rename the .agent file	Central versioned package; per-page configuration
GitHub Copilot harness	SharePoint channel not available	Not supported by the Agents SDK client

Answering the customer

Concerns and recommendations

high

Single point of failure in Site A

Every Agent link depends on the .agent file in the deployment site. Archiving/deleting Site A, changing its permissions, or a Site A member with Edit rights deleting or renaming the file breaks the agent on every site. Host it in a dedicated, locked-down "agent host" site or library.

high

Over-permissioning

"Users must have access to Site A" exposes Site A content to every agent user. Verified alternative: Read on only the .agent file (or a dedicated folder/library) - Site A stays Access Denied and the Agent link works.

medium

Two permission systems to keep in sync

Copilot Studio sharing and SharePoint file permissions. Drive both from one Entra security group.

medium

Misleading error message

Users who cannot read the .agent file see You need a Microsoft 365 Copilot license to access this agent - even though unlicensed users work. Brief the help desk.

medium

Capacity, not licenses

Copilot Studio agents in SharePoint "consume Copilot Studio capacity" - unlicensed users work, so plan and monitor capacity / pay-as-you-go.

low

One deployment site at a time

Copilot Studio: Only one SharePoint site can be deployed to at a time. Moving the host means undeploy/redeploy and re-pointing every Agent link.

low

Harness support

GitHub Copilot harness agents are not available for the SharePoint channel and not supported by the Agents SDK client today. Keep SharePoint-facing agents on the standard harness.

Recommended setup for the SharePoint-channel pattern: dedicated agent host site/library, one Entra security group used both for Copilot Studio sharing and for Read on the .agent file, minimal Edit rights, capacity monitoring. Choose the Agents SDK web part when you need no host-site dependency, inline/branded chat, several agents per page, programmatic control, or cannot grant access to the host site.

Build it

Step-by-step: the Microsoft 365 Agents SDK implementation

Exactly what was executed in the test tenant. Scripts and the SPFx solution are in the repository.

Build a standard-harness agent with Microsoft authentication

Copilot Studio home > Other ways to build > Agent (Standard). Add instructions. Settings > Security > Authentication = Authenticate with Microsoft (default). Optional: greet the user with {System.User.DisplayName} in the Conversation Start topic to prove identity flows through. Publish.

Conversation Start greets {System.User.DisplayName}

Copy the Microsoft 365 Agents SDK connection string

Standard UI: Channels > Web app (or Native app). New UI: right panel Channels (+) > App. The string identifies the environment and agent schema - no secret inside.

https://afdeda3552fae1459bc07b43e75630.0a.environment.api.powerplatform.com/copilotstudio/dataverse-backed/authenticated/bots/new_AgentAStandardharness/conversations?api-version=2022-03-01-preview

Standard agent: Channels > Web app > connection string

New UI: Channels > App > Microsoft 365 Agents SDK

Share the agent with the people or security groups who may chat

Agent > Options (...) > Share > add users / groups with End user access. This list is enforced on every site (verified, including revoke and re-grant).

Agent shared with User A and User B (Viewer / end-user access)

Register one Entra SPA app for the whole tenant (scripted)

Delegated Power Platform API / CopilotStudio.Copilots.Invoke + Graph basics, SPA redirect URI = the SharePoint origin (covers every site), tenant-wide consent. SPFx's built-in token provider cannot obtain this scope (sp-dev-docs #10775), so the web part uses MSAL.js with this app.

az login --tenant $TenantDomain --allow-no-subscriptions
.\scripts\New-AgentsSdkSpaApp.ps1 -TenantId $TenantDomain -SharePointRootUrl https://<tenant>.sharepoint.com
# -> appClientId 1f06ba87-...  adminConsent: granted

Build the SPFx package with tenant defaults (scripted)

SPFx 1.21.1 + @microsoft/agents-copilotstudio-client 1.9.1 + MSAL 4.30 + Bot Framework Web Chat 4.19.1, all bundled (no CDN, no API-access approvals). Node 22 required.

.\scripts\Build-SpfxPackage.ps1 -AppClientId <appClientId> -Version 1.0.1.0 -NodePath C:\tools\node-v22
# -> spfx-copilot-agent\sharepoint\solution\copilot-studio-agent-webpart.sppkg

Deploy once, tenant-wide

Add yourself as site admin of the app catalog (required even for SharePoint Administrators), upload the .sppkg, choose Enable this app and add it to all sites.

Admin center: add yourself as app catalog site admin

Enabled tenant-wide - available on all sites

Add the web part to any page on any site

Edit page > + > Copilot Studio Agent (Agents SDK) > paste the connection string. App ID and tenant come from the package defaults. Repeat on as many sites as needed - or provision pages through the SharePoint pages REST API.

Toolbox: Copilot Studio Agent (Agents SDK)

Property pane: paste the connection string

Published page - Agent A works, Agent B (GitHub harness) rejected

Grant normal SharePoint access

Visitor (Read) on the hosting site is enough. No access to any other site is required.

Without site permission SharePoint blocks the page itself

Validate

Greeting shows the user's name, the footer shows the signed-in UPN, unshared users get You don't have access to talk to this bot, and an anonymous call to the connection string returns HTTP 401.

Shared user: personalised greeting + answer

Unshared user: blocked by Copilot Studio

Permission test matrix

4 users × 3 sites × 2 agents

Agent A (standard harness) shared with User A + User B; Agent B (GitHub Copilot harness, Weather) shared with User A + User C; User D has no agent. Site permissions vary per user. Automated with Microsoft Edge + Playwright, one browser profile per user (MFA via TOTP), greeting + question per chat, screenshot per web part.

Persona	Agent sharing	Site	Site permission	Page	Agent A via Agents SDK	Agent B via Agents SDK	Agent B via hosted embed
User A	Agent A + Agent B	Site A	Visitor	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)
User A	Agent A + Agent B	Site B	Member	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)
User A	Agent A + Agent B	Site C	Owner	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)
User B	Agent A only	Site A	Member	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)
User B	Agent A only	Site B	Visitor	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)
User B	Agent A only	Site C	No access	ACCESS DENIED	-	-	-
User C	Agent B only	Site A	No access	ACCESS DENIED	-	-	-
User C	Agent B only	Site B	Member	OK	BLOCKED - not shared	NOT SUPPORTED	ANSWERS (no auth enforced)
User C	Agent B only	Site C	Visitor	OK	BLOCKED - not shared	NOT SUPPORTED	ANSWERS (no auth enforced)
User D	No agent access	Site A	Visitor	OK	BLOCKED - not shared	NOT SUPPORTED	ANSWERS (no auth enforced)
User D	No agent access	Site B	No access	ACCESS DENIED	-	-	-
User D	No agent access	Site C	Member	OK	BLOCKED - not shared	NOT SUPPORTED	ANSWERS (no auth enforced)
MarioR (maker)	Owner of A + B	Site A	Owner	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)
MarioR (maker)	Owner of A + B	Site B	Owner	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)
MarioR (maker)	Owner of A + B	Site C	Owner	OK	WORKS	NOT SUPPORTED	ANSWERS (no auth enforced)

Additional checks

Revocation: User B removed from Agent A -> blocked on next load; re-shared -> works again.
Anonymous POST to either connection string -> HTTP 401.
MFA users: silent SSO, no prompts; popup fallback never needed.
No tester had a Microsoft 365 Copilot or Copilot Studio license.

Reading the matrix

WORKS personalised greeting + on-topic answer. BLOCKED - not shared the agent replied You don't have access to talk to this bot. NOT SUPPORTED GitHub Copilot harness via Agents SDK. ANSWERS (no auth enforced) hosted embed answered regardless of sharing. ACCESS DENIED SharePoint page not accessible.

User A: 'Hello Agents SDK User A!' + answer

User D: blocked by Copilot Studio sharing

User B right after removal from the agent

No site permission: SharePoint blocks the page

GitHub Copilot harness

What happened with the original Weather agent

Agents SDK: not supported (yet)

Every request - including from the agent owner - returned This action doesn't support agents built with the GitHub Copilot harness. Microsoft Learn: the Copilot Studio client library supports standard-harness agents only.

App-channel embed: renders but is not secured

The hosted web chat answered users the agent was not shared with and even a signed-out browser (anonymous Direct Line token). Treat the existing embed/button on the root site as public until this is enforced.

Embed answering a user who is not shared

Resources

Companion material and references

Companion material

Tutorial, use cases and test scenarios - the Agents SDK implementation step by step, 12 use cases and 27 test scenarios
Test plan (Excel) - run the scenarios in your tenant

Source code and guide

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

docs/Agents-SDK-SharePoint-Guide.md - parameterised guide
scripts/New-AgentsSdkSpaApp.ps1, Build-SpfxPackage.ps1, variables.sample.ps1
spfx-copilot-agent/ - the web part
tests/agents-sdk-matrix/ - the automated test harness

One authenticated Copilot Studio agent on every SharePoint site

Works

Works, with a dependency

Not today

What the customer built and observed

Customer setup (paraphrased)

Customer observations

How each pattern reaches the agent

Customer pattern - SharePoint channel + Agent link

This implementation - Agents SDK web part

Does the user need Site A?

SharePoint channel + Agent link vs. Agents SDK web part

Concerns and recommendations

Single point of failure in Site A

Over-permissioning

Two permission systems to keep in sync

Misleading error message

Capacity, not licenses

One deployment site at a time

Harness support

Step-by-step: the Microsoft 365 Agents SDK implementation

Build a standard-harness agent with Microsoft authentication

Copy the Microsoft 365 Agents SDK connection string

Share the agent with the people or security groups who may chat

Register one Entra SPA app for the whole tenant (scripted)

Build the SPFx package with tenant defaults (scripted)

Deploy once, tenant-wide

Add the web part to any page on any site

Grant normal SharePoint access

Validate

4 users × 3 sites × 2 agents

Additional checks

Reading the matrix

What happened with the original Weather agent

Agents SDK: not supported (yet)

App-channel embed: renders but is not secured

Companion material and references

Companion material

Source code and guide

Microsoft documentation