M365 Copilot Agent Management Tool

A PowerShell script to list, block, and unblock Microsoft 365 Copilot agents via the M365 Admin Center API.

Overview

The M365 Admin Center provides a UI for managing Copilot agents, but no documented PowerShell cmdlets exist for this purpose. This script authenticates using the Azure PowerShell module and calls the same internal APIs that the Admin Center UI uses, enabling bulk management and automation scenarios.

Prerequisites

• PowerShell 7+ (pwsh)
• Az.Accounts module — installed automatically on first run if missing
• An account with Global Administrator or equivalent admin permissions in the target tenant

Usage

# List all agents across all scopes (default)
.\Manage-CopilotAgents.ps1 -TenantId "contoso.onmicrosoft.com"

# List agents from specific scopes only
.\Manage-CopilotAgents.ps1 -TenantId "contoso.onmicrosoft.com" -AgentScopes Shared,Tenant

# Block agents interactively
.\Manage-CopilotAgents.ps1 -TenantId "contoso.onmicrosoft.com" -Action Block

# Unblock agents interactively
.\Manage-CopilotAgents.ps1 -TenantId "12345678-1234-..." -Action Unblock

Parameters

Parameter	Required	Default	Description
TenantId	Yes	—	Azure AD / Entra ID tenant ID (GUID or domain name)
Action	No	List	Action to perform: List, Block, or Unblock
AgentScopes	No	All scopes	Which agent scopes to query. Valid values: Shared, Public, Tenant, EntraAgentBlueprintSP

Agent Scopes

The script queries multiple scopes to match the Admin Center UI behavior:

Scope	Workload	Description
Shared	SharedAgent	Agents created with Agent Builder and shared within the org
Public	MetaOS	Publicly available third-party and first-party agents
Tenant	MetaOS	Tenant-scoped agents
EntraAgentBlueprintSP	EntraAgentBlueprintSP	Entra-based agent blueprints

Authentication

The script uses the Az PowerShell module (Az.Accounts) for authentication:

1. On first run, it calls Connect-AzAccount which opens a browser for interactive sign-in.
2. It then requests an access token scoped to https://admin.microsoft.com.
3. Subsequent runs reuse the existing Az context if the tenant matches.

API Logging

All non-auth API requests and responses are logged to a date-stamped file in the script directory:

copilot-agents-2026-03-20.log

The log captures the HTTP method, URL, request body (for POST), and response body for each API call. Large responses are truncated at 50KB.

How It Works

1. List agents — GET /fd/addins/api/agents?workloads={workload}&scopes={scope}&limit=200
2. Block/Unblock agents — POST /fd/addins/api/availableAgents with a WorkloadManagementList payload containing the agent identifiers and the BLOCK or UNBLOCK command.

Interactive Selection

When blocking or unblocking, the script displays a numbered table of agents and prompts for selection:

• Enter comma-separated numbers (e.g., 1,3,5)
• Enter all to select all agents
• Enter q to cancel

A confirmation prompt (yes) is required before any block or unblock operation executes.

Disclaimer

This tool uses undocumented internal APIs from the M365 Admin Center. These APIs may change without notice. Use at your own risk.

License

MIT