Manage Microsoft Foundry agent availability as an administrator

As an AI Administrator or Global Administrator, use Agent 365 and Microsoft Entra to manage whether Microsoft Foundry agents in your tenant can run. Governance actions control logical agent availability while preserving Foundry agent definitions and infrastructure. This guidance also applies to owners and sponsors of Entra Agent Identity objects, for the actions their permissions allow.

This article explains governance actions, how developer configuration and Entra state affect availability, and the enforcement rollout for existing agents. Use infrastructure intervention as an emergency path when direct Azure resource actions are necessary.

Prerequisites

Govern agents through Agent 365 and Microsoft Entra

Use Agent 365 or Microsoft Entra governance actions as the preferred way to control agent availability. These actions preserve the Foundry agent definition and Azure infrastructure.

Governance actions and their effects

The following table uses canonical action names referenced throughout this article. These actions have different names across Agent 365 and Microsoft Entra, but they represent the same underlying governance actions.

Governance action Agent 365 label Microsoft Entra label Foundry runtime effect under normal enforcement Reversibility
Block Block Disable in this tenant Disables the agent. Reverse with Unblock.
Unblock Unblock Enable Removes the governance restriction. Developer configuration still controls enablement. Can be blocked again.
SoftDelete Delete Delete Disables the agent. Reverse with Restore.
Restore Restore agent Restore agent Removes the deletion restriction. Developer configuration still controls enablement. Can be soft-deleted again.
HardDelete Permanently delete Delete permanently Disables the agent permanently. The agent can't be recovered.

Block, SoftDelete, and HardDelete have the same runtime disablement behavior as developer-facing disablement. Their reversibility differs. Governance deletion doesn't automatically delete Azure resources; infrastructure deletion is a separate action.

For agent identities you sponsor, you can use Block and SoftDelete, but not Unblock, Restore, or HardDelete. If you block or soft-delete an identity by mistake, contact an owner or administrator to recover it.

For agent identities you own, you can use all five actions. Ownership and sponsorship permissions apply only to the identities assigned to you.

Understand effective agent state

Developer configuration and admin state both affect whether an agent can run. In this article, admin state refers to the governance state reflected in the Entra status of the agent identity and agent blueprint. Agents created before the enforcement cutoff bypass Entra-state enforcement through a legacy exception.

Note

An agent's effective state can take up to 10 minutes to reflect a change.

Developer configuration and admin state

Developers can enable or disable an agent in Foundry. Administrators, owners, and sponsors can separately take governance actions on its Entra agent identity. For agents subject to Entra-state enforcement, enabling the agent through one control doesn't override disablement through the other.

The Foundry agent object's state describes whether the agent is enabled or disabled at runtime. The other properties explain how developer configuration and admin state determine that runtime behavior.

Property or status Meaning Possible values
state Describes the agent's actual runtime enablement or disablement, after applying developer configuration, Entra-state enforcement, and any active legacy exception. enabled, disabled.
state_source Identifies the Entra object responsible for disablement. If absent, check configuration_state. agent_blueprint, agent_instance_identity. Omitted when no Entra source applies, including when developer configuration disables the agent.
configuration_state Reflects developer-facing enablement or disablement in Foundry. enabled, disabled.
instance_identity.status Reports the Entra status of the agent identity. active, disabled. Omitted when unset.
blueprint.status Reports the Entra status of the agent blueprint. active, disabled. Omitted when unset.

Under normal enforcement, both controls must permit operation for the agent to be enabled.

Developer configuration Admin state Runtime state (state)
Enabled Permits operation Enabled
Enabled Blocks operation Disabled
Disabled Permits operation Disabled
Disabled Blocks operation Disabled

For example, Unblock doesn't make an agent available if its developer configuration remains disabled. Under normal enforcement, developer-facing enablement doesn't override an Entra block or deletion. A legacy exception bypasses Entra-state enforcement for agents created before the cutoff.

When that exception permits operation and configuration_state is enabled, state remains enabled even if the Entra status is disabled. The exception doesn't override developer-facing disablement.

Identify why an agent is disabled

Use state to determine the agent's runtime behavior, then use state_source to identify why it's disabled.

  1. Check state to determine whether the agent is enabled or disabled at runtime.
  2. If it's disabled, inspect state_source. If that property is absent, check configuration_state for developer-facing disablement.
  3. If state_source is agent_blueprint, inspect blueprint.status. If it's agent_instance_identity, inspect instance_identity.status. Use the governance action appropriate to the affected object's status and your permissions.

Developer-facing enablement doesn't remove an Entra restriction. If configuration_state is disabled, coordinate with the developer or resource owner before changing that configuration. Removing an Entra restriction alone doesn't enable the agent.

Both controls can prevent operation at the same time. When developer configuration disables the agent, state_source is omitted even if Entra also blocks operation. When developer configuration is enabled and both Entra objects are disabled, state_source identifies the agent blueprint. Resolve each restriction before expecting the agent to be enabled under normal enforcement.

Understand enforcement and legacy exceptions

Foundry enforces admin state for agents created on or after October 23, 2026 at 16:00 UTC. An Entra block or deletion prevents these agents from running, even if the developer configuration is enabled.

Agents created before this cutoff bypass Entra-state enforcement through a legacy exception, regardless of their developer configuration or Entra state at the cutoff. They can run with a disabled Entra state when their developer configuration is enabled. The exception doesn't override disabling the agent in Foundry.

Changing developer configuration or enabling the Entra objects doesn't end this exception. A later Entra block or deletion doesn't prevent these agents from running. Review their availability with workload owners rather than relying on Entra governance actions alone.

Find and reconcile legacy exceptions

You can recognize an exception in use when state is enabled despite a disabled Microsoft Entra status. This discrepancy doesn't identify every agent with an exception: an agent can also have enabled Microsoft Entra objects or disabled developer configuration.

Work with each agent's owners to determine whether the agent should run, then review the affected Microsoft Entra objects:

  • If the agent should run, use Unblock for a blocked object or Restore for a soft-deleted object, and ensure its Microsoft Entra state is enabled. A permanently deleted object can't be restored; an approved workload requires re-provisioning with a new identity.
  • If the agent shouldn't run, coordinate with its owners to disable it in Foundry. Use infrastructure intervention when urgent direct action is necessary.

Reconciling Microsoft Entra state doesn't remove the legacy exception or make subsequent Microsoft Entra restrictions effective for that agent.

Infrastructure intervention

Use Agent 365 and Microsoft Entra governance actions to manage agent availability. The following Azure procedures provide an emergency path for direct intervention in Foundry resources and compute.

Infrastructure actions affect every consumer of the resource, including users in other tenants. Prefer reversible disablement or stopping deployments over infrastructure deletion, which permanently removes resources.

Identify the Foundry resource type for an agent

Foundry agents live in projects within a Foundry account resource. A project can contain multiple agents, so actions against a shared project affect more than one agent. Agent applications contain deployments that you can stop or start.

Check the Foundry Azure resource ID in the agent's Platform details in Microsoft 365 admin center. The resource type determines which infrastructure action to use.

Resource type Resource ID pattern1 Reversible infrastructure action
Foundry agent .../projects/{project-name}/agents/{agent-name} Disable or enable the agent endpoint.
Agent application .../projects/{project-name}/applications/{application-name} Stop or start the application's deployments.

1 The full resource ID pattern is omitted for brevity. Both share a common prefix: /subscriptions/{sub-id}/resourceGroups/{group}/providers/Microsoft.CognitiveServices/accounts/{account-name}/projects/{project-name}/.... The key differentiator is the segment after the project: either agents/{agent-name} or applications/{application-name}.

For background on resource organization, see Microsoft Foundry architecture. The following procedures cover each resource type separately.

Coordinate with resource owners

Contact resource owners before intervening whenever possible. For an active threat or harmful behavior, take the necessary action and then notify them. For routine reviews or unexpected costs, work with owners on remediation; intervene independently only when the impact requires urgent action.

Start with the owners listed in Microsoft 365 admin center or the owners and sponsors of the Entra objects. If you can't access the Azure resources, first get Azure access.

To identify who manages the Azure resources, check their role assignments:

  1. In the Azure portal, navigate to the resource group that contains the agent's Foundry project.
  2. Select Access control (IAM) > Role assignments to see who has permissions over the resource.

Assignments such as Owner or Contributor help identify resource managers, but other stakeholders can have less privileged roles. The resource's Activity Log also shows who recently took management actions.

Get Azure access

Microsoft Entra roles and ownership or sponsorship of an Entra object don't automatically grant Azure resource access. Ask resource owners to grant the required Azure roles or take the infrastructure action on your behalf. AI Administrators can't elevate Azure access themselves; if necessary, coordinate with a Global Administrator.

Elevate access to manage Azure subscriptions

If you already have the required Azure permissions, skip elevation. Otherwise, a Global Administrator can elevate access to obtain User Access Administrator at root scope (/). This role allows role assignment across the tenant's Azure subscriptions and management groups.

You still need the appropriate Foundry role for the infrastructure action.

For the full procedure, see Elevate access to manage all Azure subscriptions and management groups.

Important

Remove your elevated access as soon as you finish. Elevation at root scope is a powerful permission, and the principle of least privilege applies. Follow the de-elevation procedure when you complete your tasks.

If your organization uses PIM, deactivate your Global Administrator role assignment after you remove the elevation toggle.

Assign the right roles

After elevation, assign yourself the minimum role needed for your infrastructure action. If a resource owner grants you access instead, ask for the same minimum role. Don't stay at root scope longer than necessary.

Important

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Action Minimum built-in role
View Foundry User
(Reader isn't sufficient)
Disable or enable Foundry User
Delete Foundry User

Assign roles at the narrowest scope possible. For Foundry agents, assign the role over just the Foundry project resource you want to work with. For agent applications, assign the role at the application scope. If you only need to manage agents in a single resource group, assign the role at the resource group scope. Don't assign these roles at the subscription or management group scope.

If your organization uses PIM, consider creating eligible assignments instead of permanent ones. Eligible assignments require activation. This approach creates an audit trail and enforces time limits.

Disable, stop, or delete infrastructure

Use the tabs for your resource type to choose an interface. These procedures change developer configuration or infrastructure, not the Entra governance state.

For Foundry agents, the following interfaces support developer-facing disablement and enablement or infrastructure deletion. These infrastructure actions are separate from Agent 365 and Entra governance actions.

Interface Supported actions
Microsoft 365 admin center Disable, Enable
Foundry portal Disable, Enable, Delete
REST API or CLI Disable, Enable, Delete

The REST API examples use az rest commands to simplify authentication. The easiest way to run these commands is through Azure Cloud Shell. Cloud Shell requires no installation and uses your current Azure sign-in session. If you prefer to work locally, install the Azure CLI and sign in first.

For each REST API example, replace the placeholder values with your own subscription, resource group, Foundry account, project, and other resource names.

Disable or stop an agent

Take an agent offline without deleting it. Disable the Foundry agent endpoint, or stop an agent application's deployments. Enabling or starting it again doesn't override an Entra restriction.

Both procedures require the Azure permissions for the infrastructure action. If necessary, get Azure access first. After you finish, remove any temporary access.

Use Disable or Enable in Microsoft 365 admin center to change the agent's developer configuration.

Select Disable to take the agent endpoint offline. The agent definition and its versions remain intact.

Select Enable to enable the agent's developer configuration again. This action is separate from governance Unblock and doesn't remove an Entra restriction.

Delete an agent (last resort)

Infrastructure deletion permanently removes Foundry resources, unlike Entra governance deletion. Before you delete, confirm with resource owners that no other tenants or teams depend on the resource and that permanent removal is appropriate.

Agent 365 governance deletion doesn't delete Foundry agent resources. Use another interface for infrastructure deletion if truly necessary.

Remove temporary access

When you finish your infrastructure tasks, remove temporary Azure role assignments. If you elevated your access, remove your elevated permissions in reverse order:

  1. Remove Azure role assignments: Remove temporary Foundry role assignments created for this intervention (such as Foundry Owner) from the specific resources.

    Azure portal:

    1. In the Azure portal, navigate to the resource where you assigned yourself roles.
    2. Select Access control (IAM) > Role assignments.
    3. Find your user account in the role assignments list.
    4. Select the assignment and choose Remove.

    Azure CLI:

    # List current role assignments to find the assignment ID
az role assignment list --assignee <your-email> --scope <resource-scope>

# Remove the specific role assignment
az role assignment delete --ids <assignment-id>

  2. Remove User Access Administrator role: Remove the root-level User Access Administrator role from the elevation procedure.

    Azure portal:

    1. In the Azure portal, go to Microsoft Entra ID > Properties.
    2. Under Access management for Azure resources, set the toggle to No.
    3. Select Save.

    Azure CLI:

    # Remove the User Access Administrator role at root scope
az role assignment delete \
  --assignee <your-email> \
  --role "User Access Administrator" \
  --scope "/"

This two-step process ensures you remove both the specific permissions you granted yourself and the broad elevation that enabled those grants.

Related content

  • Last updated on