📚 Tutorials

🚀 Tutorial: Your First Governed Agent

Prerequisites

• Python 3.9 or higher
• Basic understanding of async/await in Python
• 5 minutes of your time

Step 1: Install Agent OS

Install the Agent OS kernel from PyPI:

pip install agent-os-kernel

Step 2: Create Your First Agent

Create a new file called my_agent.py:

import asyncio
from agent_os import KernelSpace

# Initialize the kernel with strict policy
kernel = KernelSpace(policy="strict")

@kernel.register
async def analyze_data(query: str) -> str:
    """
    A simple agent that analyzes data.
    The kernel automatically enforces safety policies
    on every action this agent attempts.
    """
    # Simulate some analysis work
    result = f"Analysis complete for: {query}"
    return result

async def main():
    # Execute the governed agent
    result = await kernel.execute(analyze_data, "Q4 revenue trends")
    print(result)
    
    # View execution metrics
    metrics = kernel.metrics()
    print(f"\n--- Kernel Metrics ---")
    print(f"Total executions: {metrics.total_executions}")
    print(f"Policy violations blocked: {metrics.blocked_actions}")
    print(f"Average latency: {metrics.avg_latency_ms:.2f}ms")

if __name__ == "__main__":
    asyncio.run(main())

Step 3: Run Your Agent

Execute your governed agent:

python my_agent.py

You should see output like:

Analysis complete for: Q4 revenue trends

--- Kernel Metrics ---
Total executions: 1
Policy violations blocked: 0
Average latency: 2.34ms

Understanding What Happened

Let's break down the key concepts:

• KernelSpace — The core runtime that enforces policies on all registered agents
• @kernel.register — Decorator that wraps your function with kernel-level governance
• kernel.execute() — Runs the agent through the kernel, which intercepts and validates every action
• policy="strict" — Uses the built-in strict policy that blocks dangerous operations

Next Steps

• Learn to write custom policies →
• Explore the full API reference →
• Add hallucination detection with CMVK →