entra-agent-id

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Microsoft Entra Agent ID

Create and manage OAuth 2.0-capable identities for AI agents using Microsoft Graph. Every agent instance gets a distinct identity, audit trail, and independently-scoped permission grants.

使用Microsoft Graph创建并管理支持OAuth 2.0的AI Agent身份。每个Agent实例都拥有独立的身份、审计轨迹以及范围独立的权限授予。

Quick Reference

快速参考

Property	Value
Service	Microsoft Entra Agent ID
API	Microsoft Graph ( `https://graph.microsoft.com/v1.0` )
Required role	Agent Identity Developer, Agent Identity Administrator, or Application Administrator
Object model	Blueprint (application) → BlueprintPrincipal (SP) → Agent Identity (SP)
Runtime exchange	Two-step `fmi_path` exchange (autonomous and OBO)
.NET helper	`Microsoft.Identity.Web.AgentIdentities`
Polyglot helper	Microsoft Entra SDK for AgentID (sidecar container)

属性	值
服务	Microsoft Entra Agent ID
API	Microsoft Graph ( `https://graph.microsoft.com/v1.0` )
所需角色	Agent Identity Developer、Agent Identity Administrator或Application Administrator
对象模型	Blueprint（应用）→ BlueprintPrincipal（SP）→ Agent Identity（SP）
运行时交换	两步式 `fmi_path` 交换（自主式和OBO）
.NET辅助工具	`Microsoft.Identity.Web.AgentIdentities`
多语言辅助工具	Microsoft Entra SDK for AgentID（边车容器）

When to Use This Skill

何时使用此技能

Provisioning a new Agent Identity Blueprint and BlueprintPrincipal
Creating per-instance Agent Identities under a Blueprint
Configuring credentials (FIC, Managed Identity, or client secret) on the Blueprint
Implementing the two-step
```
fmi_path
```
runtime token exchange (autonomous or OBO)
Cross-tenant agent token flows
Deploying the Microsoft Entra SDK for AgentID sidecar for polyglot agents (Python, Node, Go, Java)
Granting per-Agent-Identity application (
```
appRoleAssignments
```
) or delegated (
```
oauth2PermissionGrants
```
) permissions

Diagnosing Agent ID errors such as

AADSTS82001

AADSTS700211

, or

PropertyNotCompatibleWithAgentIdentity

预配新的Agent Identity Blueprint和BlueprintPrincipal
在Blueprint下创建每个实例的Agent Identity
在Blueprint上配置凭据（FIC、托管身份或客户端密钥）
实现两步式
```
fmi_path
```
运行时令牌交换（自主式或OBO）
跨租户Agent令牌流
为多语言Agent（Python、Node、Go、Java）部署Microsoft Entra SDK for AgentID边车
为每个Agent Identity授予应用程序（
```
appRoleAssignments
```
）或委托（
```
oauth2PermissionGrants
```
）权限

诊断Agent ID错误，例如

AADSTS82001

、

AADSTS700211

或

PropertyNotCompatibleWithAgentIdentity

MCP Tools

MCP工具

Tool	Use
`mcp_azure_mcp_documentation`	Search Microsoft Learn for current Agent ID setup, Graph API shapes, and SDK configuration

There is no dedicated Agent Identity MCP server today. This skill guides direct Microsoft Graph API calls (PowerShell or Python

requests

). Use

mcp_azure_mcp_documentation

to verify request bodies and endpoints against current docs before running.

工具	用途
`mcp_azure_mcp_documentation`	在Microsoft Learn中搜索当前Agent ID设置、Graph API结构和SDK配置

目前没有专门的Agent Identity MCP服务器。此技能指导直接调用Microsoft Graph API（PowerShell或Python

requests

）。运行前，请使用

mcp_azure_mcp_documentation

工具对照当前文档验证请求体和端点。

Before You Start

开始之前

Use the

mcp_azure_mcp_documentation

tool to search Microsoft Learn for current Agent ID documentation:

"Microsoft Entra Agent ID setup instructions"
"Microsoft Entra SDK for AgentID"

Verify request bodies and endpoints against the installed SDK version — Graph API shapes evolve.

使用

mcp_azure_mcp_documentation

工具在Microsoft Learn中搜索当前Agent ID文档：

"Microsoft Entra Agent ID设置说明"
"Microsoft Entra SDK for AgentID"

对照已安装的SDK版本验证请求体和端点——Graph API结构会不断演进。

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

Concept	Description
Blueprint	Application object that defines a type/class of agent. Holds credentials (secret, certificate, federated identity).
BlueprintPrincipal	Service principal for the Blueprint in the tenant. Not auto-created.
Agent Identity	Service-principal-only identity for a single agent instance. Cannot hold its own credentials.
Sponsor	A User (or Group, for Agent Identity) who is responsible for the identity. Required on creation.

Agent Identity Blueprint (application)         ← 每个Agent类型/项目对应一个
  └── BlueprintPrincipal (service principal)    ← 必须显式创建
        ├── Agent Identity (SP): agent-1        ← 每个Agent实例对应一个
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

概念	描述
Blueprint	定义Agent类型/类别的应用程序对象。存储凭据（密钥、证书、联合身份）。
BlueprintPrincipal	租户中Blueprint的服务主体。不会自动创建。
Agent Identity	单个Agent实例的仅服务主体身份。无法存储自己的凭据。
Sponsor	对身份负责的用户（或针对Agent Identity的组）。创建时必填。

Prerequisites

先决条件

Required Entra Roles

所需Entra角色

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

以下角色之一：Agent Identity Developer、Agent Identity Administrator或Application Administrator。

PowerShell (interactive setup)

PowerShell（交互式设置）

powershell

undefined

powershell

undefined

PowerShell 7+

Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

undefined

Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

undefined

Python (programmatic provisioning)

Python（程序化预配）

bash

pip install azure-identity requests

bash

pip install azure-identity requests

Authentication

身份验证

DefaultAzureCredential
is not supported. Azure CLI tokens carry
Directory.AccessAsUser.All
, which Agent Identity APIs hard-reject (403). Use a dedicated app registration with
client_credentials
, or
Connect-MgGraph
with explicit delegated scopes.

不支持
DefaultAzureCredential
。Azure CLI令牌包含
Directory.AccessAsUser.All
，Agent Identity API会直接拒绝（403）。请使用带有
client_credentials
的专用应用注册，或使用具有显式委托范围的
Connect-MgGraph
。

PowerShell (delegated)

PowerShell（委托式）

powershell

Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "AgentIdentity.Create.All",
    "User.Read"
)

powershell

Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "AgentIdentity.Create.All",
    "User.Read"
)

Python (application)

Python（应用程序式）

python

import os, 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/v1.0"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",
}

python

import os, 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/v1.0"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",
}

Core Workflow

核心工作流

Step 1: Create Agent Identity Blueprint

步骤1：创建Agent Identity Blueprint

Use the typed endpoint. Sponsors must be Users at Blueprint creation. This snippet assumes the

requests

client and

headers

dict from the Python authentication block above.

python

import subprocess
import requests

user_id = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
).stdout.strip()

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

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

使用类型化端点。创建Blueprint时，Sponsor必须是用户。以下代码片段假设使用Python身份验证块中的

requests

客户端和

headers

字典。

python

import subprocess
import requests

user_id = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
).stdout.strip()

blueprint_body = {
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/v1.0/users/{user_id}"
    ],
}
resp = requests.post(
    f"{GRAPH}/applications/microsoft.graph.agentIdentityBlueprint",
    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

步骤2：创建BlueprintPrincipal

Mandatory. Creating a Blueprint does NOT auto-create its service principal. Skipping this step produces:
400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

python

sp_body = {"appId": app_id}
resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal",
    headers=headers, json=sp_body,
)
resp.raise_for_status()

Make your provisioning scripts idempotent — always check for the BlueprintPrincipal even when the Blueprint already exists.

必须执行。创建Blueprint不会自动创建其服务主体。跳过此步骤会导致：
400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

python

sp_body = {"appId": app_id}
resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal",
    headers=headers, json=sp_body,
)
resp.raise_for_status()

确保预配脚本具有幂等性——即使Blueprint已存在，也要始终检查BlueprintPrincipal是否存在。

Step 3: Create Agent Identities

步骤3：创建Agent Identity

Sponsors for an Agent Identity may be Users or Groups.

python

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

Agent Identity的Sponsor可以是用户或组。

python

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

Runtime Authentication

运行时身份验证

Agents authenticate at runtime using credentials configured on the Blueprint (not on the Agent Identity — Agent Identities can't hold credentials).

Option	Use case	Credential on Blueprint
Managed Identity + WIF	Production (Azure-hosted)	Federated Identity Credential
Client secret	Local dev / testing	Password credential
Microsoft Entra SDK for AgentID	Polyglot / 3P agents	Sidecar container acquires tokens over HTTP

For the two-step

fmi_path

exchange (parent token → per-Agent-Identity Graph token) that gives each agent instance a distinct

sub

claim and audit trail, see references/runtime-token-exchange.md.

For OBO (agent acting on behalf of a user), see references/obo-blueprint-setup.md.

For the containerized polyglot auth sidecar (Python, Node, Go, Java — no SDK embedding), see references/sdk-sidecar.md.

For MI+WIF and client-secret setup details, see references/oauth2-token-flow.md.

Agent在运行时使用Blueprint上配置的凭据进行身份验证（而非Agent Identity——Agent Identity无法存储凭据）。

选项	使用场景	Blueprint上的凭据
托管身份 + WIF	生产环境（Azure托管）	联合身份凭据
客户端密钥	本地开发/测试	密码凭据
Microsoft Entra SDK for AgentID	多语言/第三方Agent	边车容器通过HTTP获取令牌

有关两步式

fmi_path

交换（父令牌→每个Agent Identity的Graph令牌，为每个Agent实例提供独特的

sub

声明和审计轨迹），请参阅references/runtime-token-exchange.md。

有关OBO（Agent代表用户操作），请参阅references/obo-blueprint-setup.md。

有关容器化多语言认证边车（Python、Node、Go、Java——无需嵌入SDK），请参阅references/sdk-sidecar.md。

有关MI+WIF和客户端密钥设置详情，请参阅references/oauth2-token-flow.md。

.NET quick path

.NET快速路径

For .NET services, use Microsoft.Identity.Web.AgentIdentities
— it handles Federated Identity Credential management and the two-step exchange for you. See the package README at

github.com/AzureAD/microsoft-identity-web

under

src/Microsoft.Identity.Web.AgentIdentities/

对于.NET服务，请使用**

Microsoft.Identity.Web.AgentIdentities

**——它会为你处理联合身份凭据管理和两步式交换。请查看

github.com/AzureAD/microsoft-identity-web

中

src/Microsoft.Identity.Web.AgentIdentities/

下的包README。

Granting Permissions (Per Agent Identity)

授予权限（每个Agent Identity）

Agent Identities support both application permissions (autonomous) and delegated permissions (OBO). Grants are scoped per Agent Identity, not to the BlueprintPrincipal.

Agent Identity支持应用程序权限（自主式）和委托权限（OBO）。权限授予范围是每个Agent Identity，而非BlueprintPrincipal。

Application permissions (autonomous)

应用程序权限（自主式）

python

graph_sp = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'",
    headers=headers,
).json()["value"][0]

user_read_all = next(r for r in graph_sp["appRoles"] if r["value"] == "User.Read.All")

requests.post(
    f"{GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments",
    headers=headers,
    json={
        "principalId": agent_sp_id,
        "resourceId": graph_sp["id"],
        "appRoleId": user_read_all["id"],
    },
).raise_for_status()

python

graph_sp = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'",
    headers=headers,
).json()["value"][0]

user_read_all = next(r for r in graph_sp["appRoles"] if r["value"] == "User.Read.All")

requests.post(
    f"{GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments",
    headers=headers,
    json={
        "principalId": agent_sp_id,
        "resourceId": graph_sp["id"],
        "appRoleId": user_read_all["id"],
    },
).raise_for_status()

Delegated permissions (OBO)

委托权限（OBO）

python

from datetime import datetime, timedelta, timezone

expiry = (datetime.now(timezone.utc) + timedelta(days=3650)).strftime("%Y-%m-%dT%H:%M:%SZ")

requests.post(
    f"{GRAPH}/oauth2PermissionGrants",
    headers=headers,
    json={
        "clientId": agent_sp_id,
        "consentType": "AllPrincipals",
        "resourceId": graph_sp["id"],
        "scope": "User.Read Tasks.ReadWrite Mail.Send",
        "expiryTime": expiry,
    },
).raise_for_status()

Browser-based admin consent URLs do not work for Agent Identities — use

oauth2PermissionGrants

for programmatic delegated consent.

python

from datetime import datetime, timedelta, timezone

expiry = (datetime.now(timezone.utc) + timedelta(days=3650)).strftime("%Y-%m-%dT%H:%M:%SZ")

requests.post(
    f"{GRAPH}/oauth2PermissionGrants",
    headers=headers,
    json={
        "clientId": agent_sp_id,
        "consentType": "AllPrincipals",
        "resourceId": graph_sp["id"],
        "scope": "User.Read Tasks.ReadWrite Mail.Send",
        "expiryTime": expiry,
    },
).raise_for_status()

基于浏览器的管理员同意URL不适用于Agent Identity——请使用

oauth2PermissionGrants

进行程序化委托同意。

Cross-Tenant Agent Identities

跨租户Agent Identity

Blueprints can be multi-tenant (

signInAudience: AzureADMultipleOrgs

). When exchanging tokens cross-tenant:

Step 1 of the parent token exchange MUST target the Agent Identity's home tenant, not the Blueprint's. Wrong tenant →
AADSTS700211: No matching federated identity record found
.

See references/runtime-token-exchange.md for full cross-tenant examples.

Blueprint可以是多租户的（

signInAudience: AzureADMultipleOrgs

）。跨租户交换令牌时：

父令牌交换的步骤1必须指向Agent Identity的主租户，而非Blueprint的主租户。租户错误会导致
AADSTS700211: No matching federated identity record found
。

完整的跨租户示例请参阅references/runtime-token-exchange.md。

API Reference

API参考

Operation	Method	Endpoint
Create Blueprint	`POST`	`/applications/microsoft.graph.agentIdentityBlueprint`
Create BlueprintPrincipal	`POST`	`/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal`
Create Agent Identity	`POST`	`/servicePrincipals/microsoft.graph.agentIdentity`
Add FIC to Blueprint	`POST`	`/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials`
List Agent Identities	`GET`	`/servicePrincipals/microsoft.graph.agentIdentity`
Grant app permission	`POST`	`/servicePrincipals/{id}/appRoleAssignments`
Grant delegated permission	`POST`	`/oauth2PermissionGrants`
Delete Agent Identity	`DELETE`	`/servicePrincipals/{id}`
Delete Blueprint	`DELETE`	`/applications/{id}`

Base URL:

https://graph.microsoft.com/v1.0

操作	方法	端点
创建Blueprint	`POST`	`/applications/microsoft.graph.agentIdentityBlueprint`
创建BlueprintPrincipal	`POST`	`/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal`
创建Agent Identity	`POST`	`/servicePrincipals/microsoft.graph.agentIdentity`
向Blueprint添加FIC	`POST`	`/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials`
列出Agent Identity	`GET`	`/servicePrincipals/microsoft.graph.agentIdentity`
授予应用权限	`POST`	`/servicePrincipals/{id}/appRoleAssignments`
授予委托权限	`POST`	`/oauth2PermissionGrants`
删除Agent Identity	`DELETE`	`/servicePrincipals/{id}`
删除Blueprint	`DELETE`	`/applications/{id}`

基础URL：

https://graph.microsoft.com/v1.0

。

Required Graph Permissions

所需Graph权限

Permission	Purpose
`AgentIdentityBlueprint.Create`	Create Blueprints
`AgentIdentityBlueprint.ReadWrite.All`	Read/update Blueprints
`AgentIdentityBlueprintPrincipal.Create`	Create BlueprintPrincipals
`AgentIdentity.Create.All`	Create Agent Identities
`AgentIdentity.ReadWrite.All`	Read/update Agent Identities
`Application.ReadWrite.All`	Blueprint CRUD on application objects
`AppRoleAssignment.ReadWrite.All`	Grant application permissions
`DelegatedPermissionGrant.ReadWrite.All`	Grant delegated permissions

Grant admin consent (required for application permissions):

bash

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

After admin consent, tokens may not include new claims for 30–120 seconds — retry with exponential backoff.

权限	用途
`AgentIdentityBlueprint.Create`	创建Blueprint
`AgentIdentityBlueprint.ReadWrite.All`	读取/更新Blueprint
`AgentIdentityBlueprintPrincipal.Create`	创建BlueprintPrincipal
`AgentIdentity.Create.All`	创建Agent Identity
`AgentIdentity.ReadWrite.All`	读取/更新Agent Identity
`Application.ReadWrite.All`	应用程序对象上的Blueprint增删改查
`AppRoleAssignment.ReadWrite.All`	授予应用程序权限
`DelegatedPermissionGrant.ReadWrite.All`	授予委托权限

授予管理员同意（应用程序权限必填）：

bash

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

管理员同意后，令牌可能需要30-120秒才会包含新声明——请使用指数退避重试。

Best Practices

最佳实践

Always create BlueprintPrincipal after Blueprint — not auto-created.

Use typed endpoints (

/applications/microsoft.graph.agentIdentityBlueprint

) instead of raw

/applications

with

@odata.type

Credentials live on the Blueprint — Agent Identities can't hold secrets/certs (
```
PropertyNotCompatibleWithAgentIdentity
```
).
Include
OData-Version: 4.0
on every Graph request.
Use Workload Identity Federation for production — client secrets only for local dev.
Set
identifierUris: ["api://{appId}"]
on the Blueprint before OAuth2 scope resolution.
Never use Azure CLI tokens for Agent Identity APIs —
```
Directory.AccessAsUser.All
```
causes hard 403.

Use
fmi_path
with

client_credentials

— NOT RFC 8693

urn:ietf:params:oauth:grant-type:token-exchange

(returns

AADSTS82001

Always use
/.default
scope in both steps of the exchange — individual scopes fail.
Step 1 targets the Agent Identity's home tenant in cross-tenant flows.
Grant permissions per Agent Identity, not to the BlueprintPrincipal.
Handle permission-propagation delays — retry 403s with 30–120s backoff after admin consent.
Keep the Entra SDK for AgentID on localhost — never expose via LoadBalancer or Ingress.

创建Blueprint后始终创建BlueprintPrincipal——不会自动创建。

使用类型化端点（

/applications/microsoft.graph.agentIdentityBlueprint

）而非带有

@odata.type

的原始

/applications

。

凭据存储在Blueprint上——Agent Identity无法存储密钥/证书（会触发
```
PropertyNotCompatibleWithAgentIdentity
```
）。
每个Graph请求都包含
OData-Version: 4.0
。
生产环境使用工作负载身份联合——客户端密钥仅用于本地开发。
在OAuth2范围解析前，为Blueprint设置
identifierUris: ["api://{appId}"]
。
永远不要将Azure CLI令牌用于Agent Identity API——
```
Directory.AccessAsUser.All
```
会导致直接403错误。

将
fmi_path
与
client_credentials
配合使用——不要使用RFC 8693的

urn:ietf:params:oauth:grant-type:token-exchange

（会返回

AADSTS82001

）。

交换的两个步骤始终使用
/.default
范围——单独范围会失败。
跨租户流程中，步骤1指向Agent Identity的主租户。
为每个Agent Identity授予权限，而非BlueprintPrincipal。
处理权限传播延迟——管理员同意后，对403错误进行30-120秒的退避重试。
将Entra SDK for AgentID保留在本地主机——不要通过LoadBalancer或Ingress暴露。

Troubleshooting

故障排除

Error	Cause	Fix
`AADSTS82001`	Used RFC 8693 token-exchange grant	Use `client_credentials` with `fmi_path`
`AADSTS700211`	Step 1 parent token targeted wrong tenant	Target Agent Identity's home tenant
`AADSTS50013`	OBO user token targets Graph, not Blueprint	Use `api://{blueprint_app_id}/access_as_user`
`AADSTS65001`	Missing grant or used individual scopes	Use `/.default` and verify `oauth2PermissionGrants`
`403 Authorization_RequestDenied`	No grant on this Agent Identity	Add via `appRoleAssignments` or `oauth2PermissionGrants`
`PropertyNotCompatibleWithAgentIdentity`	Tried to add credential to Agent Identity SP	Put credentials on the Blueprint
`Agent Blueprint Principal does not exist`	BlueprintPrincipal not created	Step 2 of the Core Workflow
`AADSTS650051` on admin consent	SP already exists from partial consent	Grant directly via `appRoleAssignments`

错误	原因	修复方法
`AADSTS82001`	使用了RFC 8693令牌交换授予类型	使用带有 `fmi_path` 的 `client_credentials`
`AADSTS700211`	步骤1的父令牌指向了错误的租户	指向Agent Identity的主租户
`AADSTS50013`	OBO用户令牌指向Graph而非Blueprint	使用 `api://{blueprint_app_id}/access_as_user`
`AADSTS65001`	缺少权限授予或使用了单独范围	使用 `/.default` 并验证 `oauth2PermissionGrants`
`403 Authorization_RequestDenied`	此Agent Identity无权限授予	通过 `appRoleAssignments` 或 `oauth2PermissionGrants` 添加
`PropertyNotCompatibleWithAgentIdentity`	尝试为Agent Identity SP添加凭据	将凭据放在Blueprint上
`Agent Blueprint Principal does not exist`	未创建BlueprintPrincipal	执行核心工作流的步骤2
管理员同意时出现 `AADSTS650051`	SP已因部分同意存在	通过 `appRoleAssignments` 直接授予权限

References

参考资料

File	Contents
references/runtime-token-exchange.md	Two-step `fmi_path` exchange: autonomous + OBO, cross-tenant
references/oauth2-token-flow.md	MI + WIF (production) and client secret (local dev)
references/obo-blueprint-setup.md	Configuring the Blueprint as an OAuth2 API for OBO
references/sdk-sidecar.md	Microsoft Entra SDK for AgentID — architecture, configuration, endpoints
references/sdk-sidecar-deployment.md	SDK code patterns (Python/TypeScript), Docker/Kubernetes manifests, security, troubleshooting
references/known-limitations.md	Documented gaps organized by category

文件	内容
references/runtime-token-exchange.md	两步式 `fmi_path` 交换：自主式+OBO、跨租户
references/oauth2-token-flow.md	MI + WIF（生产环境）和客户端密钥（本地开发）
references/obo-blueprint-setup.md	将Blueprint配置为OBO的OAuth2 API
references/sdk-sidecar.md	Microsoft Entra SDK for AgentID——架构、配置、端点
references/sdk-sidecar-deployment.md	SDK代码模式（Python/TypeScript）、Docker/Kubernetes清单、安全、故障排除
references/known-limitations.md	按类别整理的已记录差距

External Links

外部链接

Resource	URL
Agent ID 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	https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview
Microsoft.Identity.Web.AgentIdentities (.NET)	https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.AgentIdentities/README.AgentIdentities.md

资源	URL
Agent ID设置指南	https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions
AI引导式设置	https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-ai-guided-setup
Microsoft Entra SDK for AgentID	https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview
Microsoft.Identity.Web.AgentIdentities（.NET）	https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.AgentIdentities/README.AgentIdentities.md