授予 Agent 365 可观测性权限

#授予 Agent 365 可观测性权限

向 Foundry 托管智能体授予向 Microsoft Agent 365 导出遥测的权限：把 Agent365.Observability.OtelWrite 应用角色分配给该托管智能体的 Entra 智能体身份（Entra Agent Identity）。

当你的托管智能体被配置为向 Agent 365 发送遥测，并且需要 Microsoft Entra 权限来写入可观测性数据时，使用本流程。

先决条件

• Azure CLI 2.x 或更高版本，并且已经登录。运行 az --version 确认。
• 在 Microsoft Entra ID 中拥有全局管理员（Global Administrator）或应用程序管理员（Application Administrator）角色，以便管理应用角色分配。
• 一个已部署、并配置为向 Agent 365 发送遥测的 Foundry 托管智能体。见为 Microsoft Foundry 配置 Agent 365 数据采集。
• 能访问 Azure 门户中托管智能体的应用程序资源，以便取得其 Entra 智能体身份对象 ID。
• 租户中存在 Agent365Observability 服务主体。

注意

托管智能体必须已经部署，其 Entra 智能体身份才会存在。如果在步骤 1 中找不到智能体身份对象 ID，见排查。

找出所需的 ID

在分配应用角色之前，先收集这三个值。

1. 取得托管智能体的 Entra 智能体身份对象 ID。在 Azure 门户中打开你的智能体应用程序资源。在概述（Overview）窗格中选择 JSON 视图（JSON View），选择最新的 API 版本，并复制智能体身份对象 ID（agentIdentityId）。更多信息见智能体身份。

把这个值保存为 <AGENT_PRINCIPAL_ID>。如果找不到该值，见排查。

注意

对于脚本化工作流，可以用预览版 Microsoft Graph 端点 GET /beta/servicePrincipals/microsoft.graph.agentIdentity 列出智能体身份，并复制你的智能体的 id。该端点处于 beta，不支持用于生产。

2. 取得 Agent365Observability 服务主体的对象 ID：

az rest --method GET \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals?\$filter=displayName eq 'Agent365Observability'" \
  --query "value[0].id" \
  --output tsv

注意

这些命令使用 bash 语法。在 PowerShell 中，用反引号转义美元符号（$filter）。也可以把整个 URI 放进单引号，这样会抑制 PowerShell 中的变量展开。

把这个值保存为 <AGENT365_OBSERVABILITY_SP_ID>。

注意

appRoleId 的值是固定的，不因租户而变——它是 Agent365.Observability.OtelWrite 角色的众所周知标识符。直接从上表复制；不需要用命令再取一次。

分配可观测性应用角色

把 Agent365.Observability.OtelWrite 应用角色分配给托管智能体的 Entra 智能体身份。

注意

替换下面命令中出现的两处 <AGENT_PRINCIPAL_ID>——一处在 URI 路径中，一处在请求体中。把 <AGENT365_OBSERVABILITY_SP_ID> 替换为 Agent365Observability 服务主体对象 ID。appRoleId 的值保持不变。

• 运行命令：

az rest --method POST \
   --uri "https://graph.microsoft.com/v1.0/servicePrincipals/<AGENT_PRINCIPAL_ID>/appRoleAssignments" \
   --body '{
     "principalId": "<AGENT_PRINCIPAL_ID>",
     "resourceId": "<AGENT365_OBSERVABILITY_SP_ID>",
     "appRoleId": "8f71190c-00c8-461d-a63b-f74abde9ba52"
   }'

成功的请求返回 HTTP 201，以及一个包含分配详情的 JSON 对象，其中有 principalId、resourceId 和 appRoleId。

注意

--body 的值使用单引号包裹的 JSON，这在 bash 中有效。在 PowerShell 中，把 JSON 存成文件并用 --body @body.json 传入，或使用转义了内部双引号的 here-string。

核验分配

在测试遥测导出之前，先核验角色分配存在。

1. 运行下面的命令：

az rest --method GET \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/<AGENT_PRINCIPAL_ID>/appRoleAssignments" \
  --query "value[?appRoleId=='8f71190c-00c8-461d-a63b-f74abde9ba52']"

2. 确认响应中包含 Agent365.Observability.OtelWrite 应用角色的一条分配。

3. 分配出现之后，通过在 Microsoft Agent 365 中查看追踪，测试托管智能体的遥测流。见为 Microsoft Foundry 配置 Agent 365 数据采集。

注意

应用角色分配可能需要几分钟才会传播。如果分配后立刻导出遥测失败，等待 2–5 分钟再试。

排查

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/grant-agent-365-permissions