{ "markdown": "# Agent Guardrail\n\n\n\n**Action-level governance for AI agents — control what they DO, not what they SAY.**\n\n[![PyPI](https://img.shields.io/pypi/v/agent-guardrail)](https://pypi.org/project/agent-guardrail/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\n---\n\n## The Problem\n\nAI agents are getting tool access. They can run shell commands, make API calls, read files, spend money. But most \"guardrails\" only filter what agents *say* — not what they *do*.\n\nReal incidents:\n- **AutoGPT** autonomously spent $10K+ on API calls in a single session\n- **ChaosGPT** attempted to access military systems and recruit other AI agents\n- **Air Canada chatbot** invented a refund policy that cost the airline $800+\n\nYou need action-level control. Not output filtering.\n\n## What Agent Guardrail Does\n\n```\nAgent Framework --> Agent Guardrail --> {allow, deny, require_approval}\n --> Flight Recorder logs everything\n```\n\n- **Policy Engine** — allowlists, denylists, glob patterns for tools and targets\n- **Spend Caps** — daily and total USD limits per agent\n- **Kill Switch** — instantly deny all actions for a runaway agent\n- **Flight Recorder** — every action logged with full replay capability\n- **Approval Gates** — route risky actions to human review\n- **Risk Scoring** — automatic risk assessment per action type\n- **3 Templates** — restrictive, moderate, permissive (apply in one command)\n- **Pay-per-eval Billing** — free tier + BTC credit packs via Blockonomics\n\n**Zero dependencies.** Python stdlib only. SQLite for storage.\n\n## 30-Second Quickstart\n\n```bash\npip install agent-guardrail\n\n# Register an agent\nagent-guardrail register \"my-research-agent\" --framework langchain\n\n# Apply the moderate policy template\nagent-guardrail apply-template moderate \n\n# Test it\nagent-guardrail eval bash --target /workspace/test.sh # -> allow\nagent-guardrail eval bash --target /etc/shadow # -> deny\nagent-guardrail eval sudo # -> deny\n```\n\n## Python API\n\n```python\nfrom agent_guardrail import GuardrailStore, PolicyEngine, DEFAULT_POLICIES\n\n# Initialize\nstore = GuardrailStore() # ~/.agent-guardrail/guardrail.db\nengine = PolicyEngine(store)\n\n# Register agent\nagent = store.register_agent(\"my-agent\", framework=\"langchain\")\n\n# Apply policy template\nstore.save_policy({\n \"name\": \"moderate\",\n \"agent_id\": agent[\"id\"],\n \"rules\": DEFAULT_POLICIES[\"moderate\"][\"rules\"],\n})\n\n# Evaluate actions\ndecision = engine.evaluate(agent[\"id\"], \"bash\", target=\"/workspace/run.sh\")\n# -> PolicyDecision(decision=\"allow\", risk_score=0.7)\n\ndecision = engine.evaluate(agent[\"id\"], \"bash\", target=\"/etc/shadow\")\n# -> PolicyDecision(decision=\"deny\", reason=\"Target '/etc/shadow' is denied...\")\n\n# Evaluate + record to flight recorder\ndecision = engine.evaluate_and_record(\n agent_id=agent[\"id\"],\n action_type=\"api_call\",\n tool_name=\"openai_chat\",\n cost_usd=0.05,\n session_id=\"session-123\",\n)\n```\n\n## Framework Integrations\n\n### LangChain Callback\n\n```python\nfrom agent_guardrail import GuardrailStore, PolicyEngine\n\nclass GuardrailCallback:\n \"\"\"Drop into any LangChain agent as a callback handler.\"\"\"\n def __init__(self, agent_id, db_path=None):\n self._engine = PolicyEngine(GuardrailStore(db_path=db_path))\n self.agent_id = agent_id\n\n def on_tool_start(self, serialized, input_str, **kwargs):\n decision = self._engine.evaluate_and_record(\n agent_id=self.agent_id,\n action_type=\"tool_call\",\n tool_name=serialized.get(\"name\"),\n target=input_str[:200],\n )\n if decision.decision == \"deny\":\n raise PermissionError(f\"Guardrail: {decision.reason}\")\n```\n\n### CrewAI Task Guardrail\n\n```python\nfrom agent_guardrail import GuardrailStore, PolicyEngine\n\ndef make_guardrail(agent_id, db_path=None):\n engine = PolicyEngine(GuardrailStore(db_path=db_path))\n\n def check(task_output):\n decision = engine.evaluate_and_record(\n agent_id=agent_id, action_type=\"task_output\",\n target=str(task_output)[:200],\n )\n if decision.decision == \"deny\":\n return (False, f\"Blocked: {decision.reason}\")\n return (True, task_output)\n return check\n\n# task = Task(description=\"...\", guardrail=make_guardrail(\"agent-id\"))\n```\n\n### Universal Decorator\n\n```python\nfrom agent_guardrail import GuardrailStore, PolicyEngine\nimport functools\n\ndef guardrail(agent_id, action_type=\"function_call\", db_path=None):\n engine = PolicyEngine(GuardrailStore(db_path=db_path))\n def decorator(func):\n @functools.wraps(func)\n def wrapper(*args, **kwargs):\n target = str(args[0])[:200] if args else None\n decision = engine.evaluate_and_record(\n agent_id=agent_id, action_type=action_type,\n tool_name=func.__name__, target=target,\n )\n if decision.decision == \"deny\":\n raise PermissionError(f\"Guardrail: {decision.reason}\")\n return func(*args, **kwargs)\n return wrapper\n return decorator\n\n@guardrail(\"my-agent\", action_type=\"bash\")\ndef run_command(cmd):\n ...\n```\n\n## Hosted API (For Agents)\n\nThe library is for humans. The API is for agents.\n\nAn orchestrator running 5 sub-agents doesn't `pip install` — it calls an endpoint.\n\n```bash\n# Start the proxy server\npip install agent-guardrail[proxy]\nguardrail-proxy --port 8300 --admin-key YOUR_ADMIN_KEY\n```\n\n```bash\n# Register an agent (admin)\ncurl -X POST http://localhost:8300/v1/agents \\\n -H \"X-Admin-Key: YOUR_ADMIN_KEY\" \\\n -d '{\"name\": \"research-agent\", \"framework\": \"crewai\"}'\n\n# Evaluate an action (agent)\ncurl -X POST http://localhost:8300/v1/evaluate \\\n -H \"X-API-Key: gw_agent_key_here\" \\\n -d '{\n \"agent_id\": \"...\",\n \"action_type\": \"bash\",\n \"tool_name\": \"shell\",\n \"target\": \"/etc/shadow\",\n \"cost_usd\": 0.0\n }'\n# -> {\"decision\": \"deny\", \"reason\": \"Target denied...\", \"risk_score\": 0.7}\n```\n\nFull API docs at `http://localhost:8300/docs` (Swagger UI).\n\n## Billing & Pricing\n\nFree tier included. Pay with Bitcoin when you need more.\n\n| Tier | Evaluations | Price | Per Eval |\n|------|-------------|-------|----------|\n| **Free** | 100/day per agent | $0 | $0 |\n| **Starter** | 1,000 | $10 | $0.010 |\n| **Growth** | 5,000 | $40 | $0.008 |\n| **Scale** | 25,000 | $150 | $0.006 |\n\nCredits are prepaid and never expire. Admin-authenticated requests bypass billing entirely.\n\n**How it works:**\n\n```bash\n# Check your balance\ncurl http://localhost:8300/v1/billing/balance \\\n -H \"X-API-Key: gw_your_agent_key\"\n\n# Buy credits (returns a BTC address + amount)\ncurl -X POST http://localhost:8300/v1/billing/checkout \\\n -H \"X-API-Key: gw_your_agent_key\" \\\n -d '{\"pack_id\": \"pack_1000\"}'\n# -> {\"btc_address\": \"bc1q...\", \"amount_btc\": 0.00015, \"amount_satoshi\": 15000, ...}\n\n# Pay the BTC address -> webhook confirms -> credits granted automatically\n```\n\nWhen free tier is exhausted and no credits remain, `/v1/evaluate` returns **402 Payment Required** with a link to available packs.\n\n**Self-hosted billing:** Set `BLOCKONOMICS_API_KEY` and `BLOCKONOMICS_WEBHOOK_SECRET` environment variables. Without these, billing is disabled and all evaluations proceed without metering (backward compatible).\n\n## Policy Rules Reference\n\n```python\n{\n \"tool_allowlist\": [\"read_file\", \"write_file\"], # Only these tools allowed\n \"tool_denylist\": [\"sudo\", \"rm\", \"delete*\"], # These tools always denied\n \"target_allowlist\": [\"/workspace/*\"], # Only these targets allowed\n \"target_denylist\": [\"/etc/*\", \"*.env\", \"*.key\"], # These targets always denied\n \"network_allowlist\": [\"api.openai.com\"], # Allowed network targets\n \"network_denylist\": [\"*\"], # Denied network targets\n \"spend_cap_daily_usd\": 25.0, # Daily spend limit\n \"spend_cap_total_usd\": 500.0, # Lifetime spend limit\n \"require_approval\": [\"bash\", \"install\"], # Human approval required\n \"risk_threshold\": 0.8, # Auto-approval gate\n}\n```\n\nPatterns support glob matching (`*`, `?`, `[abc]`).\n\n## Decision Flow\n\n```\nKill switch? ──deny──> DENY\n |\nAgent enabled? ──no──> DENY\n |\nSpend cap? ──exceeded──> DENY\n |\nTool denylist? ──match──> DENY\n |\nTarget denylist? ──match──> DENY\n |\nApproval required? ──match──> REQUIRE_APPROVAL\n |\nRisk threshold? ──exceeded──> REQUIRE_APPROVAL\n |\nTool allowlist? ──not in list──> DENY\n |\nTarget allowlist? ──not in list──> DENY\n |\nDEFAULT ──> ALLOW\n```\n\n## Architecture\n\n```\n+-------------------+ +------------------+ +-----------------+\n| Agent Framework |---->| Billing Check |---->| Policy Engine |\n| (LangChain, | | (free tier / | | (evaluate) |\n| CrewAI, custom) | | credits) | +-----------------+\n+-------------------+ +------------------+ |\n | v\n | +------------------------+\n 402 if empty | Decision: |\n | allow / deny / |\n | require_approval |\n +------------------------+\n |\n v\n +-----------------+\n | Flight Recorder|\n | (SQLite) |\n +-----------------+\n\n+-------------------+ +------------------+\n| BTC Payment |---->| Blockonomics |\n| (checkout) | | (xpub-derived |\n+-------------------+ | addresses) |\n +------------------+\n |\n webhook (status=2)\n |\n v\n +------------------+\n | Credit Grant |\n | (billing_ledger)|\n +------------------+\n```\n\n## Comparison\n\n| Feature | Agent Guardrail | Guardrails AI | NeMo Guardrails | DIY |\n|---------|:-:|:-:|:-:|:-:|\n| Action-level control | Yes | No (output only) | No (dialogue only) | Manual |\n| Spend caps | Yes | No | No | Manual |\n| Kill switch | Yes | No | No | Manual |\n| Flight recorder | Yes | No | No | Manual |\n| Pay-per-eval billing | Yes (BTC) | No | No | Manual |\n| Zero dependencies | Yes | No (many) | No (many) | Varies |\n| Framework agnostic | Yes | LangChain-focused | LangChain-focused | Yes |\n| Hosted API | Yes | Cloud only | No | Manual |\n\n## CLI Reference\n\n```\nagent-guardrail agents # List registered agents\nagent-guardrail register \"name\" # Register a new agent\nagent-guardrail kill # Emergency kill switch\nagent-guardrail unkill # Revoke kill switch\nagent-guardrail policies # List policies\nagent-guardrail apply-template