Microsoft 365 Copilot Policies
On a Microsoft 365 Copilot connector, HYPR AgentPass™ makes the details of each Copilot request available to your policies as connector.m365.copilot.* attributes:
- Which part of the Agent Portal the request came from
- The Microsoft Entra tenant behind it
- The conversation it belongs to
- On a turn with a registered Copilot Studio agent, that agent's identity
You can then write rules that apply to one agent instead of Copilot as a whole, or that treat a file upload differently from a chat message.
These attributes are available on Microsoft 365 Copilot connectors only. For the attributes available on every connector, see the Attribute Reference.
Writing policies is an administrator task. This page assumes you are comfortable writing a policy by hand, and have a Microsoft 365 Copilot connector configured.
Name the Surface Your Rule Is About
connector.m365.copilot.surface is the only one of these attributes present on every Copilot request. The agent attributes are filled in for a registered Copilot Studio agent, and are absent on Microsoft 365 Copilot chat and on file uploads.
A condition testing a missing attribute is never true. A block written on agent_name alone therefore lets chat and uploads through, with nothing in the Request Log to show it. How Policies Are Evaluated explains this for every namespace. On a Copilot connector, lead every rule with the surface.
Which Surface a Request Came From
connector.m365.copilot.surface takes one of three values.
| Value | The request is |
|---|---|
default_copilot | A message in Microsoft 365 Copilot chat |
copilot_studio | A turn with one of your registered Copilot Studio agents |
attachment_upload | A file being uploaded in the Agent Portal, before it enters a conversation |
The safe form of an agent-specific rule names the surface first:
connector.template == "M365_COPILOT"
&& connector.m365.copilot.surface == "copilot_studio"
&& connector.m365.copilot.agent_name == "HR Assistant"
The policy form offers the surface guard as the example chip M365: Copilot Studio agents only.
agent_name is what you recognize in the console, which makes a rule easy to read. It also changes if someone renames the agent, and a rule naming the old value quietly stops matching. agent_id does not change, so it is the better choice for a rule you rely on. Keep the name in the policy's Description, so the rule stays readable.
Attribute Reference
Surface and tenancy
Present on requests from any of the three surfaces.
| Attribute | Type | Description |
|---|---|---|
connector.m365.copilot.surface | String | default_copilot, copilot_studio or attachment_upload. Always present. Guard your rule on this |
connector.m365.copilot.user_email | String | The signed-in person, the same value as request.user |
connector.m365.copilot.entra_tenant_id | String | The Microsoft Entra tenant configured on the connector |
connector.m365.copilot.conversation_id | String | The conversation this turn belongs to, when the request names one |
The Copilot Studio agent
Filled in on copilot_studio turns only. On the other two surfaces, every attribute in this group is absent.
| Attribute | Type | Description |
|---|---|---|
connector.m365.copilot.agent_id | String | The agent's app ID. Unchanged by a rename, so prefer it for a rule you enforce |
connector.m365.copilot.agent_name | String | The agent name shown in the console. Readable, but changes if the agent is renamed |
connector.m365.copilot.agent_environment_id | String | The Power Platform environment the agent runs in |
connector.m365.copilot.agent_schema_name | String | The agent's schema name |
connector.m365.copilot.agent_tenant_id | String | The Microsoft 365 tenant the agent belongs to |
Rules About the Person
Every Copilot request runs as the person who signed in to the Agent Portal. That person is available to a policy in two ways:
request.user, which works the same on every connectorconnector.m365.copilot.user_email, the same value read through the Copilot attributes
Use whichever reads better alongside the rest of your rule. Both carry the same caution as the agent attributes. See The Signed-In Person in the Attribute Reference and the safe form in Policy Examples.
Rules About Attached Files
Files a user attaches in the Agent Portal are checked twice. The first check is on the attachment_upload surface, as the file is uploaded. The second is on the message that sends it to Copilot or a Copilot Studio agent. A rule that blocks at upload stops the content before it can enter a conversation at all, and the user sees the attachment marked as blocked.
The file attributes are shared with every other connector, and documented once, under Attached Files in the Attribute Reference. When files arrive through the Agent Portal, remember:
- Rules about a file's name, type, size or checksum belong at upload, where AgentPass measured those values from the file itself. On the send, they describe what the caller says the file is.
- Rules about a file's text hold on both, because the text is the content that actually reaches the agent.
- Rules about a document's Microsoft Purview sensitivity label act at upload only. The label is AgentPass's own reading of the document it received, so it is offered only on the
attachment_uploadsurface. On a send, it could only be something the caller claimed, so it is not offered, and a label rule does not act.
connector.template == "M365_COPILOT"
&& connector.m365.copilot.surface == "attachment_upload"
&& request.files.exists(f, f.text.contains("CONFIDENTIAL"))
connector.template == "M365_COPILOT"
&& connector.m365.copilot.surface == "attachment_upload"
&& request.files.exists(f, f.sensitivity_label.name == "Highly Confidential")
Agent Portal Attachments covers which file types the portal accepts, what else the upload checks before a policy sees the file, and what the record keeps. More label conditions are in Policy Examples.
Checking What Copilot Replies
A rule can also act on Copilot's answer. Replies are read through the inference attributes, the same ones used on a model provider connector. One expression therefore covers Microsoft 365 Copilot chat and your Copilot Studio agents together:
connector.template == "M365_COPILOT" && inference.completion.text.contains("Project Redwood")
inference.completion.text carries the reply on both surfaces, and inference.latest_turn.text the message the user just sent. Those two, plus inference.provider, are the only inference attributes with a real value on a Copilot connector. The rest describe a provider conversation, and never arrive here. See On a Microsoft 365 Copilot Connector in the Attribute Reference.
Write these rules on the policy form, not through the AI wizard.
Checking a reply means holding the whole answer until the check finishes. On a connector with an enabled reply-side rule, Copilot replies arrive complete, instead of appearing word by word, and users perceive a slower answer. This applies to every conversation on that connector, not only those a rule matches.
Connectors with no reply-side rule keep streaming as before. Scope the rule to the connector you mean to govern, instead of leaving the policy unscoped.
A rule that reads inference attributes can block or allow, but cannot hold the reply for approval. To keep a person in the loop, run the rule in Observe mode and review its matches, or apply approvals on the request instead of the reply.
On a Copilot Studio turn or an Agent Portal file upload, REQUIRE_APPROVAL blocks the request with the policy's message, and no approval is raised.
Example Conditions
connector.template == "M365_COPILOT" && connector.m365.copilot.surface == "default_copilot"
connector.template == "M365_COPILOT"
&& connector.m365.copilot.surface == "copilot_studio"
&& connector.m365.copilot.agent_id == "00000000-0000-0000-0000-000000000000"
Policy Examples collects more, including an email-domain rule, an attachment-size rule and a confidential-reply rule.
Observe mode is the quickest way to prove one of these rules works before it can block anything. Save it in Observe, send a message on the surface you are targeting, and confirm the match appears on the connector's Policies tab. A rule that matches nothing in Observe mode does nothing in Enforce mode either. That is how a rule built on a missing attribute shows itself.
Related
- How Policies Are Evaluated — modes, actions, and why an absent attribute never matches
- Writing a Policy by Hand — the form these rules go on
- Attribute Reference — the file, person and inference attributes a Copilot rule can read