pH7x SystemspH7x Systems®
ExpertiseKnowledgeToolsField GuideBlogAbout
← pH7x Systems KnowledgeCopilot agents

How to read who can use a SharePoint agent

I shared an agent with somebody. What did I just give them?

By João Livio·pH7x Systems Knowledge

30-second answer

powershell
Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/finance -Interactive -ClientId $clientId
$agent = Get-PnPCopilotAgent | Select-Object -First 1
Get-PnPFile -Url $agent.ServerRelativeUrl -AsListItem |
    Get-PnPProperty -Property RoleAssignments, HasUniqueRoleAssignments

Sharing an agent shares the agent. It does not share what the agent knows. Those are two permission questions, and they have different answers.

What this proves

Who may open or edit the agent itself. The agent is a file, so the file's permissions are the answer, and they behave like any other document's.

What it does not prove

  • What any of those people will get back from it. Microsoft is explicit that responses depend on each user's own permissions to the agent's data sources. Access to the agent is not access to the content behind it.
  • That the agent is safe to share. A safe answer needs both halves: who holds the agent, and who can read what it points at. This is one half.
  • Who has used it. Permission is not activity. Usage is in file statistics and in the audit log.

PowerShell

powershell
$clientId = '00000000-0000-0000-0000-000000000000'
Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/finance -Interactive -ClientId $clientId

foreach ($agent in Get-PnPCopilotAgent) {
    $item = Get-PnPFile -Url $agent.ServerRelativeUrl -AsListItem
    Get-PnPProperty -ClientObject $item -Property HasUniqueRoleAssignments | Out-Null
    [pscustomobject]@{
        Agent  = $agent.CustomCopilotConfig.GPTDefinition.Name
        File   = $agent.ServerRelativeUrl
        Unique = $item.HasUniqueRoleAssignments
    }
}

HasUniqueRoleAssignments is the question that matters first: an agent inheriting the library's permissions is shared with whoever the library is shared with, and nobody decided that on purpose.

Example output

text
Agent             File                                        Unique
-----             ----                                        ------
Budget assistant  /sites/finance/SiteAssets/Budget Q3.agent    False
Invoices          /sites/finance/SiteAssets/Invoices.agent      True

False means the agent is as widely available as the library holding it. True means somebody set permissions on this one, and the next read is which.

Explanation

Microsoft documents both halves of this on the same page, and they are easy to read as one sentence when they are two.

The first half: agents in SharePoint are .agent files, and "the permissions on the .agent file determine who can access or edit the agent". That is the sharing you performed.

The second half: "if a user has access to the agent but not to the site or document library it references, the agent's responses for this user don't include content from those restricted sources". That is the sharing you did not perform, and could not have.

So an agent creates no new access. It also removes none. What it changes is speed: content that was reachable by somebody willing to search for it is now reachable by somebody who asks a question in plain language. An organisation with a permission model it never tested has not acquired a new problem here, it has acquired a faster reader of the old one.

The practical consequence for a review is an ordering. Reading the agent's permissions tells you who holds it. Reading its sources, and then the permissions on those sources, tells you what any of them can actually obtain. Doing the first and calling it an assessment is the mistake this page exists to prevent.

Production considerations

  • This is a read. Nothing here grants, revokes or shares anything.
  • Inherited permissions are the common case and the quiet one. An agent in Site Assets is available to the site's members unless somebody changed it, and unless somebody changed it is not a control.
  • The answer is bounded by the identity running it. Agents in sites this identity cannot open do not appear, and their absence looks identical to there being none.
  • Two reads make an assessment. This one, and the sources the agent points at. Either alone is a fact; only both together are an answer.

References