Setting up ExecutionRing Privilege Levels for Sandboxed Agent Tool Execution

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.

Core Components and Architecture

According to the 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): Evaluates trust scores and applies per-ring constraints.
• Ring-Breach Detector (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, 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.

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.

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. The ElevationRequest requires a signed JWT with a strict TTL, validated by the Ring-Breach Detector to prevent privilege escalation attacks.

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.

@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.
• 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, 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, 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 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. The formal specification resides in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}