Quarantine noncompliant agents with the Power Platform API

Copilot Studio provides administrators with robust tools to manage agent security and compliance, including quarantine actions for agents through the Power Platform API.

Quarantining agents is part of Copilot Studio's broader security framework, and works in tandem with your overall security approach in Copilot Studio.

For example, agents that violate data policies or lack compliance documentation can be flagged as part of audits, runtime protection, or other admin reports or notifications. Admins can then use the quarantine APIs to isolate the noncompliant agents while investigating and remediating security and compliance issues.

Agents that are quarantined are still visible to agent users and agent makers in Copilot Studio, but it isn't possible to interact with or use the agent.

Important

The old powervirtualgents namespace is deprecated. Use the copilotstudio namespace in your API calls.

Prerequisites

• You must be a Power Platform tenant admin or a Power Platform Administrator or Dynamics 365 Service Administrator.
• You have the Bot ID and Environment ID for the target agent.
• You have authentication tokens for the service or user using the API.
• You're authenticated via Microsoft Entra ID OAuth2, using the implicit flow in the authorization URL: https://login.microsoftonline.com/common/oauth2/authorize?resource=https://api.powerplatform.com.

API operations for agent quarantine management

Copilot Studio supports three key REST API operations for managing agent quarantine, as part of the Power Platform API.

Note

The quarantine and unquarantine APIs aren't compatible with Classic Chatbot (v1). The API returns 200 OK when you quarantine or unquarantine a Classic Chatbot, but the Classic Chatbot continues to remain available when you block it.

For more information on how and when to use the Power Platform API, see:

• Power Platform API and SDKs: From UX-first to API-first (Blog) (Power Platform Developer Blog)
• Programmability and extensibility overview (Power Platform documentation)
• Get started with Power Platform API (Power Platform documentation)

This article describes the operations available, which are also defined in the Power Platform API reference documentation.

Get agent quarantine status

• Endpoint: GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/botQuarantine/GetBotQuarantineStatus?api-version=1.
• Purpose: Retrieve the current quarantine status of an agent.
• Response: Returns a boolean isBotQuarantined and lastUpdateTimeUtc.

See the API reference documentation for quarantine status for parameter requirements and response codes.

Set agent as quarantined

• Endpoint: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/botQuarantine/SetAsQuarantined?api-version=1.
• Purpose: Mark an agent as quarantined, restricting its availability and interactions.
• Response: Confirms quarantine status update.

See the API reference documentation for quarantining agents for parameter requirements and response codes.

Set agent as unquarantined

• Endpoint: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/botQuarantine/SetAsUnquarantined?api-version=1.
• Purpose: Remove an agent from quarantine after risk assessment and remediation.
• Response: Confirms quarantine status update.

See the API reference documentation for unquarantining agents for parameter requirements and response codes.