Edit

Set up an agent identity blueprint for a fleet

A fleet runtime uses one agent identity blueprint to create agent identities and to acquire tokens for them. Configure the blueprint once, before the first agent is deployed. For the overall design, see Plan an agent fleet on a shared runtime.

Prerequisites

  • The Agent ID Developer role, to create the blueprint.
  • An administrator who can grant tenant-wide admin consent for Microsoft Graph application permissions.
  • An Azure compute resource for the runtime with a user-assigned managed identity.

Create the blueprint and its principal

  1. Create an agent identity blueprint. Record its client ID.
  2. Create the agent identity blueprint principal in the tenant. The principal creates agent identities and receives admin consent.

Record the tenant ID, blueprint client ID and object ID, blueprint principal object ID, and runtime managed identity client ID for the developer who configures provisioning. Use Record the identifiers for your scenario to distinguish these values.

Add the blueprint credential

Add the runtime's managed identity as a federated identity credential on the blueprint. The runtime and the provisioning service use this credential to authenticate as the blueprint.

Don't use client secrets in production. Every agent in the fleet depends on this credential.

Grant provisioning permissions

The blueprint principal needs the following Microsoft Graph application permissions to provision identities. Neither permission is granted by default.

Permission Required for
AgentIdentity.CreateAsManager Creating and deleting agent identities
AgentIdUser.ReadWrite.IdentityParentedBy Creating and deleting agent's user accounts

Skip AgentIdUser.ReadWrite.IdentityParentedBy if no agent in the fleet needs an agent's user account. Skip both if Agent 365 provisions your agents.

  1. Sign in to the Microsoft Entra admin center.
  2. Browse to Entra ID > App registrations and open the blueprint app registration.
  3. Select API permissions > Add a permission > Microsoft Graph > Application permissions.
  4. Select AgentIdentity.CreateAsManager and, if needed, AgentIdUser.ReadWrite.IdentityParentedBy.
  5. Select Add permissions, and then select Grant admin consent.

Before handing setup back to the runtime developer, confirm that admin consent is granted for each selected Microsoft Graph application permission on this blueprint. A permission listed without consent doesn't make the provisioning service ready. Keep these provisioning permissions separate from the downstream permissions granted to agents.

For more information about these permissions, see Agent identity blueprint principals.

Plan how agents get access

Grant access to each agent identity individually. This approach is recommended because each agent's access stays separate and visible on its agent identity. After the provisioning service creates an agent identity, grant it the application permissions, delegated permissions, Azure role assignments, or other access that the agent needs:

Optionally configure inheritable permissions

If every agent in the fleet needs the same permissions, you can grant them once on the blueprint principal and let each agent identity inherit them. This approach is a convenience: new agent identities receive the permissions without a separate grant.

  1. Add the shared permissions to the blueprint's required resource access.
  2. Configure inheritable permissions for each resource app, such as Microsoft Graph or your custom API.
  3. Have an administrator grant admin consent for those permissions on the blueprint principal.

Inherited permissions don't appear on agent identities in the admin center or through Microsoft Graph. They appear only in the tokens that agent identities receive. For the rules that determine which permissions are inherited, see Inheritable permissions.

Expose the inbound scope

If users or client applications call agents in the fleet, configure an identifier URI and the access_agent scope on the blueprint. Every agent in the fleet shares this audience.

To limit who can call the fleet, define app roles and require assignment on the blueprint principal. App roles apply to every agent in the fleet. Enforce per-agent access in the runtime.

Next steps

Continue with the integration path for the runtime: