# Setting up ExecutionRing Privilege Levels for Sandboxed Agent Tool Execution

> Master ExecutionRing privilege levels for sandboxed agent tool execution. Learn how the Agent Governance Toolkit enforces least privilege and resource sandboxes.

- Repository: [Microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit)
- Tags: how-to-guide
- Published: 2026-05-29

---

**Agent Governance Toolkit implements a hypervisor-based Execution-Ring system that assigns agents to one of four privilege tiers (Ring 0–3) based on dynamic trust scores, automatically enforcing least-privilege constraints and resource sandboxes during tool execution.**

The Microsoft Agent Governance Toolkit (AGT) isolates agent-driven tool calls inside a hypervisor-controlled execution environment. The **Execution-Ring model** provides a graduated 4-tier privilege system that dynamically assigns resource access rights based on real-time trust evaluation. This guide demonstrates how to implement ExecutionRing privilege levels to secure agent operations while maintaining operational flexibility.

## Understanding the Execution-Ring Privilege Model

The Execution-Ring model implements a **zero-trust runtime environment** using four distinct privilege tiers. Unlike binary allow/deny systems, this graduated approach lets agents earn higher privileges through clean audit history while enabling automatic demotion upon anomalous behavior.

Each ring maps to specific capabilities:

- **Ring 0**: Full system-level access including file system, network, and process creation. Reserved for trusted internal services.
- **Ring 1**: Elevated but constrained access with limited file paths and network egress. Suitable for vetted super-user agents.
- **Ring 2**: Standard user-level access to read-only data stores and safe APIs. Used by most production business logic agents.
- **Ring 3**: Strict sandbox with whitelisted tool calls only and no external I/O. Isolates untrusted third-party agents or experimental code.

Assignment depends on the **`eff_score`** (effective trust score), a dynamic value calculated from identity verification, past behavior, and policy evaluation defined in [`agent-governance-python/agentmesh-integrations/pydantic-ai-governance/src/pydantic_ai_governance/policy.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agentmesh-integrations/pydantic-ai-governance/src/pydantic_ai_governance/policy.py).

## Core Components and Architecture

According to the [`AGENT-HYPERVISOR-EXECUTION-CONTROL-1.0.md`](https://github.com/microsoft/agent-governance-toolkit/blob/main/AGENT-HYPERVISOR-EXECUTION-CONTROL-1.0.md) specification, the sandbox implementation spans several specialized components:

- **Agent-Hypervisor** (`agent-hypervisor/`): Session manager handling ring assignment and enforcement hooks.
- **Policy Engine** ([`agentmesh-integrations/pydantic-ai-governance/src/pydantic_ai_governance/policy.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agentmesh-integrations/pydantic-ai-governance/src/pydantic_ai_governance/policy.py)): Evaluates trust scores and applies per-ring constraints.
- **Ring-Breach Detector** ([`agent-hypervisor/ring_breach.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-hypervisor/ring_breach.py)): Monitors execution metadata and triggers demotion.
- **Saga Orchestrator** (`agent-hypervisor/saga/`): Coordinates multi-step workflows respecting ring boundaries.
- **Event Stream** (`agent-hypervisor/events/`): Emits `RingAssigned`, `RingElevated`, `RingBreach`, and `ToolExecuted` events for audit trails.

Each ring maintains a **policy bundle** defining allowed tool names, resource limits (CPU, memory, I/O), and execution timeouts.

## Configuring Session-Level Ring Assignment

In [`agent-hypervisor/session.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-hypervisor/session.py), the `Session` class orchestrates agent admission and automatic ring assignment. The hypervisor invokes the trust score callback during `join_agent()` to determine the appropriate tier.

```python
from agent_hypervisor.session import Session
from agent_hypervisor.trust import TrustScoreProvider

# Provide a custom trust-score function (e.g., based on JWT claims)

def my_trust_score(agent_id: str) -> float:
    # In a real deployment this would query a trust DB or evaluate a policy

    return TrustScoreProvider.from_jwt("…signed-jwt…").effective_score

session = Session(
    session_id="demo-session",
    trust_score_cb=my_trust_score,
)

# Join the agent – the hypervisor looks up the score and assigns a ring

ring = session.join_agent(agent_id="my-untrusted-agent")
print(f"Agent joined with Execution Ring {ring}")

```

The `Session` object maintains the ring context for all subsequent operations, enforcing that tools execute only within the assigned privilege boundaries.

## Executing Tools Within Ring Constraints

The `ToolExecutor` class in the hypervisor tooling layer respects the session's current ring during invocation. It automatically applies ring-specific timeouts and blocks disallowed tool names.

```python
from agent_hypervisor.tools import ToolExecutor

executor = ToolExecutor(session=session)

# The executor automatically applies the ring's limits

result = executor.execute(
    tool_name="search_web",
    payload={"query": "latest security best practices"},
    timeout_seconds=5,  # Enforced per-ring timeout

)

print(result.output)

```

If the requested tool violates the current ring's policy bundle, the hypervisor aborts the call before execution begins.

## Implementing Temporary Ring Elevation

Agents may request short-term privilege increases via the elevation API in [`agent-hypervisor/elevation.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-hypervisor/elevation.py). The `ElevationRequest` requires a signed JWT with a strict TTL, validated by the Ring-Breach Detector to prevent privilege escalation attacks.

```python
from agent_hypervisor.elevation import ElevationRequest

# JWT must be signed by a trusted authority and include a short TTL (e.g., 60s)

elev_req = ElevationRequest(
    agent_id="my-untrusted-agent",
    target_ring=2,
    jwt="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"
)

if session.request_elevation(elev_req):
    print("Elevation granted – you now run in Ring 2")
else:
    print("Elevation denied – staying in Ring 3")

```

Approved elevations emit `RingElevated` events to the audit stream and automatically expire when the JWT TTL elapses.

## Detecting Breaches and Enforcing Demotion

The `Ring-Breach Detector` monitors tool execution metadata for policy violations. When an agent exceeds its ring's limits—such as attempting disallowed system calls or exceeding resource quotas—the hypervisor aborts the operation and triggers breach handling.

```python
@session.on_ring_breach
def handle_breach(event):
    # Example: log and demote the offending agent

    print(f"Breach detected! Agent {event.agent_id} attempted {event.disallowed_action}")
    session.demote_agent(event.agent_id, new_ring=3)  # Force to deepest sandbox

```

Breach events are immutable records in the event stream, enabling SLO monitoring and forensic analysis. The `demote_agent()` method immediately restricts the agent to Ring 3 capabilities without terminating the session.

## Summary

- **ExecutionRings** provide four graduated privilege tiers (Ring 0–3) that map agent trust scores to sandbox constraints.
- The **`Agent-Hypervisor`** automatically assigns rings during session creation based on the **`eff_score`** callback evaluation in [`agent-hypervisor/session.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-hypervisor/session.py).
- **Policy bundles** define per-ring tool whitelists, resource limits, and timeouts enforced by the `ToolExecutor`.
- **Temporary elevation** requires signed JWTs with TTL validation through the `ElevationRequest` API and `Ring-Breach Detector`.
- **Breach detection** automatically demotes agents violating ring constraints, emitting audit events for `RingBreach` and `ToolExecuted` activities.

## Frequently Asked Questions

### How does AGT determine which ExecutionRing to assign to an agent?

The hypervisor evaluates the **`eff_score`** (effective trust score) returned by the `trust_score_cb` function provided during `Session` initialization. As implemented in [`agent-hypervisor/session.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-hypervisor/session.py), this dynamic score incorporates identity verification, historical behavior, and policy rules to select the appropriate tier from Ring 0 (highest privilege) to Ring 3 (strict sandbox).

### Can an agent permanently elevate its ExecutionRing privilege level?

No. Agents must maintain clean audit histories to remain in higher rings, and the system implements graduated privilege rather than permanent elevation. While agents can request temporary ring-bumps via `ElevationRequest` in [`agent-hypervisor/elevation.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-hypervisor/elevation.py), these require signed JWTs with short TTLs and validation against the Ring-Breach Detector. Permanent elevation requires re-authentication with a higher trust score.

### What happens when an agent violates its ExecutionRing constraints?

The **Ring-Breach Detector** in [`agent-hypervisor/ring_breach.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-hypervisor/ring_breach.py) aborts the disallowed tool call, emits a `RingBreach` event to the audit stream, and may invoke `demote_agent()` to restrict the agent to Ring 3. The hypervisor enforces these boundaries at the system-call level, preventing unauthorized resource access before damage occurs.

### Where are ExecutionRing policies defined in the codebase?

Ring-specific constraints are declared in policy bundles referenced by the **Policy Engine** at [`agent-governance-python/agentmesh-integrations/pydantic-ai-governance/src/pydantic_ai_governance/policy.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agentmesh-integrations/pydantic-ai-governance/src/pydantic_ai_governance/policy.py). The formal specification resides in [`docs/specs/AGENT-HYPERVISOR-EXECUTION-CONTROL-1.0.md`](https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/specs/AGENT-HYPERVISOR-EXECUTION-CONTROL-1.0.md), which defines the privilege matrix, ring-bump semantics, and breach detection protocols for the microsoft/agent-governance-toolkit repository.