Policy Engine

Overview

The Atlas Agent Engine Policy Engine gives organization admins runtime control over agent execution. Admins author policies within the organization scope, the project scope, or both. The control plane merges the policies that apply to a project into a single effective configuration, and the Orchestration Engine (OE) enforces that configuration per execution.

Policies control the actions an agent takes, such as which tools and models it invokes and how much work a single run performs. Policies fall into two categories:

• Allowlists restrict which tools and models the agent can call.

• Execution budgets cap the resources a single execution can consume, such as the number of tool calls, the number of large language model (LLM) calls, and the execution duration.

To control the content that passes through an agent, see Use Content Guardrails.

Policy Types

Each policy type has a kind, which describes the shape of the policy's value. The kind determines how the Policy Engine merges organization and project policies. The following policy types are available:

To learn about the policy denial error, see Enforcement.

Token totals accumulate after each model response rather than before an LLM call. For more information, see Limitations.

If an agent delegates a task to a child agent, the child inherits the parent's root session, so both agents run in the same session. Their combined tokens count toward one MAX_TOKENS_PER_SESSION total rather than a separate total per agent. To learn more about agent-to-agent delegation, see Use Agent-to-Agent Communication.

Policy Scope and Inheritance

You can author a policy within the organization scope or the project scope. An organization policy applies to every project in the organization. Every project policy must be at least as restrictive as the organization policy of the same kind. When two scopes define the same policy type, the Policy Engine merges them into one effective value for the project.

The merge rule depends on the policy kind. The following table lists each policy kind and its corresponding merge rule:

If you save a project policy that is less restrictive than the organization policy of the same kind, the Atlas Agent Engine rejects the request. To raise a limit or widen an allowlist for a project, an organization admin must first change the organization policy.

Enforcement

The OE evaluates the effective policies at specific checkpoints during each execution:

When a policy check fails, the OE halts the execution and returns a policy denial error to the caller. The error includes an error_code of policy_denied and a message in the form Policy denied: <reason> that identifies the reason for the denial.

Policy Propagation

After you create, update, or delete a policy, the Atlas Agent Engine applies the change within approximately one minute. The Atlas Agent Engine first rebuilds the effective configuration for each affected project, and then delivers that configuration to the OE that runs the project's agents.

Each execution takes a snapshot of the effective policies when it starts and uses that snapshot for its entire lifetime. Policy changes apply only to executions that start after the change propagates. Policy changes do not affect in-flight executions.

If the Atlas Agent Engine cannot deliver a change, the OE continues to enforce the last configuration that it received. To check which projects have not received a change, see Check Organization Policy Rollout.

Create and Edit Policies

You can create and edit policies from the platform UI or the REST API.

Preview an Organization Allowlist

Because an allowlist merges as an intersection, removing values from an organization allowlist can leave a project with no permitted values. Before you save changes to an organization policy, call the following endpoint with the ORG_OWNER role:

POST /api/v1/organizations/{orgId}/policies/preview

The API response names each project whose effective allowlist becomes empty and shows the allowlist that the project currently enforces. To learn more, see Preview affected projects.

Enable and Disable Policies

The Atlas Agent Engine skips disabled policies when it builds the effective configuration. Both organization and project policies have an enabled flag. To enable or disable a policy, call the PUT API endpoint for the policy's scope and set the enabled flag. You can also enable or disable project policies from the platform UI. To learn more, see Create and Edit Policies.

When you disable a policy, the Atlas Agent Engine preserves the configuration and history of the policy. If you reenable the policy, the Atlas Agent Engine restores the same configuration.

View Effective Policies

The effective view shows how the organization and project scopes resolve for a project. To retrieve the effective view, use the following project endpoint with the project read role:

GET /api/v1/projects/{projectId}/policies/effective

The API response lists every policy type, the merged effective value that the OE enforces, the value that each scope defines, and the scope or scopes in force. The Atlas Agent Engine reads the organization values on your behalf, so you can see the inherited baseline without holding an organization role. To learn more, see List effective policies.

Check Organization Policy Rollout

In the Atlas Agent Engine, projects receive a policy change one at a time rather than together. While an organization policy rollout is in progress, some projects enforce the new policy while others still enforce the previous one. To see the progress of an organization policy rollout, use the following endpoint with the ORG_OWNER or ORG_READ_ONLY role:

GET /api/v1/organizations/{orgId}/policies/rollout

The API response identifies each delayed project, the reason that the project has not rebuilt or received the effective configuration, and the number of attempts that the Atlas Agent Engine has made to rebuild or receive the effective configuration. The API response omits the underlying error text, which the Atlas Agent Engine records in its logs. To learn more, see See organization policy rollout status.

When a project does not receive a saved policy, the Atlas Agent Engine retries delivering the policy to that project and leaves the projects that already received the change untouched. If the failure can't be resolved by retrying the build, such as an invalid policy value, the Atlas Agent Engine immediately stops trying to build that project. If the failure is transient, such as an unreachable project, the Atlas Agent Engine retries to build the project with increasing delay between attempts. The Atlas Agent Engine stops retrying to build the project after 10 failed attempts.

The attempt count resets the next time a user edits the policy. If the Atlas Agent Engine stops retrying a project, correct the policy and save it again to return the project to the rollout queue.

Monitor Policy Denials

The platform UI reports how often policies deny calls in your organization and projects. To learn how to read the Platform UI metrics, see View Policy Denials.

Limitations

The Policy Engine has the following limitations:

• A new or updated policy takes up to one minute to take effect. A policy applies only to executions that start after it propagates. Guardrails take effect almost immediately.

• The OE can exceed a cap by one call. The OE checks duration and token use before each call. If the call hasn't reached the MAX_EXECUTION_DURATION_MS or MAX_TOKENS_PER_EXECUTION limit, it makes the next call, even if the call exceeds these limits.

• The OE can exceed a session token cap by more than one call. One session runs several executions at the same time. The Atlas Agent Engine checks the session caps only after all in-flight calls finish. The MAX_TOKENS_PER_SESSION value might exceed the configured maximum value by the combined tokens of those calls.

• Token caps exclude memory extraction. Tokens that memory extraction consumes do not count toward the MAX_TOKENS_PER_EXECUTION or MAX_TOKENS_PER_SESSION values.

• Denial counts exclude model denials. The View Policy Denials metric doesn't count denials from when a requested model is not defined in the AUTHORIZED_MODELS policy type.

• Tools without a catalog match by name only. A tool that carries no catalog identifier, such as a custom tool, matches AUTHORIZED_TOOLS policy type entries by tool name only. To learn more, see Tool and Catalog Matching.

• Network egress is governed separately. The Policy Engine doesn't control network egress. To learn how to configure network egress restrictions, see Manage Network Egress Policies.