Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.0

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.

note

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.

ValueThe request is
default_copilotA message in Microsoft 365 Copilot chat
copilot_studioA turn with one of your registered Copilot Studio agents
attachment_uploadA file being uploaded in the Agent Portal, before it enters a conversation

The safe form of an agent-specific rule names the surface first:

Block anything sent to one Copilot Studio agent
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.

Prefer the agent ID for a rule you intend to enforce

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.

AttributeTypeDescription
connector.m365.copilot.surfaceStringdefault_copilot, copilot_studio or attachment_upload. Always present. Guard your rule on this
connector.m365.copilot.user_emailStringThe signed-in person, the same value as request.user
connector.m365.copilot.entra_tenant_idStringThe Microsoft Entra tenant configured on the connector
connector.m365.copilot.conversation_idStringThe 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.

AttributeTypeDescription
connector.m365.copilot.agent_idStringThe agent's app ID. Unchanged by a rename, so prefer it for a rule you enforce
connector.m365.copilot.agent_nameStringThe agent name shown in the console. Readable, but changes if the agent is renamed
connector.m365.copilot.agent_environment_idStringThe Power Platform environment the agent runs in
connector.m365.copilot.agent_schema_nameStringThe agent's schema name
connector.m365.copilot.agent_tenant_idStringThe 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 connector
  • connector.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_upload surface. On a send, it could only be something the caller claimed, so it is not offered, and a label rule does not act.
Block a confidential document at upload
connector.template == "M365_COPILOT"
&& connector.m365.copilot.surface == "attachment_upload"
&& request.files.exists(f, f.text.contains("CONFIDENTIAL"))
Block a document marked Highly Confidential at upload
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:

Block a reply that mentions an internal project name
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.

A reply-side rule turns off streaming for this connector

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.

Reply rules block or allow

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​

Apply a rule to Microsoft 365 Copilot chat but not to your agents
connector.template == "M365_COPILOT" && connector.m365.copilot.surface == "default_copilot"
Block turns with one Copilot Studio agent
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.

Run the policy in Observe mode first

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.