[Hosted Agents] Documentation gap: Project managed identity requires account-level RBAC for tracing initialization

[anevesel-mck]

Description

When deploying a hosted agent, the container fails to initialize tracing with a permission error. The project's system-assigned managed identity lacks the required data action to read connections at the account level.

Error Message

2026-02-04T10:45:12.0848320Z stderr F 2026-02-04 10:45:12,082 - azure.ai.agentserver - WARNING - Failed to initialize tracing: (PermissionDenied) The principal `000-000-000-000-000-` lacks the required data action `Microsoft.CognitiveServices/accounts/AIServices/connections/read` to perform `GET /api/projects/{projectName}/connections` operation. For instructions on granting the necessary permissions, see documentation.

Environment

• Service: Microsoft Foundry Hosted Agents
• Identity: Project's system-assigned managed identity

Documentation Gap

The Roles and permissions section states:

• If you have an existing Foundry resource and need to create a new Foundry project to deploy a hosted agent, you need Azure AI Owner roles.
• If you have an existing project and want to create the model deployment and container registry in the project, you need Azure AI Owner role on Foundry in addition to the Contributor role on the Azure subscription.
• If you have everything configured in the project to deploy a hosted agent, you need Reader on the Foundry account and Azure AI User on the project.

However, the documentation describes permissions for the deploying user or service principal, not the project's system-assigned managed identity which actually runs the hosted agent container at runtime.

Root Cause

When the hosted agent container starts, it uses the project's system-assigned managed identity to:

• Initialize OpenTelemetry tracing
• Read connections from the Foundry account via GET /api/projects/{projectName}/connections
• Export traces to Application Insights

This identity requires the Microsoft.CognitiveServices/accounts/AIServices/connections/read data action at the Foundry account scope, which is not documented.

Expected Documentation Update

The documentation should clarify that two identities need permissions:

Identity	Required Role	Scope	Purpose
Deploying user/service principal	Azure AI User + Reader	Foundry Account	Create and manage hosted agents
Project's system-assigned managed identity	Azure AI User	Foundry Account	Runtime operations: read connections, initialize tracing

Impact

• Hosted agents deploy successfully but tracing initialization fails
• Users must discover this permission requirement through trial and error
• The error message references documentation that does not explain this scenario

References

• Hosted agents in Foundry Agent Service (preview)
• Roles and permissions
• Example: Fetch logs using curl