Edit

Microsoft Entra Agent ID APIs in Microsoft Graph overview

Microsoft Entra Agent ID APIs in Microsoft Graph help you create, secure, and manage AI agent identities operating in your organization. You can programmatically create agent identities, control their access to resources, and monitor their activities through a centralized platform.

In this article, you learn about the key concepts and APIs for managing agent identities in Microsoft Graph, including the components that make up an agent identity, how to apply security and governance policies to agents, and the permissions required to manage agents programmatically.

To learn more about the Microsoft Entra Agent ID, see What is Microsoft Entra Agent ID.

Building blocks of agent identities

The following core components comprise Microsoft Entra Agent ID's architecture:

Component Purpose Microsoft Graph resource
Blueprint Template defining the agent identity type, including permissions that agent identities are preauthorized to automatically inherit agentIdentityBlueprint
Blueprint principal Record of blueprint's addition to a tenant agentIdentityBlueprintPrincipal
Agent identity Primary identity for authentication agentIdentity
Agent user Optional account for scenarios that require a user account agentUser
Agent registry (deprecated) Centralized repository for agent management that serves as the platform for managing agent card manifests, agent instances, and agent collections.

Important

Upcoming change to Agent Registry APIs

Starting May 2026, the Agent Registry APIs in Microsoft Graph will be replaced by the Agent Registry APIs powered by Microsoft Agent 365. This change consolidates agent management experiences to make it easier to observe, govern, and secure all agents in your tenant. We recommend that you plan to migrate to the new Agent 365-based APIs when they are released. Learn more about Agent Registry convergence with Microsoft Agent 365.

Learn more about the agent identity architecture in Microsoft Entra Agent ID key concepts.

Microsoft Entra Agent ID extends the comprehensive security and governance capabilities of Microsoft Entra to AI agents, including Conditional Access, Identity Protection, governance, and audit logs.

Ownership and accountability

Each agent identity should have a designated party accountable for the agent's actions, access permissions, and overall security posture to ensure accountability and proper governance. Microsoft Graph APIs let you assign and manage the following metadata for agent identities, to support this principle.

Metadata Applies to
owner agentIdentityBlueprint, agentIdentityBlueprintPrincipal, agentIdentity
sponsor agentIdentityBlueprint, agentIdentityBlueprintPrincipal, agentIdentity, agentUser
manager agentUser

See Administrative relationships in Microsoft Entra Agent ID (owners, sponsors, and managers) for more information.

Conditional Access

You can programmatically apply Conditional Access policies to enforce access policies on AI agents, based on agent identity, risk and other contextual factors.

  • Use the What If evaluation API to simulate how Conditional Access policies would affect agent identities trying to access resources.
  • Use the Conditional Access policy APIs to apply or manage Conditional Access policies for AI agents accessing organizational resources. You can apply these policies based on agent risk level, or custom security attributes assigned to the agents.

Identity Protection

Microsoft Entra ID Protection continuously evaluates agent risk based on various signals and machine learning. You can use the agentRiskDetection and riskyAgent resource types to identify and manage agent risk in your organization, including dismissing or confirming detected risks. Confirmed risks can trigger automated remediation actions such as Conditional Access policy enforcement.

Governance

Microsoft Entra ID Governance extends to AI agents, enabling you to manage the access lifecycle of agent identities in the same way as other identities. With governance applied to agent identities, you can ensure agents have a responsible person providing oversight throughout the agent lifecycle, and that agent access doesn't persist longer than needed.

  • Use access packages via the entitlement management APIs to assign agent identities access to security groups, application OAuth permissions (including Microsoft Graph permissions), and Microsoft Entra roles. The agent identity itself, its owner, its sponsor, or an administrator can request access packages on behalf of the agent.
  • Assign sponsors to agent identities and agent users to designate accountable human users responsible for making decisions about the agent's lifecycle and access. Sponsors receive notifications when access package assignments approach expiry and can approve renewals or allow access to expire.
  • Use access reviews to periodically verify that agent identities still need the access they have.
  • Use lifecycle workflows to automate agent identity sponsor lifecycle tasks for effective governance and compliance, such as triggering notifications when agent identity sponsor changes or transferring sponsorship responsibilities from a user to their manager.

For a complete overview of governance capabilities for agent identities, see Microsoft Entra ID Governance for agent identities.

Activity monitoring

Microsoft Entra sign-in reports and audit logs capture activities performed by agent identities, providing visibility into agent operations for compliance and security monitoring - from creation of agent identities to configuration changes on agents including assignments of roles and permissions.

Permissions for managing agent identities

Microsoft Graph provides granular permissions to manage agent identities and their associated components. The permissions follow the following patterns and are published in the Microsoft Graph permissions reference.

Permissions for managing the agent registry:

  • AgentCardManifest.Read*
  • AgentCollection.Read*
  • AgentInstance.Read*

Permissions for managing the agent identity blueprints and identities:

  • AgentIdentity*

Permissions for nmanaging agent users:

  • AgentIdUser.Read*

Managing Conditional Access policies, Identity Protection, and viewing audit logs for agents require the same permissions as managing these features for other identity types in Microsoft Entra. For more information, see the corresponding API articles for each feature.

Microsoft Graph permissions blocked for agents

Agent identities use the same Microsoft Graph permission model as other identities. Therefore, they can be granted delegated or application permissions to access Microsoft Graph APIs.

However, because of the autonomous nature of agents and the potential risks they pose, the following high-risk Microsoft Graph API permissions are explicitly blocked for agents to prevent misuse or unintended access to sensitive data. These permissions can't be granted to agent identities through Microsoft Graph or Microsoft Entra admin center.

Legend:

  • ❌ indicates the permission is blocked in that category
  • ➖ indicates the permission is not applicable/blocked in that category
Permission name Delegated Application
AgentIdentity.Create ➖ ❌
AgentIdentity.Create.All ➖ ❌
AgentIdentity.CreateAsManager ➖ ❌
AgentIdentityBlueprint.Create ➖ ❌
AgentIdentityBlueprint.CreateAsManager ➖ ❌
AgentIdentityBlueprint.ReadWrite.All ➖ ❌
AgentIdentityBlueprintPrincipal.Create ➖ ❌
Application.ReadWrite.All ➖ ❌
Application.ReadWrite.OwnedBy ➖ ❌
AppRoleAssignment.ReadWrite.All ➖ ❌
BitlockerKey.Read.All ➖ ❌
Calendars.Read ➖ ❌
ChannelMessage.Read.All ➖ ❌
ChannelMessage.Read.Group ➖ ❌
Chat.Read.All ➖ ❌
Chat.ReadWrite.All ➖ ❌
ConsentRequest.ReadWrite.All ➖ ❌
CustomSecAttributeAssignment.ReadWrite.All ❌ ❌
CustomSecAttributeDefinition.ReadWrite.All ❌ ❌
DelegatedPermissionGrant.ReadWrite.All ❌ ❌
Device.ReadWrite.All ➖ ❌
Device.Write.Restricted ❌ ❌
DeviceManagementConfiguration.Read.All ➖ ❌
Directory.AccessAsUser.All ❌ ➖
Directory.ReadWrite.All ❌ ❌
Directory.Write.Restricted ❌ ❌
Domain.ReadWrite.All ❌ ❌
EduRoster.ReadWrite.All ➖ ❌
EntitlementManagement.ReadWrite.All ➖ ❌
Files.Read.All ➖ ❌
Files.ReadWrite.All ➖ ❌
Group.Create ➖ ❌
Group.ReadWrite.All ❌ ❌
Group.Write.Restricted ❌ ➖
GroupMember.ReadWrite.All ❌ ❌
IdentityProvider.ReadWrite.All ➖ ❌
LifecycleManagement.ReadWrite.All ➖ ❌
Organization.ReadWrite.All ➖ ❌
Policy.ReadWrite.AuthenticationMethod ➖ ❌
Policy.ReadWrite.CrossTenantAccess ➖ ❌
Policy.ReadWrite.PermissionGrant ➖ ❌
Policy.ReadWrite.SecurityDefaults ➖ ❌
PrintJob.ReadWrite.All ➖ ❌
PrivilegedAccess.ReadWrite.AzureAD ➖ ❌
PrivilegedAccess.ReadWrite.AzureResources ➖ ❌
RoleManagement.ReadWrite.All ❌ ➖
RoleManagement.ReadWrite.Directory ❌ ❌
Sites.FullControl.All ➖ ❌
Sites.Manage.All ➖ ❌
Sites.Read.All ➖ ❌
Sites.ReadWrite.All ➖ ❌
Tasks.ReadWrite.All ➖ ❌
User-PasswordProfile.ReadWrite.All ❌ ❌
User.DeleteRestore.All ❌ ❌
User.EnableDisableAccount.All ❌ ❌
User.Invite.All ➖ ❌
User.ReadWrite.All ❌ ❌
UserAuthenticationMethod.Read.All ❌ ➖
UserAuthenticationMethod.ReadWrite.All ❌ ❌

Related content

What is Microsoft Entra Agent ID

  • Last updated on