Microsoft Entra Agent ID
Provisioning

AI-guided setup for Microsoft Entra Agent ID

In brief

The guidance now describes the AI assistant as helping with provisioning rather than completing onboarding autonomously. It adds checks for tenant, permissions, approvals, resource choices, existing objects, secrets, and separate provisioning/runtime verification.

What Entra admins need to know

Review proposed operations and permissions, arrange required approvals, inspect existing resources before rerunning, and keep secrets out of prompts and logs.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

AI-guided setup for Microsoft Entra Agent ID

Onboarding to Microsoft Entra Agent ID involves multiple steps: creating an agent identityThis workflow helps you provision a fleet of separately managed agents: it creates a multi-instance blueprint, configuring credentials, setting up identifier URIsconfigures its credentials and scopes, creatingcreates a blueprint principals,principal, and provisioningprovisions child identities. If you're building a cloud or local agent identities. Each step has its own prerequisites, validation checks, and decision points.rather than a hosting platform, start with Choose an integration path. The skill described here isn't the single-instance or local public-client setup procedure.

This AI-guided setup automates this entire workflow by using anAn AI coding agent (suchassistant, such as GitHub Copilot in VS Code)Code, can use a skill to help execute the stepsprovisioning steps. You remain responsible for reviewing proposed changes, arranging administrator approvals, and checking the results. Skill behavior depends on your behalf. Insteadits version and the assistant; its completion summary isn't evidence 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. This instruction file is available as a Skill and can be accessed in more than one way.runtime authorization.

Benefits

The AI-guided setup offers several advantages over the manual workflow:assistant can help assemble provisioning commands, suggest names, and explain error responses. Before allowing changes:

  • Single entry point: One instruction file replacesConfirm the needintended tenant, operator, management client, and required consent. Ask the administrator to navigate between multiple documentation pages. The AI agent followsapprove only the steps in orderoperations your setup requires.
  • Review the sponsor, owner, credential type, and handles transitions automatically.identity count. Don't accept defaults that create a fleet when your scenario needs one cloud or local agent.
  • Automated prerequisite validation: The AI agent validates that you haveRecord the correct Microsoft Entra roles, that the required tools and Graph modules are 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,objects and the AI agent derives all related resource names (blueprint, blueprint principal, agent identities, identifier URIs) using consistent patterns.identifiers for your scenario. Before rerunning an interrupted setup, inspect what already exists; don't assume the skill is idempotent.
  • Inline error handling: When a command fails, the AI agent analyzes the error, suggests a fix,Keep secrets, private keys, and retriesaccess tokens out of prompts and logs. Review any proposed role or permission changes rather than requiring youtreating a failed request as a reason 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.grant broader access.

Prerequisites

The AI-guided setup uses a skill, which is a single instruction file that contains all the steps and validation checks. You can access the skill in one of two ways:

Step 1: Open your project in VS Code

If you don't have the extension, reference the skill directly from GitHub:

Follow the steps in https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/plugins/azure-skills/skills/entra-agent-id/SKILL.md

The AI agent reads the skill and begins the guided setup. It works through the steps sequentially:

Step 5: Verify provisioning and runtime separately

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 blueprints to find the blueprint, then Agent identities to see your new agent identity blueprint and any agent identities created under it.find its child identities.
  3. Verify the blueprint has the correct's credentials, identifier URI, and scope configured.scope. Check the returned object types and parent relationships, not just display names. Confirm that the fleet blueprint principal exists.
  4. Continue with the fleet runtime tutorial for your language and access scenario. Acquire the intended agent's token and make an authorized call to the target API. A provisioned object, compiled application, or issued token alone doesn't establish that the API operation works.

What the AI-guided setup covers

The AI-guided setup automatesUse these source procedures to review the following stages of the Agent ID integration:assistant's proposed provisioning steps:

Stage What happens Related documentation

Common provisioning pitfalls

Review these requirements when checking generated commands or recovering from a failure. Don't assume the AI-guided setup handles

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

OData-Version header is required

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


The AI-guided setup always creates the blueprintCheck for an existing principal immediately after the blueprint. It also handles the idempotent case.before creating it. If a previous run created thestopped after blueprint but crashed before creating the principal, the setup detects this event and createscreation, create the missing principal.principal using the recorded blueprint `appId`. This requirement applies to this fleet workflow, not single-instance blueprints.

### Sponsors are required


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](agent-owners-sponsors-managers.md#sponsors) as sponsor for a blueprint, use the Microsoft Graph API directly.

### PermissionDiagnose authorization before retrying

New consent can take time to appear in a newly acquired token, but a `403 Forbidden` response doesn't by itself prove a propagation takes 30–120+ seconds

After you grant admin consentdelay. First inspect the Graph error code, management client, tenant, granted scopes, and operator authorization. See [Agent identity error codes](error-codes.md).

If an administrator just granted the required permission, wait briefly, reconnect with the same explicit management client ID, tenant, and scopes, and check `Get-MgContext` before retrying. Use bounded retries only for Agenta confirmed transient condition. Stop and retain the status, error code, and request ID permissions, newly granted permissionsif the denial persists; don't appear in tokens immediately. The token endpoint serves cached claims, and propagation can take 30-120 secondssilently exhaust retries 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:

```powershell
# 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
        }
    }
}

broaden permissions. ### Agent identities can't have password credentials

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


Using

Use the `/applications/{id}/federatedIdentityCredentials` path might work for agent identity blueprints, but itsupported request in Configure credentials for the agent identity blueprint. The placeholder is the blueprint's object ID, not supportedits client ID. Preserve the request's OData header and isnverify that the credential't recommended. ### s issuer, subject, and audience match the hosting identity.

Token issuer varies by endpoint version -

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

Use the resource API's supported token-validation library and metadata configuration for its expected token version. Don't simply allow both formats in your tokenissuer strings or disable issuer validation logic. ## to get past a failure. See Validate agent tokens in a downstream API.

Troubleshooting ###

AI agent skips validation steps The instruction file enforces strict step ordering.

A skill provides instructions, not an enforcement mechanism. If the AI agent appears to skipassistant skips a step, remind it to followstop before more changes and request the instructions from the beginning.missing evidence. For example: ```text

Please start from Step 1 in the setup instructions and work through each step in order.
The most common causes of 403 errors:

- **Using Azure CLI or `DefaultAzureCredential` tokens**: Azure CLI tokens include `Directory.AccessAsUser.All`, which Agent Identity APIs reject outright. Use `Connect-MgGraph` with explicit delegated scopes, or a dedicated app registration with `client_credentials`. See the [authentication warning](#required-microsoft-graph-permissions) in the prerequisites.
- **Permission propagation delay*Recent permission change**: Wait 1–2 minutes after adminAfter verifying consent and retry. The AI-guided setup handles this automatically with retry logic.operator authorization, wait briefly and reacquire a token using the same management client and tenant. Don't classify every denial as propagation.
- **Missing admin consent**: Verify that the required permissions have admin consent granted in the [Microsoft Entra admin center](https://entra.microsoft.com/) under **App registrations** > your client app > **API permissions**.

### Blueprint creation succeeds but returns a standard application

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

- RerunInspect the AI-guided setup with updated values. The idempotent checks skipexisting objects and request only the required updates. Before rerunning setup, confirm which resources that already exist correctly.the installed skill will reuse and which it will create.
- Use Microsoft Graph PowerShell to update specific properties with `PATCH` requests.

## Next steps
Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…