🎯 What You'll Build in 5 Minutes

from agent_os import KernelSpace, Policy

# 1. Define safety policies (not prompts - actual enforcement)
kernel = KernelSpace(policies=[
    Policy.no_destructive_sql(),      # Block DROP, DELETE without WHERE
    Policy.file_access("/workspace"), # Restrict file access
    Policy.rate_limit(100, "1m"),     # Max 100 calls/minute
])

# 2. Your agent code runs in user space
@kernel.register
async def data_analyst(query: str):
    result = await llm.generate(f"Analyze: {query}")
    return result

# 3. Kernel intercepts and validates EVERY action
result = await kernel.execute(data_analyst, "revenue by region")
# ✅ Safe queries execute
# ❌ "DROP TABLE users" → BLOCKED (not by prompt, by kernel)

Result: Defined policies are deterministically enforced by the kernel—not by hoping the LLM follows instructions.

What is Agent OS?

Agent OS applies operating system concepts to AI agent governance. Instead of relying on prompts to enforce safety ("please don't do dangerous things"), it provides application-level middleware that intercepts and validates agent actions before execution.

Note: This is application-level enforcement (Python middleware), not OS kernel-level isolation. Agents run in the same process. For true isolation, run agents in containers.

┌─────────────────────────────────────────────────────────┐
│              USER SPACE (Agent Code)                    │
│   Your agent code runs here. The kernel intercepts      │
│   actions before they execute.                          │
├─────────────────────────────────────────────────────────┤
│              KERNEL SPACE                               │
│   Policy Engine │ Flight Recorder │ Signal Dispatch     │
│   Actions are checked against policies before execution │
└─────────────────────────────────────────────────────────┘

The Idea

Prompt-based safety asks the LLM to follow rules. The LLM decides whether to comply.

Kernel-based safety intercepts actions before execution. The policy engine decides, not the LLM.

This is the same principle operating systems use: applications request resources, the kernel grants or denies access based on permissions.

Architecture

agent-os/
├── src/agent_os/             # Core Python package
│   ├── __init__.py           # Public API
│   ├── cli.py                # Command-line interface
│   └── integrations/         # Framework adapters
├── modules/                  # Kernel Modules (4-layer architecture)
│   ├── primitives/           # Layer 1: Base types and failures
│   ├── cmvk/                 # Layer 1: Cross-model verification
│   ├── emk/                  # Layer 1: Episodic memory kernel
│   ├── caas/                 # Layer 1: Context-as-a-Service
│   ├── amb/                  # Layer 2: Agent message bus
│   ├── iatp/                 # Layer 2: Inter-agent trust protocol
│   ├── atr/                  # Layer 2: Agent tool registry
│   ├── observability/        # Layer 2: Prometheus + OpenTelemetry
│   ├── control-plane/        # Layer 3: THE KERNEL (policies, signals)
│   ├── scak/                 # Layer 4: Self-correcting agent kernel
│   ├── mute-agent/           # Layer 4: Face/Hands architecture
│   └── mcp-kernel-server/    # Integration: MCP protocol support
├── extensions/               # IDE & AI Assistant Extensions
│   ├── mcp-server/           # ⭐ MCP Server (Copilot, Claude, Cursor)
│   ├── vscode/               # VS Code extension
│   ├── copilot/              # GitHub Copilot (DEPRECATED - use mcp-server)
│   ├── jetbrains/            # IntelliJ/PyCharm plugin
│   ├── cursor/               # Cursor IDE extension
│   ├── chrome/               # Chrome extension
│   └── github-cli/           # gh CLI extension
├── examples/                 # Working examples
│   ├── quickstart/           # Start here: my_first_agent.py
│   ├── demo-app/             # Full demo application
│   ├── hello-world/          # Minimal example
│   └── [domain examples]/    # Real-world use cases
├── docs/                     # Documentation
├── tests/                    # Test suite (organized by layer)
├── notebooks/                # Jupyter tutorials
└── templates/                # Policy templates

Core Modules

IDE & CLI Extensions

Install

pip install agent-os

Or with optional components:

pip install agent-os[cmvk]           # + cross-model verification
pip install agent-os[iatp]           # + inter-agent trust
pip install agent-os[observability]  # + Prometheus/OpenTelemetry
pip install agent-os[full]           # Everything

One-Command Quickstart

macOS/Linux:

curl -sSL https://raw.githubusercontent.com/imran-siddique/agent-os/main/scripts/quickstart.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/imran-siddique/agent-os/main/scripts/quickstart.ps1 | iex

Quick Example

from agent_os import KernelSpace

# Create kernel with policy
kernel = KernelSpace(policy="strict")

@kernel.register
async def my_agent(task: str):
    # Your LLM code here
    return llm.generate(task)

# Actions are checked against policies
result = await kernel.execute(my_agent, "analyze this data")

POSIX-Inspired Primitives

Agent OS borrows concepts from POSIX operating systems:

Signals

from agent_os import SignalDispatcher, AgentSignal

dispatcher.signal(agent_id, AgentSignal.SIGSTOP)  # Pause
dispatcher.signal(agent_id, AgentSignal.SIGCONT)  # Resume
dispatcher.signal(agent_id, AgentSignal.SIGKILL)  # Terminate

VFS (Virtual File System)

from agent_os import AgentVFS

vfs = AgentVFS(agent_id="agent-001")
vfs.write("/mem/working/task.txt", "Current task")
vfs.read("/policy/rules.yaml")  # Read-only from user space

Framework Integrations

Wrap existing frameworks with Agent OS governance:

# LangChain
from agent_os.integrations import LangChainKernel
governed = LangChainKernel().wrap(my_chain)

# OpenAI Assistants
from agent_os.integrations import OpenAIKernel
governed = OpenAIKernel().wrap_assistant(assistant, client)

# Semantic Kernel
from agent_os.integrations import SemanticKernelWrapper
governed = SemanticKernelWrapper().wrap(sk_kernel)

# CrewAI
from agent_os.integrations import CrewAIKernel
governed = CrewAIKernel().wrap(my_crew)

See integrations documentation for full details.

How It Differs from Other Tools

Agent Frameworks (LangChain, CrewAI): Build agents. Agent OS governs them. Use together.

Safety Tools (NeMo Guardrails, LlamaGuard): Input/output filtering. Agent OS intercepts actions mid-execution.

You can use them together:

from langchain.agents import AgentExecutor
from agent_os import KernelSpace

kernel = KernelSpace(policy="strict")

@kernel.govern
async def my_langchain_agent(task: str):
    return agent_executor.invoke({"input": task})

Examples

The examples/ directory contains working demos:

Getting Started

Production Demos (with Observability)

Each production demo includes:

• Grafana dashboard on port 300X
• Prometheus metrics on port 909X
• Jaeger tracing on port 1668X

# Run carbon auditor with full observability
cd examples/carbon-auditor
cp .env.example .env  # Optional: add API keys
docker-compose up

# Open dashboards
open http://localhost:3000  # Grafana (admin/admin)
open http://localhost:16686 # Jaeger traces

Safe Tool Plugins

Agent OS includes pre-built safe tools for agents:

from atr.tools.safe import create_safe_toolkit

toolkit = create_safe_toolkit("standard")

# Available tools
http = toolkit["http"]        # Rate-limited HTTP with domain whitelisting
files = toolkit["files"]      # Sandboxed file reader
calc = toolkit["calculator"]  # Safe math (no eval)
json = toolkit["json"]        # Safe JSON/YAML parsing
dt = toolkit["datetime"]      # Timezone-aware datetime
text = toolkit["text"]        # Text processing

# Use a tool
result = await http.get("https://api.github.com/users/octocat")

See Creating Custom Tools for more.

Message Bus Adapters

Connect agents using various message brokers:

from amb_core.adapters import RedisBroker, KafkaBroker, NATSBroker

# Redis (low latency)
broker = RedisBroker(url="redis://localhost:6379")

# Kafka (high throughput)
broker = KafkaBroker(bootstrap_servers="localhost:9092")

# NATS (cloud-native)
broker = NATSBroker(servers=["nats://localhost:4222"])

# Also: AzureServiceBusBroker, AWSSQSBroker

See Message Bus Adapters Guide for details.

CLI Tool

Agent OS includes a CLI for terminal workflows:

# Check files for safety violations
agentos check src/app.py

# Check staged git files (pre-commit)
agentos check --staged

# Multi-model code review
agentos review src/app.py --cmvk

# Install git pre-commit hook
agentos install-hooks

# Initialize Agent OS in project
agentos init

MCP Integration (Claude Desktop, GitHub Copilot, Cursor)

Agent OS provides an MCP server that works with any MCP-compatible AI assistant:

# Quick install via npx
npx agentos-mcp-server

npm: agentos-mcp-server
MCP Registry: io.github.imran-siddique/agentos

Add to your config file:

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "agentos": {
      "command": "npx",
      "args": ["-y", "agentos-mcp-server"]
    }
  }
}

Features: 10 tools for agent creation, policy enforcement, compliance checking (SOC 2, GDPR, HIPAA), human-in-the-loop approvals, and audit logging.

See MCP server documentation for full details.

Documentation

Tutorials

• 5-Minute Quickstart - Get running fast
• 30-Minute Deep Dive - Comprehensive walkthrough
• Building Your First Governed Agent - Complete tutorial
• Using Message Bus Adapters - Connect agents
• Creating Custom Tools - Build safe tools
• Cheatsheet - Quick reference

Interactive Notebooks

Learn by doing with Jupyter notebooks:

Reference

• Quickstart Guide - 60 seconds to first agent
• Framework Integrations - LangChain, OpenAI, etc.
• Kernel Internals - How the kernel works
• Architecture Overview - System design
• CMVK Algorithm - Cross-model verification
• RFC-003: Agent Signals - POSIX-style signals
• RFC-004: Agent Primitives - Core primitives

Status

This is a research project exploring kernel concepts for AI agent governance. The code is functional but evolving.

Core (Production-Ready)

The minimal trust boundary that's small enough to audit:

• Policy Engine: Deterministic rule enforcement for defined patterns
• Flight Recorder: SQLite-based audit logging (see known limitations below)
• SDK Adapters: Intercept tool calls at SDK boundary (OpenAI, LangChain, CrewAI)

Extensions (Experimental)

Additional capabilities built on the core:

• Cross-model verification (CMVK), Inter-agent trust (IATP)
• Supervisor agents, Constraint graphs, Shadow mode
• IDE extensions (VS Code, JetBrains, Copilot)
• Observability (Prometheus, OpenTelemetry)
• Message bus adapters (Redis, Kafka, NATS)

Known Architectural Limitations

Be aware of these design constraints:

See GitHub Issues for the full roadmap.

• Some integrations are basic wrappers

Troubleshooting

Common Issues

ModuleNotFoundError: No module named 'agent_os'

# Install from source
git clone https://github.com/imran-siddique/agent-os.git
cd agent-os
pip install -e .

Permission errors on Windows

# Run PowerShell as Administrator, or use --user flag
pip install --user -e .

Docker not working

# Build with Dockerfile (no Docker Compose needed for simple tests)
docker build -t agent-os .
docker run -it agent-os python examples/hello-world/agent.py

Tests failing with API errors

# Most tests work without API keys - mock mode is default
pytest tests/ -v

# For real LLM tests, set environment variables
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

FAQ

Q: How is this different from LangChain/CrewAI? A: LangChain and CrewAI are frameworks for building agents. Agent OS is infrastructure for governing them. Use them together—wrap your LangChain agent with Agent OS for safety guarantees.

Q: What does "deterministic enforcement" mean? A: When a policy matches an action, that action is blocked—not by asking the LLM nicely. The middleware intercepts and stops it. However, this only works for patterns the policy engine knows about. Novel attacks that don't match defined rules will pass through.

Q: Do I need to rewrite my agents? A: No. Agent OS provides integration wrappers for LangChain, CrewAI, AutoGen, OpenAI Assistants, and Semantic Kernel. Wrap your existing code and add governance.

Q: Does it work with local models (Ollama, llama.cpp)? A: Yes. Agent OS is model-agnostic—it governs what agents do, not what LLM they use.

Q: How do I contribute? A: See CONTRIBUTING.md for guidelines. Good first issues are labeled in GitHub.

Contributing

git clone https://github.com/imran-siddique/agent-os.git
cd agent-os
pip install -e ".[dev]"
pytest

License

MIT - See LICENSE