Skip to content

Troubleshooting: Control 3.11 - Centralized Agent Inventory Enforcement

Last Updated: February 2026 Troubleshooting Level: Control Implementation

Common Issues and Resolutions

Issue 1: Agent Inventory Feature Not Visible in PPAC

Symptoms: - Agent Inventory section does not appear in PPAC navigation - No "Agent Inventory" or "Agents" menu item in left navigation - Error message: "This feature is not available in your tenant"

Root Causes: 1. Agent Inventory feature is still in Preview and not yet rolled out to your tenant 2. User does not have Power Platform Admin role 3. Tenant region does not yet have the preview feature

Resolution Steps:

  1. Verify Role Assignment:
  2. Navigate to Entra ID → Users → [Your User] → Assigned roles
  3. Confirm "Power Platform Admin" or "Entra Global Admin" role is assigned

  4. Wait 15 minutes for role propagation if recently assigned

  5. Check Feature Availability:

  6. Navigate to Microsoft 365 Admin Center → Health → Message Center
  7. Search for "Agent Inventory" or "MC" message IDs related to PPAC features

  8. Check rollout timeline and expected availability for your tenant region

  9. Verify Tenant Licensing:

  10. Agent Inventory may require specific license SKUs (verify with Microsoft documentation)
  11. Navigate to Microsoft 365 Admin Center → Billing → Licenses

  12. Confirm tenant has Power Apps or Copilot Studio licenses assigned

  13. Contact Microsoft Support:

  14. If feature should be available but is not visible, open support case
  15. Reference: "Agent Inventory feature not visible in PPAC (Preview)"
  16. Provide tenant ID and user principal name

Workaround (Compensating Control):

Until Agent Inventory is available, use PowerShell-based discovery:

# Manual inventory discovery script
$environments = Get-AdminPowerAppEnvironment
$inventory = @()

foreach ($env in $environments) {
    $agents = Get-AdminPowerAppCopilotStudioAgent -EnvironmentName $env.EnvironmentName
    $inventory += $agents | Select-Object DisplayName, Owner, @{N='Environment';E={$env.DisplayName}}, CreatedTime, LastModifiedTime
}

$inventory | Export-Csv -Path "ManualAgentInventory_$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation

Issue 2: PowerShell Script Fails with "Access Denied" or "Insufficient Permissions"

Symptoms: - PowerShell scripts fail with error: "Access denied to resource" - Error: "Insufficient permissions to perform this operation" - Script cannot retrieve agents from environments

Root Causes: 1. User executing script does not have Power Platform Admin role 2. Service principal lacks required API permissions 3. Execution policy blocks script execution

Resolution Steps:

  1. Verify Role Assignment: 

    # Check if user has admin role
Add-PowerAppsAccount
Get-AdminPowerAppEnvironment | Select-Object -First 1
# If this fails, role is missing

  2. Grant Power Platform Admin Role:

  3. Navigate to Entra ID → Roles and administrators
  4. Search for "Power Platform Administrator"
  5. Click → Add assignments
  6. Add your user account

  7. Wait 15 minutes for propagation

  8. Check Execution Policy: 

    # Check current policy
Get-ExecutionPolicy

# If Restricted, change to RemoteSigned
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  9. Verify Module Installation: 

    # Confirm modules are installed
Get-Module -ListAvailable Microsoft.PowerApps.Administration.PowerShell
Get-Module -ListAvailable Microsoft.Graph

# If missing, reinstall
Install-Module -Name Microsoft.PowerApps.Administration.PowerShell -Force
Install-Module -Name Microsoft.Graph -Force

  10. Use Different Account:

  11. If unable to grant admin role to your user, use a dedicated service account with Power Platform Admin role
  12. Configure scheduled tasks with service account credentials

Issue 3: Power Automate Flow Fails to Retrieve Agent Inventory

Symptoms: - Flow run history shows failure at "Get Agent Inventory Data" step - Error: "HTTP 401 Unauthorized" or "HTTP 403 Forbidden" - Flow cannot access Agent Inventory API

Root Causes: 1. Agent Inventory API is not yet available (preview status) 2. Flow lacks required API permissions 3. Managed Identity or service principal authentication not configured correctly

Resolution Steps:

  1. Verify API Availability:
  2. As of February 2026, Agent Inventory API is in preview
  3. API endpoints may change before GA

  4. Check Microsoft Learn documentation for current API status

  5. Use Alternative Data Source (Workaround):

Instead of HTTP request to Agent Inventory API, use SharePoint as intermediary:

Step 1: Export Agent Inventory from PPAC to CSV manually or via PowerShell Step 2: Upload CSV to SharePoint document library Step 3: Power Automate flow reads CSV from SharePoint

Flow modification: 

Trigger: Recurrence (Daily)
Action 1: SharePoint - Get file content (AgentInventory.csv)
Action 2: Parse CSV (use Parse CSV action or Compose)
Action 3: Filter array (incomplete metadata)
Action 4: Post to Teams

  1. Configure Managed Identity (When API Available):
  2. In Power Automate, navigate to flow settings → Connections
  3. Update HTTP connection to use Managed Identity

  4. Grant Managed Identity appropriate API permissions in Entra ID

  5. Use Dataverse as Intermediate Storage:

Alternative approach using Dataverse: - Run PowerShell script daily to populate Dataverse table with inventory data - Power Automate flow queries Dataverse table instead of API - See PowerShell Setup playbook Script 1 for Dataverse population logic

Issue 4: Orphaned Agent Detection Script Returns Empty Results

Symptoms: - Detect-OrphanedAgents.ps1 completes successfully but reports zero orphaned agents - Script output: "Total Orphaned Agents: 0" - Known departed users exist but are not detected

Root Causes: 1. Inventory report used by script does not have accurate owner status 2. Microsoft Graph connection failed to validate users 3. Staleness threshold is too high (e.g., >365 days but no agents that old) 4. Owner email format mismatch (UPN vs. email address)

Resolution Steps:

  1. Verify Owner Status in Inventory Report:
  2. Open the inventory report CSV in Excel
  3. Check "OwnerStatus" column — should show "Active", "Departed", "Invalid", or "Missing"

  4. If all show "Unknown", Graph connection failed during inventory generation

  5. Re-run Inventory Generation with Graph Connection: 

    # Ensure Graph module is installed
Install-Module Microsoft.Graph -Force

# Connect to Graph explicitly before running inventory
Connect-MgGraph -Scopes "User.Read.All"

# Run inventory script
.\Get-AgentInventoryReport.ps1 -OutputPath "C:\Reports"

# Verify OwnerStatus is populated
Import-Csv "C:\Reports\AgentInventoryReport_*.csv" | Select-Object AgentName, Owner, OwnerStatus

  6. Lower Staleness Threshold for Testing: 

    # Test with 180-day threshold instead of 365
.\Detect-OrphanedAgents.ps1 -InventoryReportPath "C:\Reports\AgentInventory.csv" -StalenessThresholdDays 180

  7. Manually Verify Departed Users: 

    # Get list of agent owners
$inventory = Import-Csv "C:\Reports\AgentInventory.csv"
$owners = $inventory | Select-Object -ExpandProperty Owner -Unique

# Check each owner in Entra ID
Connect-MgGraph -Scopes "User.Read.All"
foreach ($owner in $owners) {
    try {
        $user = Get-MgUser -UserId $owner -ErrorAction SilentlyContinue
        if ($user) {
            Write-Host "$owner - Active" -ForegroundColor Green
        } else {
            Write-Host "$owner - NOT FOUND (Departed)" -ForegroundColor Red
        }
    } catch {
        Write-Host "$owner - ERROR: $_" -ForegroundColor Yellow
    }
}

  8. Check Owner Email Format:

  9. Some agents may use email address while others use UPN
  10. Verify graph query handles both formats

Issue 5: Teams Notifications Not Delivered

Symptoms: - PowerShell script or Power Automate flow completes successfully - No error messages related to Teams notification - Teams channel does not receive expected notification

Root Causes: 1. Teams webhook URL is incorrect or expired 2. Adaptive card JSON is malformed 3. Flow bot does not have permission to post to channel 4. Webhook was deleted or disabled by Teams admin

Resolution Steps:

  1. Verify Webhook URL:
  2. Navigate to Teams → [Governance Team] → [Agent Governance Alerts channel]
  3. Click ⋯ (More options) → Connectors → Incoming Webhook
  4. Verify webhook exists and is enabled

  5. Copy webhook URL and compare to URL in script/flow

  6. Test Webhook Directly: 

    # Test webhook with simple message
$webhookUrl = "https://outlook.office.com/webhook/..."
$body = @{
    text = "Test notification from PowerShell"
} | ConvertTo-Json

Invoke-RestMethod -Uri $webhookUrl -Method Post -Body $body -ContentType 'application/json'

Expected result: Message appears in Teams channel within 30 seconds

  1. Validate Adaptive Card JSON:
  2. Copy adaptive card JSON from script
  3. Test in Adaptive Cards Designer: https://adaptivecards.io/designer/
  4. Verify JSON is valid and renders correctly

  5. Common issues: Missing commas, unclosed brackets, invalid schema version

  6. Recreate Webhook:

  7. If webhook is not working, delete and recreate:

    • Teams → Channel → ⋯ → Connectors → Incoming Webhook
    • Click "Remove" on existing webhook
    • Click "Configure" to create new webhook
    • Name: "Agent Inventory Alerts"
    • Upload icon (optional)
    • Copy new webhook URL
    • Update scripts/flows with new URL

  8. Check Flow Bot Permissions (Power Automate):

  9. In Power Automate, check flow run history
  10. If error "Flow bot does not have access to the channel":
    • Add Flow bot as a member of the Teams team
    • Grant posting permissions in channel settings

Issue 6: Pre-Publication Checklist Not Enforced

Symptoms: - Agents are published without complete metadata - Pre-publication checklist is documented but not enforced - No blocking mechanism prevents incomplete agents from going to production

Root Causes: 1. Approval workflow is not configured or agents bypass approval 2. Checklist is manual but not integrated with approval gates 3. No technical enforcement mechanism (DLP, security roles, etc.)

Resolution Steps:

Immediate Mitigation (Manual Process):

  1. Implement Manual Review Gate:
  2. Require all Zone 2/3 agents to have change management ticket before approval
  3. In change request form, include pre-publication checklist as required fields

  4. Power Platform Admin reviews checklist before granting sharing permissions

  5. Communicate Policy to Agent Authors:

  6. Send organization-wide email explaining new pre-publication requirements
  7. Provide link to checklist document and approval process
  8. Include examples of compliant vs. non-compliant agents

Long-Term Solution (Automated Enforcement):

  1. Implement Change Management Integration:
  2. Configure ServiceNow/Jira workflow with agent registration request type
  3. Make all checklist items required fields (cannot submit without completing)
  4. Approval workflow routes to Power Platform Admin → AI Governance Lead → Compliance Officer (Zone 3)

  5. Agents cannot be shared until change request is approved

  6. Use DLP to Block Unapproved Sharing:

  7. Create DLP policy for Zone 3 environments
  8. Block "Copilot Studio for Microsoft Teams" connector until agent is approved
  9. After approval, grant specific agent exemption in DLP policy

  10. Requires manual DLP policy updates per agent (labor-intensive but high assurance)

  11. Implement Custom Approval Workflow in Power Automate:

  12. Flow triggered when agent is created (if webhook available)
  13. Flow checks if agent metadata is complete (query inventory or metadata table)
  14. If incomplete, flow sends notification to author: "Complete metadata before requesting publication"
  15. If complete, flow generates approval request and routes to approvers
  16. After approval, flow updates metadata with approval date and approver name

Issue 7: Inventory Completeness Metrics Do Not Improve Over Time

Symptoms: - Compliance rate remains stagnant or declines month-over-month - Remediation efforts do not result in measurable improvement - Same agents appear in non-compliant reports repeatedly

Root Causes: 1. Remediation actions are not being executed (low follow-through) 2. New agents with incomplete metadata are created faster than remediation occurs 3. No accountability or ownership for remediation 4. Metadata requirements are unclear or too burdensome for agent authors

Resolution Steps:

  1. Establish Remediation Accountability:
  2. Assign specific governance team member as "Remediation Owner"
  3. Weekly review of orphaned/incomplete agent reports
  4. Create JIRA/ServiceNow tickets for each remediation item with due dates

  5. Track ticket completion rate as KPI

  6. Implement SLA Tracking and Escalation:

  7. Add SLA fields to remediation reports (days since detection, SLA breach status)
  8. Automate escalation: If Zone 3 agent exceeds 7-day SLA, escalate to AI Governance Lead

  9. Monthly governance meeting: Review SLA compliance and remediation velocity

  10. Use a Phased Metadata Approach:

  11. If metadata collection is causing adoption friction, consider a phased approach: start with mandatory fields (name, owner, zone) and add supplementary fields (description, data classification, regulatory scope) in subsequent phases
  12. Do NOT remove mandatory governance fields — these are required for Control 3.11 enforcement

  13. Example: Phase 1 requires name, owner, and zone classification; Phase 2 adds description, data classification, and regulatory scope after teams are comfortable with the process

  14. Provide Agent Author Training:

  15. Host monthly training session: "How to Complete Agent Metadata"
  16. Record training and make available on-demand
  17. Include in onboarding for new Copilot Studio users

  18. Provide quick reference guide or checklist template

  19. Block New Agent Creation Until Remediation Backlog Clears:

  20. Temporary measure: Suspend new Zone 3 agent approvals until non-compliance rate drops below 10%
  21. Communicate: "We are prioritizing metadata completeness for existing agents before onboarding new agents"

  22. Resume normal approvals once backlog is remediated

  23. Celebrate Wins and Progress:

  24. Recognize teams/individuals who achieve 100% metadata completeness
  25. Share success stories in governance team meetings
  26. Visualize progress with trend charts: "Compliance rate improved from 65% to 85% this quarter"

Issue 8: Decommissioning Process Results in Data Loss

Symptoms: - Decommissioned agent metadata is not properly archived - Unable to retrieve agent configuration after decommissioning - Audit trail gaps for decommissioned agents

Root Causes: 1. Metadata export step was skipped or failed 2. Archived metadata was stored in temporary location and deleted 3. Agent configuration export did not capture all necessary details 4. Retention policy automatically deleted archived metadata

Resolution Steps:

  1. Verify Metadata Archive Location:
  2. Confirm SharePoint library or compliance repository exists: "Decommissioned Agents Archive"
  3. Check folder structure: YYYY/MM/AgentName_DecommissionedYYYYMMDD/

  4. Verify file retention policy is set to 7+ years (FSI requirement)

  5. Recover Metadata from Power Platform:

  6. If agent was recently decommissioned, metadata may still be in environment
  7. Use PowerShell to query decommissioned agents: 
    Get-AdminPowerAppCopilotStudioAgent -EnvironmentName [EnvironmentId] | Where-Object { $_.Internal.properties.statecode -eq 1 }

  8. Export metadata to JSON and archive

  9. Implement Automated Archival:

  10. Create Power Automate flow: "Agent Decommissioning Metadata Archive"
  11. Triggered when agent status changes to "Decommissioned"
  12. Flow exports metadata to SharePoint with timestamp and original owner info

  13. Flow sends confirmation email to governance team with archive location

  14. Enhance Decommissioning Workflow:

  15. Update decommissioning checklist to include explicit verification step:

    • Metadata exported and saved to archive location
    • Agent configuration exported (YAML or JSON)
    • Archive location path documented in change ticket
    • Compliance Officer verifies archive before final deletion approval

  16. Test Archive Retrieval:

  17. Quarterly, randomly select 3 decommissioned agents
  18. Attempt to retrieve archived metadata
  19. Verify all required fields are present and readable
  20. Document test results as part of compliance evidence

Issue 9: Zone Mappings Are Incorrect or Outdated

Symptoms: - Agents are classified to wrong governance zone - Zone mapping file does not include new environments - Inventory reports show many agents with "Unknown" zone classification

Root Causes: 1. Zone mapping CSV file is not maintained when new environments are created 2. Environment IDs in mapping file do not match actual environment IDs 3. Environments are renamed but mapping file is not updated

Resolution Steps:

  1. Regenerate Zone Mapping File: 

    # Get all environments with IDs
$environments = Get-AdminPowerAppEnvironment | Select-Object EnvironmentName, DisplayName

# Export to CSV for manual zone assignment
$environments | Export-Csv -Path "C:\Config\environments_for_zone_mapping.csv" -NoTypeInformation

# Manually edit CSV and add ZoneName column (Zone 1, Zone 2, Zone 3)
# Save as zone-mappings.csv

  2. Establish Zone Mapping Maintenance Process:

  3. When new environment is created, immediately add to zone mapping file
  4. Power Platform Admin responsible for zone mapping updates
  5. Quarterly review: Audit all environments and verify zone classifications are accurate

  6. Version control zone mapping file in Git or SharePoint with version history

  7. Validate Zone Mappings: 

    # Load zone mappings
$zoneMappings = Import-Csv "C:\Config\zone-mappings.csv"

# Get all environments
$environments = Get-AdminPowerAppEnvironment

# Check for unmapped environments
foreach ($env in $environments) {
    $mapping = $zoneMappings | Where-Object { $_.EnvironmentId -eq $env.EnvironmentName }
    if (-not $mapping) {
        Write-Host "UNMAPPED: $($env.DisplayName) ($($env.EnvironmentName))" -ForegroundColor Red
    }
}

  8. Use Environment Naming Convention:

  9. Include zone indicator in environment display name: "PROD-Z3-Sales", "DEV-Z1-Personal"
  10. Update zone mapping script to auto-detect zone from environment name: 
    $zone = if ($env.DisplayName -match "-Z(\d)-") { "Zone $($Matches[1])" } else { "Unknown" }

Issue 10: Script Performance Issues with Large Inventories

Symptoms: - PowerShell script takes >30 minutes to complete - Script consumes excessive memory (>2GB) - Script times out before completing all environments

Root Causes: 1. Large number of environments (100+) 2. Many agents per environment (>50 agents) 3. Inefficient API calls (e.g., validating each owner individually against Graph) 4. Script is not optimized for parallelization

Resolution Steps:

  1. Optimize Script with Parallel Processing: 

    # Use ForEach-Object -Parallel (PowerShell 7+)
$environments | ForEach-Object -Parallel {
    $env = $_
    $agents = Get-AdminPowerAppCopilotStudioAgent -EnvironmentName $env.EnvironmentName
    # Process agents...
} -ThrottleLimit 5

  2. Batch Graph API Calls: 

    # Instead of querying Graph for each owner individually, get all users once
$allUsers = Get-MgUser -All

# Create lookup hashtable
$userLookup = @{}
foreach ($user in $allUsers) {
    $userLookup[$user.UserPrincipalName] = $user
}

# Validate owners against lookup table (no API calls)
foreach ($agent in $agents) {
    $ownerValid = $userLookup.ContainsKey($agent.Owner.email)
}

  3. Implement Incremental Inventory Updates:

  4. Instead of full inventory scan daily, detect only changes
  5. Store previous inventory in Dataverse or database
  6. Query only agents modified since last run ($filter=lastmodifiedon gt [timestamp])

  7. Merge incremental changes with previous inventory

  8. Run Script in Azure Automation:

  9. Migrate script to Azure Automation Runbook
  10. Benefit from Azure-hosted execution (better network connectivity to APIs)

  11. Use Hybrid Runbook Worker if on-premises connectivity required

  12. Split Script by Environment:

  13. For very large tenants, split execution:
    • Script 1: Environments 1-50
    • Script 2: Environments 51-100
    • Run in parallel or staggered schedule
  14. Merge results afterward

Diagnostic Commands

Check Agent Inventory API Availability

# Test if Agent Inventory API is accessible (adjust URL when API is GA)
$apiUrl = "https://api.powerplatform.com/agentInventory/v1/inventory"
try {
    Invoke-RestMethod -Uri $apiUrl -Method Get -Headers @{ Authorization = "Bearer $token" }
    Write-Host "Agent Inventory API is accessible" -ForegroundColor Green
} catch {
    Write-Host "Agent Inventory API error: $_" -ForegroundColor Red
}

Validate PowerShell Module Versions

# Check installed module versions
Get-Module -ListAvailable | Where-Object { $_.Name -like "*PowerApps*" -or $_.Name -like "*Graph*" } | Select-Object Name, Version

Test Power Platform Connectivity

# Verify Power Platform connection
Add-PowerAppsAccount
Get-AdminPowerAppEnvironment | Select-Object -First 1 | Format-List

# If successful, connection is working
# If error, check credentials and role assignment

Test Microsoft Graph Connectivity

# Verify Graph connection
Connect-MgGraph -Scopes "User.Read.All"
Get-MgUser -UserId "test@contoso.com"

# If successful, Graph connection is working
# If error, check permissions and authentication

Error Code Reference

Error Code Description Resolution
HTTP 401 Unauthorized - Authentication failed Re-authenticate with Add-PowerAppsAccount or Connect-MgGraph
HTTP 403 Forbidden - Insufficient permissions Grant Power Platform Admin role or required API permissions
HTTP 404 Not Found - Resource does not exist Verify environment ID, agent ID, or API endpoint is correct
HTTP 429 Too Many Requests - Rate limit exceeded Implement exponential backoff or reduce API call frequency
HTTP 500 Internal Server Error - Microsoft service issue Wait and retry; if persistent, open support case
PSInvalidOperationException PowerShell operation failed Check syntax, cmdlet name, and module version
ModuleNotFoundError PowerShell module not installed Run Install-Module for required module

Support Escalation

If issues persist after troubleshooting:

  1. Internal Escalation:
  2. Escalate to Power Platform Admin team
  3. Escalate to Entra ID Admin team (for role/permission issues)

  4. Escalate to Security Operations (for DLP or conditional access issues)

  5. Microsoft Support:

  6. Open support case via M365 Admin Center → Support → New service request
  7. Severity: Sev B (if impacting governance, not production outage)
  8. Provide: Tenant ID, user ID, error messages, script version, troubleshooting steps attempted

  9. Reference: Control 3.11 - Centralized Agent Inventory Enforcement

  10. Community Resources:

  11. Power Platform Community Forums: https://powerusers.microsoft.com/
  12. Microsoft Tech Community: https://techcommunity.microsoft.com/
  13. Stack Overflow: Tag power-platform, copilot-studio, microsoft-graph

Known Limitations

As of February 2026, the following limitations exist:

  1. Agent Inventory API: Not yet generally available; preview status may cause instability
  2. Zone Classification: No native PPAC support; requires manual mapping file
  3. Real-Time Enforcement: Unmanaged agent blocking not yet available; requires compensating controls (DLP, security roles)
  4. Cross-Platform Discovery: Agent Inventory may not include all agent types (e.g., Microsoft Foundry agents)
  5. Metadata Extensibility: Cannot add custom metadata fields to Agent Inventory natively

Monitor Microsoft 365 Roadmap and Message Center for updates that address these limitations.

Back to Control 3.11 | Portal Walkthrough | PowerShell Setup | Verification Testing

Updated: February 2026 | Version: v1.0