Microsoft Copilot Studio
The Microsoft Copilot Studio integration works in two ways:
Inventory and activity
Where it shows up
- Overview › Agentic estate: under Connected platforms.
- Agents: the Microsoft Copilot Studio source chip.
- Graph: the Copilot chip.
Set it up
On the Library tab of Settings › Integrations, click Install on the Microsoft Copilot Studio card and fill in:
Check that it works
The card shows INSTALLED on the Installed tab, and Copilot Studio agents appear on Agents under the Microsoft Copilot Studio source chip.
Permissions for runtime threat detection
Threat detection is configured per Power Platform environment: repeat the Power Platform steps for each environment whose agents you want to protect.
Runtime threat detection
Copilot Studio calls QuilrAI before a tool executes. QuilrAI scans the user's recent prompt context and proposed tool inputs, then returns an allow/block decision. This integration checks content without forwarding an LLM request to a provider.
When to use it
Use the Copilot Studio integration when you want to:
- Block sensitive data before a Copilot tool receives it
- Prevent risky tool inputs generated from a user prompt
- Log Copilot tool-execution checks alongside other QuilrAI gateway logs
- Apply the same PII, PHI, PCI, financial, adversarial, and custom-intent policies you use elsewhere
Microsoft external threat detection is called for generative agents that use generative orchestration. Microsoft skips this flow for classic agents.
Endpoint
Create a QuilrAI key with provider copilot_studio, then use the closest regional endpoint as the external threat detection base URL:
https://guardrails-usa-2.quilr.ai/copilot_studio/sk-quilr-xxx
The example uses US East. Choose the nearest regional base URL for your tenant:
Treat this URL as a secret. The QuilrAI key is part of the path because Copilot Studio controls the webhook request format.
Routes
Copilot Studio appends these paths to the endpoint base:
For example, if the endpoint base is https://guardrails-usa-2.quilr.ai/copilot_studio/sk-quilr-xxx, Copilot Studio calls:
https://guardrails-usa-2.quilr.ai/copilot_studio/sk-quilr-xxx/validate
https://guardrails-usa-2.quilr.ai/copilot_studio/sk-quilr-xxx/analyze-tool-execution
Copilot Studio may also include an api-version query parameter. QuilrAI ignores unknown query parameters.
Admin consent
A Microsoft 365 or Power Platform admin must grant tenant-wide consent to the QuilrAI Microsoft Entra application before the organization can use the QuilrAI Copilot Studio integration.
Grant admin consent
Use this same Microsoft Entra App ID when Power Platform asks for the Azure Entra App ID:
54abe80d-4f95-4e44-a19a-d360e5cdb617
Power Platform setup
- In QuilrAI, open Settings > LLM Gateway > Create App, choose App-only credentials and select the Copilot Studio tile (guardrails only, no models).
- Copy the full endpoint base URL, including the
sk-quilr-...key. - Have a Microsoft 365 or Power Platform admin grant tenant-wide consent for the QuilrAI Copilot Studio integration.
- Open Power Platform admin center.
- Go to Security and then Threat detection.
- Select Additional threat detection.
- Select the environment, then select Set up.
- Enable Allow Copilot Studio to share data with a threat detection provider.
- Enter the QuilrAI Microsoft Entra App ID:
54abe80d-4f95-4e44-a19a-d360e5cdb617. - Enter the QuilrAI endpoint base URL as the endpoint link.
- Choose the Power Platform error behavior and save.
- Verify: Power Platform calls the
/validateroute when you save. Then run a test agent with a tool and a prompt containing a harmless test value your policy blocks, and check that the tool call is blocked and the check appears in your LLM Gateway logs.
Microsoft documents the setup flow in Enable external threat detection and protection for Copilot Studio custom agents. Their webhook contract is documented in Build a runtime threat detection system for Copilot Studio agents.
What QuilrAI scans
For analyze-tool-execution, QuilrAI scans:
- Recent user messages from
plannerContext.chatHistory plannerContext.userMessagewhen chat history does not provide user text- Scalar values inside
inputValues, including nested object and array values
QuilrAI stores Copilot metadata for review, including conversation ID, tool name, tool ID, correlation ID, and user/tenant identifiers when Copilot provides them.
If Copilot includes a bearer token, QuilrAI uses available claims such as email, preferred_username, upn, oid, sub, and tid for identity-aware logging. The webhook is authenticated by the QuilrAI key in the endpoint path.
Decision behavior
Copilot Studio expects a fast decision. QuilrAI returns a fail-open allow decision on DLP timeout or internal DLP errors so the agent can continue during temporary guardrail service interruptions.
Redaction-style actions become blocks because Copilot Studio cannot accept rewritten tool input from the external threat detection response. Use monitor actions for detections you want to observe without blocking.
Response examples
Allow:
{
"blockAction": false
}
Block:
{
"blockAction": true,
"reasonCode": 112,
"reason": "content_blocked",
"diagnostics": "{\"reason\":\"content_blocked\",\"categories\":[\"email\"]}"
}
Validation:
{
"isSuccessful": true,
"status": "OK"
}