Govern agent kinds and hosted agent container images

Use built-in Azure Policy definitions to control which agent kinds your organization permits and which container images hosted agents can use in Microsoft Foundry. Assign the policies at your governance scope, configure their parameters, and validate the resulting restrictions before enforcing them in production.

Prerequisites

  • An Azure account with an active subscription and a Foundry account with a project for testing.
  • Permissions to assign Azure Policy at the selected scope, such as Owner or Resource Policy Contributor. See Azure Policy and Azure RBAC.
  • Permissions to create and update agents in your test project.
  • Azure CLI, if you use the command-line procedures.
  • For hosted agent tests, a supported container image and access to its registry. See Deploy a hosted agent with a private Azure Container Registry.
  • A nonproduction test environment with both new and existing agents.

Regional availability

The agent-kind and hosted-agent container-image policies are rolling out. They're currently available in the following regions:

  • Canada Central
  • Spain Central
  • Korea Central

Choose the policies and scope

The two definitions address different governance requirements:

Built-in policy Purpose Status
[Preview]: Microsoft Foundry agents should not use denied agent kinds Restrict agent kinds that your organization prohibits. Preview
[Preview]: Microsoft Foundry hosted agents should only use allowed container images Restrict container-based hosted agents to approved image references or patterns. Preview

Both definitions use the Microsoft.CognitiveServices.Data resource provider mode and target Microsoft.CognitiveServices.Data/accounts/projects/agents. The policy resource type isn't an agent creation API endpoint.

Both policies support the following effect values:

Effect Purpose
Audit Evaluate violations without enforcing a deny restriction. This is the default.
Deny Reject applicable requests that violate the policy rule.
Disabled Disable evaluation of the policy rule.

The policy effect and an assignment's enforcement mode are separate settings. When testing Deny, confirm that the assignment uses the default enforcement mode rather than DoNotEnforce. See Azure Policy assignment structure.

Choose a scope that matches your governance boundary:

Scope Resource ID format Intended coverage
Subscription /subscriptions/<subscription-id> Foundry accounts and projects within the subscription.
Resource group /subscriptions/<subscription-id>/resourceGroups/<resource-group-name> Foundry accounts and projects within the resource group.
Foundry account /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<account-name> Projects within the selected Foundry account.

Azure Policy assignments apply at their scope and below. Check inherited assignments, exclusions, and exemptions before interpreting a test result. A more permissive child assignment doesn't cancel a restriction inherited from a parent scope.

Restrict agent kinds

Use [Preview]: Microsoft Foundry agents should not use denied agent kinds to block agent kinds that your organization prohibits.

The definition ID is:

/providers/Microsoft.Authorization/policyDefinitions/b6ca2367-8597-4a3f-ab19-48f58d6d9278
Parameter Type Default Behavior
effect String Audit Select Audit, Deny, or Disabled.
deniedAgentKinds Array [] Match an agent's agentKind against the prohibited values.

This policy is a deny list, not an allow list. Agent kinds that aren't listed don't violate this policy, but other policies and service requirements can still prevent an operation. To permit only approved kinds, identify the supported kinds and explicitly deny the kinds your organization restricts. Review this list when new kinds become available.

The rule uses the in operator, not wildcard matching. Use actual agent-kind identifiers from the agent definition, not programming languages, display labels, or container runtime names. An empty deniedAgentKinds list doesn't restrict any kind through this policy.

The following example denies the hosted kind. Replace it with the kinds your organization intends to restrict.

Assign the agent-kind policy

  1. Sign in and select your subscription:

    az login
    az account set --subscription "<subscription-id>"
    
  2. Inspect the built-in definition:

    az policy definition show \
      --name "b6ca2367-8597-4a3f-ab19-48f58d6d9278" \
      --query "{displayName:displayName,mode:mode,parameters:parameters,policyRule:policyRule}" \
      --output json
    

    Confirm the policy name, deniedAgentKinds parameter, and effect values before assigning it.

  3. Create a local file named agent-kinds-params.json:

    {
      "effect": {
        "value": "Deny"
      },
      "deniedAgentKinds": {
        "value": ["hosted"]
      }
    }
    

    For an audit-first rollout, use Audit instead of Deny.

  4. Assign the policy at your test scope:

    az policy assignment create \
      --name "foundry-denied-agent-kinds" \
      --display-name "Restrict Foundry agent kinds" \
      --scope "<scope-resource-id>" \
      --policy "/providers/Microsoft.Authorization/policyDefinitions/b6ca2367-8597-4a3f-ab19-48f58d6d9278" \
      --params @agent-kinds-params.json
    

    Replace <scope-resource-id> with a scope from the earlier table. Record the assignment ID returned by the command.

Validate approved and restricted kinds

Test each supported kind individually, rather than testing only one permitted kind and one restricted kind.

  1. Inventory the kinds your team uses, and record their exact identifiers. Separate approved kinds from restricted kinds.
  2. Create the test assignment and allow it to propagate. Verify enforcement with a known restricted request before recording the other results.
  3. For each kind, test the available create and update operations in the Foundry portal and through the direct agent API.
  4. Test the playground with both a new agent and an agent created before the assignment. Record whether the operation creates, updates, or invokes an agent.
  5. Edit the assignment's Denied Agent Kinds parameter in Azure Policy. Add a previously approved kind, then repeat the same requests. Remove a restricted kind and repeat them again.
  6. Repeat at subscription, resource-group, and Foundry-account scope, including inherited assignments and a control project outside the selected scope.
Test Expected result when a request is evaluated with Deny
Agent kind isn't in deniedAgentKinds This policy doesn't deny the request.
Agent kind is in deniedAgentKinds This policy denies the request.
Previously approved kind is added to the deny list Subsequent evaluated requests for that kind are denied after the change takes effect.
Previously restricted kind is removed from the deny list This assignment no longer denies that kind; other assignments can still deny it.
Existing agent has a restricted kind Verify how each operation on that existing agent is evaluated. Don't assume the assignment deletes or stops it.
Operation is outside the assignment scope This assignment doesn't apply; check for other applicable assignments.

Approve hosted agent container images

Use [Preview]: Microsoft Foundry hosted agents should only use allowed container images to restrict the image references used by container-based hosted agents.

The definition ID is:

/providers/Microsoft.Authorization/policyDefinitions/d0d9ac6c-628b-46c1-a177-eb22b12ce588
Parameter Type Default Behavior
effect String Audit Select Audit, Deny, or Disabled.
allowedContainerImages Array [] Approve full image references or case-insensitive patterns.

The rule applies when agentKind is hosted and hostedAgent.sourceType is container. An applicable request violates the rule if its container image is missing, empty, or doesn't match any approved entry. Other agent kinds and hosted source types don't match this rule.

An empty allowedContainerImages list matches no images. With Deny, it rejects all applicable container-image requests. Populate the list before enforcing the policy.

Choose image references and patterns

Match the full image reference, including the registry hostname and repository path.

Approved entry example Matching intent
contoso.azurecr.io/agents/support:1.2.3 Approve this full tagged image reference.
contoso.azurecr.io/agents/support@sha256:<image-digest> Approve a specific image digest. Replace <image-digest> with the actual digest.
contoso.azurecr.io/* Approve image references from this registry.
contoso.azurecr.io/agents/* Approve image references under this repository namespace.
contoso.azurecr.io/agents/support:* Approve tagged image references for this repository.

The policy uses Azure Policy's case-insensitive like comparison. Use no more than one * wildcard in each entry. These patterns aren't regular expressions. A bare hostname such as contoso.azurecr.io doesn't match a full image reference; use contoso.azurecr.io/* for a registry-wide pattern.

Entries are alternatives: matching any one entry satisfies the image approval check. Adding a registry-wide pattern also permits other images from that registry, even if you list only one specific image alongside it. Use the narrowest patterns that meet your requirements.

Image approval doesn't grant registry access, verify image signatures, or scan image contents. Your hosted agent still needs the permissions and network connectivity required to pull the image. A mutable tag can point to different content without changing the approved reference. Use a digest when your requirement is approval of a specific image artifact.

Assign the container-image policy

  1. Inspect the built-in definition in your selected subscription.

    az policy definition show \
      --name "d0d9ac6c-628b-46c1-a177-eb22b12ce588" \
      --query "{displayName:displayName,mode:mode,parameters:parameters,policyRule:policyRule}" \
      --output json
    
  2. Create a local file named agent-images-params.json. This example permits one tagged image:

    {
      "effect": {
        "value": "Deny"
      },
      "allowedContainerImages": {
        "value": [
          "contoso.azurecr.io/agents/support:1.2.3"
        ]
      }
    }
    

    Replace the example with an image your organization approves. To approve a registry or namespace instead, use a pattern from the earlier table. For an audit-first rollout, set effect to Audit.

  3. Assign the policy at your test scope:

    az policy assignment create \
      --name "foundry-approved-agent-images" \
      --display-name "Approve hosted agent container images" \
      --scope "<scope-resource-id>" \
      --policy "/providers/Microsoft.Authorization/policyDefinitions/d0d9ac6c-628b-46c1-a177-eb22b12ce588" \
      --params @agent-images-params.json
    

    Record the returned assignment ID.

Validate image approval and redeployment

Use customer-owned registries and real image references that your test agent can pull. Separate policy-denial failures from registry-authentication, networking, and image-startup failures.

  1. Test an approved full image reference and a non-approved reference with otherwise equivalent agent settings.
  2. Test registry-wide and repository patterns in separate assignments or parameter revisions. Include references that match the pattern and references just outside the registry or repository boundary.
  3. Test a new hosted agent, an update to an existing agent's image reference, and redeployment of an existing agent.
  4. Repeat through supported Foundry portal and direct API deployment paths.
  5. Change the approved list and repeat the requests after the change takes effect.
  6. Repeat with inherited assignments at subscription, resource-group, and Foundry-account scope. Include a control project outside the tested scope.
Test Expected result when an applicable request is evaluated with Deny
Full image reference matches an approved entry This policy doesn't deny the request.
Image matches an approved registry or repository pattern This policy doesn't deny the request.
Image is outside all approved references and patterns This policy denies the request.
Container image field is missing or empty This policy denies the request.
Approved list is empty This policy denies applicable container-image requests.
Hosted agent uses a source type other than container This policy rule doesn't apply.
Image is approved but can't be pulled Approval doesn't resolve the registry permission or connectivity failure.

Test both policies together

An approved image doesn't override a restricted agent kind. Likewise, permitting the hosted kind doesn't approve its container image.

  1. Permit the hosted kind and approve the test image. Verify a valid deployment can proceed when no other restrictions block it.
  2. Permit hosted but remove the image from the approved list. Verify image-policy denial on an evaluated request.
  3. Approve the image but add hosted to deniedAgentKinds. Verify agent-kind denial on an evaluated request.
  4. Restrict both the kind and image. Record the error returned; don't assume which policy is reported first.
  5. Repeat after changing an inherited assignment, checking every applicable assignment before expecting a previously denied request to succeed.

Investigate a blocked operation

Capture evidence from the failed operation before changing an assignment.

  1. Record the operation, timestamp, agent kind, image reference if applicable, target project and account, and API or portal path.
  2. Inspect the complete error response. Record any policy definition ID, assignment ID, and request or correlation ID it provides.
  3. In Azure Policy, review assignments at the account and parent scopes, including their parameters, effects, enforcement modes, exclusions, and exemptions.
  4. Compare the request's agent kind or full image reference with the applicable parameters.
  5. Use a permitted kind or approved image, or ask the administrator to review the restriction. Retry after any approved assignment change has taken effect.

Don't assume every deployment failure is a policy denial. Authorization failures, image-pull failures, and invalid agent definitions require separate troubleshooting.