AI-guided setup for Microsoft Entra Agent ID

Microsoft Entra Agent ID integration involves multiple steps: creating an agent identity blueprint, configuring credentials, setting up identifier URIs and scopes, creating blueprint principals, and provisioning agent identities. Each step has its own prerequisites, validation checks, and decision points.

This AI-guided setup automates this entire workflow by using an AI coding agent (such as GitHub Copilot in VS Code) to execute the steps on your behalf. Instead of navigating between multiple documentation pages and running commands manually, you provide the AI agent with a single instruction file and it walks you through the process interactively.

Benefits

The AI-guided setup offers several advantages over the manual workflow:

• Single entry point: One instruction file replaces the need to navigate between multiple documentation pages. The AI agent follows the steps in order and handles transitions automatically.
• Automated prerequisite validation: The AI agent validates that you have the correct Microsoft Entra roles, that the Microsoft Graph beta module is installed, and that required permissions are configured with admin consent before making any API calls.
• Smart defaults and auto-detection: The AI agent queries your tenant for existing user information and resource details, then uses those values as suggestions when collecting configuration inputs.
• Derived naming conventions: You provide a single display name for your agent, and the AI agent derives all related resource names (blueprint, blueprint principal, agent identities, identifier URIs) using consistent patterns.
• Inline error handling: When a command fails, the AI agent analyzes the error, suggests a fix, and retries rather than requiring you to search through troubleshooting documentation. This error handling is especially valuable for Agent ID-specific pitfalls like permission propagation delays and OData header requirements.
• Idempotent operations: The AI agent checks whether resources already exist before creating them, making it safe to rerun the setup if a previous attempt was interrupted.

Prerequisites

Before you begin, ensure you have the following prerequisites.

Required tools

• Visual Studio Code with GitHub Copilot and GitHub Copilot Chat extensions installed. The AI-guided setup requires an AI coding agent with terminal access.
• PowerShell 7 or later is required for the Microsoft Graph PowerShell module.
• Microsoft Graph PowerShell SDK (beta) installed using Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force.

Required accounts and permissions

• Access to a Microsoft Entra tenant with one of the following roles:
  • Agent ID Developer to create agent identity blueprints and agent identities. Any owner of an agent identity blueprint can create an agent identity for that blueprint without an Agent ID role.
  • Agent ID Administrator for full administrative access to Agent ID resources.

• Additional roles for permission grants:
  • Privileged Role Administrator to grant Microsoft Graph application permissions.
  • Cloud Application Administrator or Application Administrator to grant Microsoft Graph delegated permissions.

Required Microsoft Graph permissions

The client you use (PowerShell or a custom app registration) must be authorized with the following delegated permissions:

Required agent code (optional)

If you already have a working agent project (Python, Node.js, or .NET) that needs an Agent ID identity, have the project directory available. If you don't have one yet, you can still complete the blueprint setup independently.

Get the setup instructions file

The AI-guided setup uses the instructions found in the Microsoft Skills GitHub repository.

Run the AI-guided setup

Follow these steps to start the AI-guided setup.

Step 1: Open your project in VS Code

Open your agent project directory (or any working directory) in Visual Studio Code.

Step 2: Open GitHub Copilot Chat in agent mode

Open the GitHub Copilot Chat panel and switch to Agent mode. Agent mode gives GitHub Copilot the ability to run terminal commands, read files, and interact with your environment, which the AI-guided setup requires.

Step 3: Attach the instructions file and start

In the Copilot Chat input, attach the agent-id-setup-instructions.md file and send it with a short prompt. For example:

Follow the steps in #file:agent-id-setup-instructions.md

The AI agent reads the instruction file and begins the guided setup. It creates a task list and works through the steps sequentially:

1. Validate prerequisites: Checks Microsoft Entra roles, validates that PowerShell 7+ and the Microsoft Graph beta module are installed.
2. Authorize and connect: Connects to Microsoft Graph with the required scopes and sets the profile to beta.
3. Create the agent identity blueprint: Collects a display name, identifies the sponsor (you), creates the blueprint with the required @odata.type and OData-Version headers, and records the appId.
4. Configure credentials: Adds a managed identity (for production) or a certificate or client secret (for local development/testing) to the blueprint.
5. Configure identifier URI and scope: Sets identifierUris to api://{appId}, creates an access_agent OAuth2 permission scope for agent-to-agent and user-to-agent communication.
6. Create the blueprint principal: Creates the service principal for the blueprint (the principal is not autocreated and must be done explicitly).
7. Create agent identities: Creates one or more agent identity service principals under the blueprint.

Step 4: Respond to prompts

The AI agent pauses at specific points to collect input from you:

• Display name: The display name for your agent identity blueprint (for example, "Contoso Budget Agent").
• Sponsor: The user or group who is accountable for the agent. Defaults to the currently signed-in user.
• Owner: The user or service principal who can make technical changes to the blueprint. Optional but recommended.
• Credential type: Whether to use a managed identity (recommended for production) or a certificate or client secret (for local development).
• Agent identity count: How many agent identities to create under this blueprint.
• Derived value confirmation: Review autogenerated names and URIs before resources are created.

Step 5: Verify in the Microsoft Entra admin center

After the setup completes, the AI agent provides instructions on how to verify the resources:

1. Sign in to the Microsoft Entra admin center as at least an Agent ID Developer.
2. Browse to Entra ID > Agents > Agent identities to see your new agent identity blueprint and any agent identities created under it.
3. Verify the blueprint has the correct credentials, identifier URI, and scope configured.

What the AI-guided setup covers

The AI-guided setup automates the following stages of the Agent ID integration:

Common pitfalls the AI-guided setup handles

The Agent ID APIs have several requirements that the AI-guided setup detects and resolves automatically, but they're not obvious requirements. Understanding these pitfalls can be helpful if you need to debug issues or extend the setup.

OData-Version header is required

All Agent ID API calls that use @odata.type require the OData-Version: 4.0 header. If you omit this header, the @odata.type field is silently ignored, causing the API to create a standard application instead of an agent identity blueprint. The AI-guided setup always includes this header.

Blueprint principal isn't autocreated

Creating an agent identity blueprint (POST /applications) does not automatically create its blueprint principal (service principal). Without the blueprint principal, all subsequent agent identity creation fails with:

400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

The AI-guided setup always creates the blueprint principal immediately after the blueprint. It also handles the idempotent case. If a previous run created the blueprint but crashed before creating the principal, the setup detects this event and creates the missing principal.

Sponsors are required

Sponsors are required and can be users, groups with dynamic membership, or unified groups. Both blueprint and agent identity creation require a sponsors@odata.bind field. Without it, you receive:

400: No sponsor specified. Please provide at least one sponsor.

The AI-guided setup only accepts User objects for sponsor assignment and uses the /users/{objectId} URL format (not /directoryObjects/ or /servicePrincipals/). The setup resolves the current user's object ID and uses it as the default sponsor. To assign a supported group as sponsor for a blueprint, use the Microsoft Graph API directly.

Permission propagation takes 30–120+ seconds

After you grant admin consent for Agent ID permissions, newly granted permissions don't appear in tokens immediately. The token endpoint serves cached claims, and propagation can take 30-120 seconds or more.

The AI-guided setup handles recent permission changes by retrying operations with exponential backoff when a 403 is received. If you're scripting this manually, implement retry logic:

# Example: Retry with backoff after admin consent
$maxRetries = 5
for ($i = 0; $i -lt $maxRetries; $i++) {
    try {
        # Attempt the operation
        $result = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 403 -and $i -lt $maxRetries - 1) {
            $wait = 20 * ($i + 1)
            Write-Host "Permission not yet propagated. Retrying in $wait seconds..."
            Start-Sleep -Seconds $wait
            # Disconnect and reconnect to force a fresh token
            Disconnect-MgGraph
            Connect-MgGraph -Scopes $scopes
        } else {
            throw
        }
    }
}

Agent identities can't have password credentials

Agent identities are service principals without backing application objects. Attempting to add a passwordCredential directly to an agent identity results in:

PropertyNotCompatibleWithAgentIdentity

Credentials must be configured on the blueprint, not on individual agent identities. Use managed identity federation (recommended) or add secrets/certificates to the blueprint, and agent identities inherit the credential through impersonation.

Identifier URI must be set explicitly

The blueprint's identifierUris field isn't set by default. Without it, the OAuth2 scope api://{appId}/.default won't resolve, and token acquisition for the agent will fail. The AI-guided setup always configures this value as part of the scope setup step.

Federated identity credential path for blueprints

When adding federated identity credentials (FIC) for managed identity federation, you must use the agent-specific API path:

POST /applications/{blueprint-obj-id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials

Using the /applications/{id}/federatedIdentityCredentials path might work for agent identity blueprints, but it's not supported and isn't recommended.

Token issuer varies by endpoint version

When validating tokens in your agent backend, be aware of the following variations:

• v1.0 tokens use issuer https://sts.windows.net/{tenant-id}/
• v2.0 tokens use issuer https://login.microsoftonline.com/{tenant-id}/v2.0

Accept both formats in your token validation logic.

Troubleshooting

AI agent doesn't run terminal commands

If the AI agent describes commands but doesn't execute them, make sure you're using Agent mode in GitHub Copilot Chat. Ask and Edit modes don't have terminal access.

AI agent skips validation steps

The instruction file enforces strict step ordering. If the AI agent appears to skip a step, remind it to follow the instructions from the beginning. For example:

Please start from Step 1 in the setup instructions and work through each step in order.

Graph commands fail with 403-Forbidden

The most common causes of 403 errors:

• Permission propagation delay: Wait 1–2 minutes after admin consent and retry.
• Missing admin consent: Verify that the required permissions have admin consent granted in the Microsoft Entra admin center under App registrations > your client app > API permissions.

Blueprint creation succeeds but returns a standard application

This result happens when the OData-Version: 4.0 header is missing or the @odata.type property is omitted. Verify both are present in the request. If using PowerShell cmdlets, ensure you're using the beta module and passing the correct body structure.

Agent identity creation fails with "Blueprint Principal does not exist"

The blueprint principal must be created as a separate step after the blueprint. Run:

POST https://graph.microsoft.com/beta/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

{
  "appId": "<your-blueprint-app-id>"
}

Credential lifetime policy errors

Your tenant might have credential lifecycle policies that restrict the maximum lifetime for client secrets. If you receive an error about credential lifetime when adding a password, reduce the endDateTime value to align with your organization's policy.

Configuration values need to change

If you need to change configuration values after the setup, you can:

• Rerun the AI-guided setup with updated values. The idempotent checks skip resources that already exist correctly.
• Use Microsoft Graph PowerShell to update specific properties with PATCH requests.

Next steps

• Create and delete agent identities
• Administrative relationships in Agent ID (Owners, sponsors, and managers)
• Agent identities, service principals, and applications
• Agent identity blueprint concepts