Index of every page on this site: llms.txt
All skills
microsoft avatar

/entra-agent-id

@0d60658
by microsoftmicrosoft/skills3.2k stars
373
Run it yourself

Microsoft Entra Agent ID (preview) for creating OAuth2-capable AI agent identities via Microsoft Graph beta API. Covers Agent Identity Blueprints, BlueprintPrincipals, Agent Identities, required permissions, sponsors, and Workload Identity Federation. Includes Microsoft Entra SDK for AgentID (containerized sidecar) for polyglot agent authentication (Docker/Kubernetes), 3P agent integration, autonomous and interactive agent patterns. Triggers: "agent identity", "agent id", "Agent Identity Blueprint", "BlueprintPrincipal", "entra agent", "agent identity provisioning", "Graph agent identity", "entra sidecar", "agent id sidecar", "auth sidecar", "3P agent", "third-party agent identity", "polyglot agent auth".

Use this Skill: https://skilld.dev/gh/microsoft/skills/entra-agent-id

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈183 tokens for metadata: the name and description. ≈2.2k when used: this file. ≈5.8k more on demand in 3 files.

Description uses 9.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈731 characters, or 9.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Microsoft Entra Agent ID

Create and manage OAuth2-capable identities for AI agents using Microsoft Graph beta API.

Preview API — All Agent Identity endpoints are under /beta only. Not available in /v1.0.

Before You Start

Search microsoft-docs MCP for the latest Agent ID documentation:

  • Query: "Microsoft Entra agent identity setup"
  • Verify: API parameters match current preview behavior

Conceptual Model

Agent Identity Blueprint (application)        ← one per agent type/project
  └── BlueprintPrincipal (service principal)   ← MUST be created explicitly
        ├── Agent Identity (SP): agent-1       ← one per agent instance
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

Prerequisites

PowerShell (recommended for interactive setup)

# Requires PowerShell 7+
Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force

Python (for programmatic provisioning)

pip install azure-identity requests

Required Entra Roles

One of: Agent Identity Developer, Agent Identity Administrator, or Application Administrator.

Environment Variables

AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<app-registration-client-id>
AZURE_CLIENT_SECRET=<app-registration-secret>

Authentication

⚠️ DefaultAzureCredential is NOT supported. Azure CLI tokens contain Directory.AccessAsUser.All, which Agent Identity APIs explicitly reject (403). You MUST use a dedicated app registration with client_credentials flow or connect via Connect-MgGraph with explicit delegated scopes.

PowerShell (delegated permissions)

Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "User.Read"
)
Set-MgRequestContext -ApiVersion beta

$currentUser = (Get-MgContext).Account
$userId = (Get-MgUser -UserId $currentUser).Id

Python (application permissions)

import os
import requests
from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id=os.environ["AZURE_TENANT_ID"],
    client_id=os.environ["AZURE_CLIENT_ID"],
    client_secret=os.environ["AZURE_CLIENT_SECRET"],
)
token = credential.get_token("https://graph.microsoft.com/.default")

GRAPH = "https://graph.microsoft.com/beta"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",  # Required for all Agent Identity API calls
}

Core Workflow

Step 1: Create Agent Identity Blueprint

Sponsors are required and must be User objects — ServicePrincipals and Groups are rejected.

import subprocess

# Get sponsor user ID (client_credentials has no user context, so use az CLI)
result = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
)
user_id = result.stdout.strip()

blueprint_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/applications", headers=headers, json=blueprint_body)
resp.raise_for_status()

blueprint = resp.json()
app_id = blueprint["appId"]
blueprint_obj_id = blueprint["id"]

Step 2: Create BlueprintPrincipal

This step is mandatory. Creating a Blueprint does NOT auto-create its service principal. Without this, Agent Identity creation fails with: 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprintPrincipal",
    "appId": app_id,
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=sp_body)
resp.raise_for_status()

If implementing idempotent scripts, check for and create the BlueprintPrincipal even when the Blueprint already exists (a previous run may have created the Blueprint but crashed before creating the SP).

Step 3: Create Agent Identities

agent_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentity",
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=agent_body)
resp.raise_for_status()
agent = resp.json()

API Reference

Operation Method Endpoint OData Type
Create Blueprint POST /applications Microsoft.Graph.AgentIdentityBlueprint
Create BlueprintPrincipal POST /servicePrincipals Microsoft.Graph.AgentIdentityBlueprintPrincipal
Create Agent Identity POST /servicePrincipals Microsoft.Graph.AgentIdentity
List Agent Identities GET /servicePrincipals?$filter=... —
Delete Agent Identity DELETE /servicePrincipals/{id} —
Delete Blueprint DELETE /applications/{id} —

All endpoints use base URL: https://graph.microsoft.com/beta

Required Permissions

Permission Purpose
Application.ReadWrite.All Blueprint CRUD (application objects)
AgentIdentityBlueprint.Create Create new Blueprints
AgentIdentityBlueprint.ReadWrite.All Read/update Blueprints
AgentIdentityBlueprintPrincipal.Create Create BlueprintPrincipals
AgentIdentity.Create.All Create Agent Identities
AgentIdentity.ReadWrite.All Read/update Agent Identities

There are 18 Agent Identity-specific Graph application permissions. Discover all:

az ad sp show --id 00000003-0000-0000-c000-000000000000 \
  --query "appRoles[?contains(value, 'AgentIdentity')].{id:id, value:value}" -o json

Grant admin consent (required for application permissions):

az ad app permission admin-consent --id <client-id>

Admin consent may fail with 404 if the service principal hasn't replicated. Retry with 10–40s backoff.

Cleanup

# Delete Agent Identity
requests.delete(f"{GRAPH}/servicePrincipals/{agent['id']}", headers=headers)

# Delete BlueprintPrincipal (get SP ID first)
sps = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '{app_id}'",
    headers=headers,
).json()
for sp in sps.get("value", []):
    requests.delete(f"{GRAPH}/servicePrincipals/{sp['id']}", headers=headers)

# Delete Blueprint
requests.delete(f"{GRAPH}/applications/{blueprint_obj_id}", headers=headers)

Best Practices

  1. Always create BlueprintPrincipal after Blueprint — not auto-created; implement idempotent checks on both
  2. Use User objects as sponsors — ServicePrincipals and Groups are rejected
  3. Handle permission propagation delays — after admin consent, wait 30–120s; retry with backoff on 403
  4. Include OData-Version: 4.0 header on every Graph request
  5. Use Workload Identity Federation for production auth — for local dev, use a client secret on the Blueprint (see references/oauth2-token-flow.md)
  6. Set identifierUris on Blueprint before using OAuth2 scoping (api://{app-id})
  7. Never use Azure CLI tokens for API calls — they contain Directory.AccessAsUser.All which is hard-rejected
  8. Check for existing resources before creating — implement idempotent provisioning

References

File Contents
references/oauth2-token-flow.md Production (Managed Identity + WIF) and local dev (client secret) token flows
references/known-limitations.md 29 known issues organized by category (from official preview known-issues page)
references/sdk-sidecar.md Microsoft Entra SDK for AgentID — endpoints, 3P agent patterns, Docker/K8s deployment, security

External Links

Resource URL
Official Setup Guide https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions
AI-Guided Setup https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-ai-guided-setup
Microsoft Entra SDK for AgentID — Overview https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview
Microsoft Entra SDK for AgentID — Endpoints https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/endpoints

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill facilitates the management of Microsoft Entra Agent IDs using official Microsoft tools and APIs. It includes important considerations for handling Azure credentials and provides guidance on transitioning from local development secrets to production-grade authentication methods.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    4/4 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 0d60658. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 8 months ago

README badge

README badge for microsoft/skills/entra-agent-id