pH7x SystemspH7x Systems®
ExpertiseKnowledgeToolsField GuideBlogAbout
← pH7x Systems KnowledgeCopilot agents

How to read which sources a SharePoint agent was pointed at

Which sites and libraries does this agent actually reference?

By João Livio·pH7x Systems Knowledge

30-second answer

powershell
Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/finance -Interactive -ClientId $clientId
Get-PnPCopilotAgent | ForEach-Object {
    $_.CustomCopilotConfig.GPTDefinition.Capabilities.ItemsByUrl.Url
}

An agent in SharePoint is a file, and the file names the sources it was pointed at. Reading the agent gives you that list without asking anybody.

What this proves

Which sites, libraries, folders or files a given agent was configured to ground its answers on, as recorded in the agent itself.

It also gives you the agent's own instructions, its description and the conversation starters somebody wrote for it. All of it is in the file, and anybody who can read the file can read all of it.

What it does not prove

  • Who can actually see those sources. The list is what the agent points at, not what any particular person is allowed to read through it. Those are two separate reads, and confusing them is the whole trap.
  • That the list is complete for the tenant. This is one site collection. An identity that cannot open a site does not see the agents in it, so an empty result means nothing was visible from here and never there are none.
  • What the agent answered anybody. Configuration is not usage. Interaction detail lives in the audit log, not in the file.

PowerShell

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

Get-PnPCopilotAgent | ForEach-Object {
    $definition = $_.CustomCopilotConfig.GPTDefinition
    [pscustomobject]@{
        File    = $_.ServerRelativeUrl
        Type    = $_.AgentType
        Name    = $definition.Name
        Sources = @(
            $definition.Capabilities.ItemsByUrl.Url
            $definition.Capabilities.ItemsBySharePointIds.Url
        ).Count
    }
}

Get-PnPCopilotAgent takes an optional -ServerRelativeUrl to read one agent instead of every agent in the site collection.

Example output

text
File                                          Type Name              Sources
----                                          ---- ----              -------
/sites/finance/SiteAssets/Budget Q3.agent     Site Budget assistant        3
/sites/finance/SiteAssets/Invoices.agent      DocumentLibrary Invoices     1

AgentType returns one of Site or DocumentLibrary. Each source item carries a Url, a Name, a Type and the SharePoint identifiers SiteId, WebId, ListId and UniqueId.

Explanation

Agents created in SharePoint are stored as .agent files, and Microsoft documents where they live: the site's Site Assets library. That is the reason the whole surface is readable at all. There is no separate agent service to query and no special API to learn. An agent is a document, and this product already knows how to read documents.

Inside it, the definition carries a name, a description, the instructions the author wrote, and the capabilities. The capabilities are where the sources are: ItemsByUrl for things named by address, ItemsBySharePointIds for things named by identifier. Either way the agent is telling you what it was told to read.

The instructions are readable too, and that is worth saying out loud because people write things in them. Whoever can open the file can see the prompt, and the prompt was often written as if nobody would.

The shape above was read from PnP.PowerShell 3.3.0 itself rather than observed against a tenant, which is what the tested_with line means and does not mean. The property names and the enum are the module's; the values on your own tenant are yours.

Production considerations

  • This is a read. Get-PnPCopilotAgent changes nothing, and nothing on this page creates, edits or removes an agent.
  • The result is bounded by the identity running it. A delegated run sees the agents in the sites it can open. That boundary belongs in the report, because a count without it reads as a tenant total.
  • A site with no agents and a site you cannot open produce the same empty result. They are different answers, and only one of them is good news.
  • Sources named by identifier may outlive what they point at. A ListId in an agent file is a claim about a list that existed when somebody configured it, not proof that the list exists now.

References