Agent Hypervisor

Why Agent Hypervisor¶

The problem: AI agents run with unlimited resources, no isolation, and no kill switch. A single rogue agent in a shared session can escalate privileges, corrupt state, or cascade failures across your entire system.

The approach: A hypervisor that enforces execution rings, resource limits, saga compensation, and runtime governance, giving you a kill switch and blast-radius containment.

How It Maps to What You Already Know¶

Quick start¶

pip install agent-governance-toolkit-core

from hypervisor import Hypervisor, SessionConfig, ConsistencyMode

hv = Hypervisor()

# Create an isolated session with governance
session = await hv.create_session(
    config=SessionConfig(enable_audit=True),
    creator_did="did:mesh:admin",
)

# Agent joins, ring assigned automatically by trust score
ring = await hv.join_session(
    session.sso.session_id,
    "did:mesh:agent-1",
    sigma_raw=0.85,
)
# RING_2_STANDARD (trusted agent)

# Activate and run a governed saga
await hv.activate_session(session.sso.session_id)
saga = session.saga.create_saga(session.sso.session_id)
step = session.saga.add_step(
    saga.saga_id, "draft_email", "did:mesh:agent-1",
    execute_api="/api/draft", undo_api="/api/undo-draft",
    timeout_seconds=30, max_retries=2,
)
result = await session.saga.execute_step(
    saga.saga_id, step.step_id, executor=draft_email,
)

# Terminate, returns tamper-evident audit hash
hash_root = await hv.terminate_session(session.sso.session_id)

Configuration¶

This section covers how to configure agents, sessions, sagas, safety controls, and rate limiting.

Agent Configuration¶

Agents join sessions and are assigned an Execution Ring based on their trust score (eff_score). You can control ring assignment, resource limits, and timeouts.

from hypervisor import Hypervisor, SessionConfig, ConsistencyMode, ExecutionRing

# Basic initialization. Optional adapters resolve trust scores,
# behavioral verification, and capability manifests.
hv = Hypervisor(
    nexus=None,        # External trust scoring backend
    policy_check=None, # Behavioral verification adapter
    iatp=None,         # Capability manifest parser
)

# Create a session with resource limits
session = await hv.create_session(
    config=SessionConfig(
        consistency_mode=ConsistencyMode.EVENTUAL,  # or STRONG
        max_participants=10,           # 1-1000
        max_duration_seconds=3600,     # 1-604,800 (7 days max)
        min_eff_score=0.60,            # Minimum trust score to join
        enable_audit=True,             # Hash-chained audit trail
    ),
    creator_did="did:mesh:admin",
)

# Agent joins, ring assigned by trust score
ring = await hv.join_session(
    session.sso.session_id,
    "did:mesh:agent-1",
    sigma_raw=0.85,   # Raw trust score [0.0-1.0]
)
# Ring assignment thresholds:
#   eff_score > 0.95 + consensus -> RING_1_PRIVILEGED
#   eff_score > 0.60             -> RING_2_STANDARD
#   otherwise                    -> RING_3_SANDBOX (default)

Temporary Ring Elevation (Sudo)¶

Agents can request temporary privilege escalation with a TTL. Elevation is granted only if the agent's trust score meets the target ring's threshold; Ring 1 additionally requires an attestation string, and Ring 0 is never granted through the standard API.

from hypervisor import ExecutionRing, RingElevationManager

elevation_mgr = RingElevationManager()

# Request temporary Ring 1 access (TTL default 300s, capped at 3600s)
elevation = elevation_mgr.request_elevation(
    agent_did="did:mesh:agent-1",
    session_id=session.sso.session_id,
    current_ring=ExecutionRing.RING_2_STANDARD,
    target_ring=ExecutionRing.RING_1_PRIVILEGED,
    ttl_seconds=300,               # Auto-expires after 5 minutes
    attestation="signed-by-sre",   # Required for Ring 1
    reason="deploy-approval",
    trust_score=0.96,              # Or supply a trust_provider to the manager
)

# Revoke early if needed
elevation_mgr.revoke_elevation(elevation.elevation_id)

# Expire elapsed elevations (call periodically)
elevation_mgr.tick()

Session Configuration¶

SessionConfig controls isolation, participant limits, and consistency:

from hypervisor import SessionConfig, ConsistencyMode

config = SessionConfig(
    consistency_mode=ConsistencyMode.STRONG,  # Requires consensus
    max_participants=5,
    max_duration_seconds=7200,    # 2-hour session
    min_eff_score=0.70,           # Higher trust threshold
    enable_audit=True,
)

session = await hv.create_session(config=config, creator_did="did:mesh:admin")
await hv.activate_session(session.sso.session_id)

# Session lifecycle: CREATED -> HANDSHAKING -> ACTIVE -> TERMINATING -> ARCHIVED

Saga Configuration¶

Define multi-step transactions with compensation programmatically:

saga = session.saga.create_saga(session.sso.session_id)
step = session.saga.add_step(
    saga.saga_id, "draft_email", "did:mesh:agent-1",
    execute_api="/api/draft",
    undo_api="/api/undo-draft",   # Compensation endpoint
    timeout_seconds=30,
    max_retries=2,
)
result = await session.saga.execute_step(
    saga.saga_id, step.step_id, executor=draft_email,
)
# On failure: automatic reverse-order compensation of committed steps

Kill Switch¶

The kill switch provides graceful agent termination with saga step handoff:

from hypervisor import KillSwitch
from hypervisor.security.kill_switch import KillReason

kill_switch = KillSwitch()

# Terminate a misbehaving agent
result = kill_switch.kill(
    agent_did="did:mesh:rogue-agent",
    session_id=session.sso.session_id,
    reason=KillReason.RING_BREACH,
)
# result.handoffs, list of in-flight saga steps handed to substitute agents
# result.compensation_triggered, True if active sagas were compensated

Kill reasons: - behavioral_drift, agent behavior diverges from expected patterns - rate_limit, agent exceeded rate limit thresholds - ring_breach, agent attempted unauthorized ring access - manual, operator-initiated termination - quarantine_timeout, quarantine period expired without resolution - session_timeout, session max duration exceeded

Rate Limiting¶

Per-ring token bucket rate limiting is applied automatically:

from hypervisor import AgentRateLimiter
from hypervisor.models import ExecutionRing

limiter = AgentRateLimiter()

# Default per-ring limits (rate tokens/sec, burst capacity):
#   Ring 0 (Root):       100.0 rate, 200.0 capacity
#   Ring 1 (Privileged):  50.0 rate, 100.0 capacity
#   Ring 2 (Standard):    20.0 rate,  40.0 capacity
#   Ring 3 (Sandbox):      5.0 rate,  10.0 capacity

# Custom rate limits per ring
custom_limits = {
    ExecutionRing.RING_0_ROOT: (200.0, 400.0),
    ExecutionRing.RING_1_PRIVILEGED: (100.0, 200.0),
    ExecutionRing.RING_2_STANDARD: (30.0, 60.0),
    ExecutionRing.RING_3_SANDBOX: (2.0, 5.0),
}
limiter = AgentRateLimiter(ring_limits=custom_limits)

Ring Breach Detection¶

The breach detector monitors agents for anomalous access patterns:

from hypervisor import RingBreachDetector, BreachSeverity

detector = RingBreachDetector()

# Breach events include:
#   severity: NONE | LOW | MEDIUM | HIGH | CRITICAL
#   anomaly_score: float, how far the behavior deviates
#   actual_rate vs expected_rate, call frequency anomaly
#   call_count_window, calls in the detection window

# Breach detection triggers automatic demotion or kill switch

Docker Compose¶

For production deployments with Redis-backed state:

# docker-compose.yml
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  hypervisor-api:
    build: .
    environment:
      - REDIS_URL=redis://redis:6379/0
      - HYPERVISOR_CONFIG=/app/config/hypervisor.yaml
    ports:
      - "8000:8000"
    volumes:
      - ./config:/app/config

Configuration Reference¶

Architecture¶

Execution Ring Hierarchy¶

graph TD
    R0["🔴 Ring 0, Root<br/>Hypervisor config and penalty<br/>Requires SRE Witness"]
    R1["🟠 Ring 1, Privileged<br/>Non-reversible actions<br/>eff_score > 0.95 + consensus"]
    R2["🟡 Ring 2, Standard<br/>Reversible actions<br/>eff_score > 0.60"]
    R3["🟢 Ring 3, Sandbox<br/>Read-only / research<br/>Default for unknown agents"]

    R0 -->|"supervises"| R1
    R1 -->|"supervises"| R2
    R2 -->|"supervises"| R3

Ring Promotion / Demotion Flow¶

stateDiagram-v2
    [*] --> Ring3 : Agent joins session
    Ring3 --> Ring2 : eff_score rises above 0.60
    Ring2 --> Ring1 : eff_score > 0.95 + consensus
    Ring1 --> Ring0 : SRE Witness approval

    Ring0 --> Ring1 : Trust drops / TTL expires
    Ring1 --> Ring2 : Trust drops below 0.95
    Ring2 --> Ring3 : Trust drops below 0.60
    Ring3 --> [*] : Terminated / expelled

    Ring2 --> Ring1 : Sudo elevation (TTL)
    Ring1 --> Ring2 : TTL expires

    note right of Ring3 : Ring breach detection\ntriggers immediate demotion

Saga Lifecycle¶

flowchart LR
    Create["Create Saga"] --> AddSteps["Add Steps"]
    AddSteps --> Execute["Execute Steps"]
    Execute --> Success{"All steps\nsucceed?"}
    Success -- Yes --> Complete["✅ Saga Complete"]
    Success -- No --> Compensate["Compensate\n(reverse order)"]
    Compensate --> CompOk{"Compensation\nsucceeds?"}
    CompOk -- Yes --> Rolled["↩️ Saga Rolled Back"]
    CompOk -- No --> Escalate["⚠️ Saga Failed\n(compensation error)"]

Key Features¶

Ring 0 (Root)       Hypervisor config and penalty, requires SRE Witness
Ring 1 (Privileged) Non-reversible actions, requires eff_score > 0.95 + consensus
Ring 2 (Standard)   Reversible actions, requires eff_score > 0.60
Ring 3 (Sandbox)    Read-only / research, default for unknown agents

Benchmarks¶

Microbenchmarks for ring computation, delta-audit capture, session lifecycle, and saga execution live in the benchmarks/ directory.

cd agent-governance-python/agent-hypervisor
python benchmarks/bench_hypervisor.py

Modules¶

Test Suite¶

cd agent-governance-python/agent-hypervisor

# Run all tests
pytest tests/ -v

# Run only integration tests
pytest tests/integration/ -v

# Run benchmarks
python benchmarks/bench_hypervisor.py

Cross-Module Integrations¶

The Hypervisor supports optional integration with external trust scoring, behavioral verification, and capability manifest systems via adapters in hypervisor.integrations. See the adapter modules for usage examples.

REST API¶

Run the FastAPI server and open the interactive Swagger docs:

uvicorn hypervisor.api.server:app
# Open http://localhost:8000/docs for Swagger UI

Implemented endpoint groups:

Visualization Dashboard¶

Interactive Streamlit dashboard:

cd agent-governance-python/agent-hypervisor/examples/dashboard
pip install -r requirements.txt
streamlit run app.py

Tabs: Session Overview | Execution Rings | Saga Orchestration | Event Stream

Ecosystem¶

Agent Hypervisor is part of the Agent Governance Ecosystem, specialized components that work together:

graph TB
    subgraph Ecosystem["Agent Governance Ecosystem"]
        OS["🧠 Agent OS<br/>Policy Enforcement Kernel"]
        Mesh["🔗 Agent Mesh<br/>Cryptographic Trust Network"]
        SRE["📊 Agent SRE<br/>Reliability Platform"]
        HV["⚡ Agent Hypervisor<br/>Runtime Governance"]

        OS <-->|"policies"| HV
        Mesh <-->|"trust scores"| HV
        SRE <-->|"SLOs + chaos"| HV
        OS <-->|"identity"| Mesh
    end

    style HV fill:#ff6b6b,stroke:#333,color:#fff

Roadmap¶

Frequently Asked Questions¶

Why use a hypervisor for AI agents? Just as OS hypervisors isolate virtual machines and enforce resource boundaries, an agent hypervisor isolates AI agent sessions and enforces governance boundaries. Without isolation, a misbehaving agent in a shared session can corrupt state, escalate privileges, or cascade failures across the entire system.

How do Execution Rings differ from traditional access control? Traditional access control is static and binary (allowed/denied). Execution Rings are dynamic and graduated. Agents earn ring privileges based on their trust score, can request temporary elevation with TTL (like sudo), and are automatically demoted when trust drops. Ring breach detection catches anomalous behavior before damage occurs.

What happens when a multi-agent saga fails? The Saga Orchestrator triggers reverse-order compensation for all committed steps. Each step defines an undo_api compensation endpoint, and steps that time out are cancelled and retried up to max_retries before compensation runs.

Contributing¶

We welcome contributions! Please see our Contributing Guide for details.

• Report a Bug
• Request a Feature
• Join Discussions
• Look for issues labeled good first issue to get started

License¶

MIT, see LICENSE.