Share via

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 makers in Copilot Studio, but it isn't possible to interact with or use the agent.

Important

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

Prerequisites

  • You have the Bot ID and Environment ID for the target agent.
  • You must obtain a user access token issued by Microsoft Entra ID OAuth2.
    • The user associated with the token must have one of the following admin roles:
      • Global tenant administrator
      • AI administrator
      • Power Platform administrator
    • You must acquire the access token using the client ID of an app registration that has the CopilotStudio.AdminActions.Invoke scope granted under the Power Platform API.

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:

Get agent quarantine status

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

Learn more in Get Bot Quarantine Status API reference documentation.

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

Learn more in Set Bot As Quarantined API reference documentation.

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

Learn more in Set Bot As Unquarantined API reference documentation.

  • Last updated on