agentguardrail 1.2.1
AgentGuardrail — guardrails and policy enforcement for AI agents. Runtime action blocking, audit logs, MCP gateway, NLP intent detection. Works with OpenAI, Anthropic, LangChain, CrewAI, Google ADK, browser-use, and any agent framework.
Requires Python: >=3.11
Keywords: agent-firewall, agent-guardrail, agent-guardrails, agent-observability, agent-runtime, agent-safety, agent-security, agentguardrail, agentic-ai, ai-agent-guardrails, ai-agents, ai-automation, ai-guardrails, ai-safety, ai-security, anthropic, audit-trail, browser-automation, browser-use, compliance, crewai, execution-control, google-adk, guardrails, langchain, llm-agents, llm-guardrails, mcp, mcp-gateway, mcp-server, model-context-protocol, openai, openclaw, policy-engine, runtime-enforcement, tool-security

# AgentGuardrail — Guardrails & Policy Enforcement for AI Agents

**AgentGuardrail is an open-source Python framework for enforcing guardrails, policies, and execution safety on AI agents.** It helps developers control what AI agents can do — blocking risky actions, auditing executions, securing agent workflows, and governing MCP tool calls.

[![PyPI](https://img.shields.io/pypi/v/agentguardrail?color=blue&label=PyPI)](https://pypi.org/project/agentguardrail/)
[![Downloads](https://img.shields.io/pypi/dm/agentguardrail?color=green&label=Downloads)](https://pypi.org/project/agentguardrail/)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/agentguardrail)](https://pypi.org/project/agentguardrail/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green)](https://github.com/Nitin-100/agentgate/blob/master/LICENSE)

---

## What is AgentGuardrail?

AgentGuardrail (also known as **AgentGate**) is a **runtime guardrails framework** for AI agents. It intercepts every agent action — browser clicks, form submissions, MCP tool calls — and enforces security policies **before** the action executes.

> **Not just LLM output validation.** AgentGuardrail enforces guardrails on **agent actions and tool calls**, not just text outputs. It's a runtime execution firewall, not a prompt filter.
>
> **Note:** AgentGuardrail is **not** the same as `guardrails-ai`. That project validates LLM text outputs. AgentGuardrail enforces guardrails on agent **actions** — clicks, tool calls, browser interactions.

### Why do AI agents need guardrails?

AI agents (OpenAI, Claude, LangChain, CrewAI, Google ADK, browser-use, etc.) can now operate websites, call APIs, make payments, and perform real-world actions. Without guardrails:

- ❌ An agent can click "Pay $5,000" — no policy controls it
- ❌ An agent can call `delete_database` via MCP — no tool-level security
- ❌ No tamper-proof audit trail of what the agent actually did
- ❌ No way to scope or time-limit agent permissions

**AgentGuardrail fixes all of this.**

## Why AgentGuardrail?

| What happens today | With AgentGuardrail |
|---|---|
| Agent clicks "Pay $5,000" | 🛡️ **Blocked** — payment actions are policy-controlled |
| Agent calls MCP `delete_table` | 🛡️ **Blocked** — MCP tool calls are policy-checked |
| Agent exports customer PII | 🛡️ **Requires approval** — sensitive actions need human sign-off |
| "What did the agent do?" — nobody knows | 🛡️ **Tamper-proof evidence vault** — every action recorded with hash chain |
| Agent has unlimited access | 🛡️ **Capability tokens** — scoped, time-bound, revocable permissions |
| Multiple agents with no coordination | 🛡️ **Multi-agent session manager** — role-based governance, cross-agent rate limits |
| No sidecar health monitoring | 🛡️ **Heartbeat client** — auto-reconnect, policy change detection |

## Works With Every AI Agent Framework

AgentGuardrail is **framework-agnostic**. Drop it into any agent stack in under 5 minutes:

| Framework | Integration | Status |
|---|---|---|
| **OpenAI** (GPT-4, CUA, Assistants) | Python SDK / REST API | ✅ Tested |
| **Anthropic** (Claude, Computer Use) | Python SDK / REST API | ✅ Tested |
| **Google ADK** (Agent Development Kit) | Python SDK / REST API | ✅ Tested |
| **LangChain / LangGraph** | Python SDK / REST API | ✅ Tested |
| **CrewAI** | Python SDK / REST API | ✅ Tested |
| **browser-use** | Python SDK | ✅ Tested |
| **OpenClaw** | Built-in skill + sidecar | ✅ First-class |
| **MCP Servers** (Stripe, GitHub, etc.) | MCP proxy gateway | ✅ Native |
| **Any HTTP client** | REST API on port 18790 | ✅ Universal |

### 🦞 First-Class OpenClaw Support

AgentGuardrail ships with a ready-to-use **OpenClaw skill** — just drop the `skills/agentgate/` folder into your OpenClaw workspace and every browser action is automatically policy-checked.

```bash
# Start AgentGate sidecar
agentgate sidecar --policy finance-safe

# OpenClaw automatically checks every action through AgentGate
```

## Install

```bash
pip install agentguardrail
```

**With NLP-powered intent detection** (~67 MB model, CPU-only, zero API keys):

```bash
pip install agentguardrail[nlp]
```

**With MCP (Model Context Protocol) support:**

```bash
pip install agentguardrail[mcp]
```

**Everything:**

```bash
pip install agentguardrail[all]
```

## Quick Start — Secure Your Agent in 3 Lines

```python
from agentgate.sidecar.client import AgentGateClient

gate = AgentGateClient()  # Connects to sidecar on localhost:18790

# Before your agent clicks anything:
result = gate.check_click("https://bank.com", "Pay Now", "button.pay")
# result.decision → "block" (payment actions blocked by policy)
```

Or use the **full browser wrapper** for automatic enforcement:

```python
from agentgate import SecureBrowser

async with SecureBrowser(policy="finance-safe") as browser:
    page = await browser.new_page()
    await page.goto("https://example.com")    # ✅ Allowed
    await page.click("button#pay")            # 🚫 Blocked automatically
```

## How AgentGuardrail Works

```
Your AI Agent (OpenAI / Claude / LangChain / CrewAI / any)
    ↓  every action & tool call passes through AgentGuardrail
┌────────────────────────────────────────────────┐
│  🛡️ AgentGuardrail Firewall                    │
│                                                │
│  1. Action Interceptor (browser + MCP tools)   │
│  2. Policy Engine (3-layer NLP matching)       │
│  3. Evidence Vault (SHA-256 hash-chained)      │
│  4. Capability Tokens (scoped, time-bound)     │
└────────────────────────────────────────────────┘
    ↓  only ALLOWED actions reach the target
Browser / MCP Servers / APIs
```

## Policies — YAML-Based Agent Guardrails

```yaml
name: finance-safe
description: Allow reading, block all payments

rules:
  - action: click
    block_elements:
      - text_contains: ["Pay", "Transfer", "Delete"]
        risk: high
    require_approval:
      - text_contains: ["Submit", "Confirm"]
        risk: medium

  - action: navigate
    block:
      - pattern: "*/admin/*"
      - pattern: "*/payments/*"
```

**Browser policy presets:** `finance-safe`, `readonly`, `permissive`

**MCP policy presets:** `mcp-default`, `mcp-readonly`, `mcp-finance-safe`, `mcp-devops-safe`

## Key Features

### 🧠 NLP Intent Detection *(v1.1+)*
- **3-layer matching pipeline:** exact keywords → phonetic codes → semantic NLP
- **20 intent categories** — payment, delete, admin, posting, messaging, sharing, and more
- Understands novel phrases: "Process Transaction" → payment intent → HIGH risk
- Catches typos: "Chekout" → matches "checkout" via phonetic codes
- Runs on **CPU** (~67 MB ONNX model), **zero API keys**, ~2ms per classification
- Add custom intents at runtime

### 🔒 Policy Engine
- **15 action types** intercepted (click, type, navigate, download, JS eval, etc.)
- **5 risk levels** with automatic classification
- YAML-based rules — version-controlled, human-readable
- Most-restrictive-wins across multiple policies

### 📋 Evidence Vault
- **SHA-256 hash-chained** evidence records — tamper-evident by design
- Every action recorded: what, where, when, who, decision, fingerprint
- Session-based tracking with export and replay
- Holds up to compliance and audit requirements

### 🎟️ Capability Tokens
- Scoped permissions: limit by domain, URL pattern, action type, element text
- Time-bound: tokens auto-expire (minutes, hours, or days)
- Rate-limited: max actions per minute, max total actions
- HMAC-signed and revocable

### 🔌 Sidecar REST API
- FastAPI service on port 18790 — works with any language or framework
- 16 endpoints: evaluate, batch check, sessions, tokens, policies, health
- Python SDK included: `AgentGateClient` (sync) and `AsyncAgentGateClient`

### 🔌 MCP Gateway (Model Context Protocol)
- **MCP Server mode** — expose AgentGuardrail tools via MCP protocol
- **MCP Proxy Gateway** — intercept and guard tool calls to downstream MCP servers
- **Extensible Plugin System** — transform, validate, audit, and policy plugins
- **Built-in security plugins** — SQL injection guard, sensitive data guard, rate limiter
- **4 MCP policy presets** — mcp-default, mcp-readonly, mcp-finance-safe, mcp-devops-safe
- Same 3-layer NLP pipeline on tool names and arguments
- Works with Claude Desktop, Cursor, GPT, and any MCP-compatible client

### 🤖 Multi-Agent Session Management *(v1.2+)*
- **6 agent roles** — READER, WRITER, ADMIN, EXECUTOR, OBSERVER, CUSTOM
- **Orchestration lifecycle** — group multiple agents under one governed session
- **Cross-agent rate limiting** — per-agent + collective limits across all agents
- **Sequential execution** — coordination locks for one-at-a-time agent action
- **Unified evidence trail** — every agent gets its own evidence session, unified summary
- Pause, resume, and transfer control between agents

### 💓 OpenClaw Heartbeat *(v1.2+)*
- **Background health monitoring** — async heartbeat loop with configurable intervals
- **Policy change detection** — alerts when policies change mid-session
- **Auto-reconnect** — automatic recovery on connection loss with retry limits
- **Latency tracking** — avg/min/max response times and uptime percentage
- **6 event callbacks** — on_healthy, on_degraded, on_unhealthy, on_disconnect, on_policy_change, on_reconnect

## AgentGuardrail vs. Other Tools

| Other Tools | AgentGuardrail |
|---|---|
| Prompt/text filtering (guardrails-ai) | **Agent action & tool enforcement** |
| LLM output validation | **Runtime execution guardrails** |
| API call monitoring only | **Browser + MCP tool control** |
| Keyword-only matching | **NLP semantic understanding** |
| Logs only | **Tamper-evident evidence chain** |
| No MCP governance | **MCP proxy gateway** |
| No multi-agent coordination | **Multi-agent sessions with role-based governance** |
| No health monitoring | **Heartbeat client with auto-reconnect** |
| Detection-only | **Prevention — blocks before execution** |

## CLI Reference

```bash
agentgate init                          # Scaffold a new project
agentgate sidecar --policy finance-safe   # Start the sidecar API
agentgate policies list                 # View loaded policies
agentgate sessions list                 # View evidence sessions
agentgate sessions verify <id>          # Verify evidence chain integrity
agentgate dashboard                     # Launch web dashboard
agentgate license status                # Check license tier
agentgate mcp serve                     # Start as MCP server
agentgate mcp proxy --config file.yaml  # Start MCP proxy gateway
agentgate mcp check <server> <tool>     # Check if MCP tool call is allowed
agentgate mcp policies                  # List MCP policy presets
```

## Licensing

| Tier | Price | What You Get |
|---|---|---|
| **Community** | Free forever | Core engine, 2 policies, basic sidecar |
| **Trial** | Free 24 hours | All features unlocked — starts automatically |
| **Pro** | $49/month | Unlimited policies, evidence vault, tokens, webhooks |
| **Enterprise** | $199/month | Everything + SSO, priority support, 365-day audit logs |

```bash
# First install → 24-hour trial starts automatically (all features)
pip install agentguardrail

# After trial → free Community tier continues working
# Upgrade anytime:
agentgate license activate YOUR-LICENSE-KEY
```

## Security

AgentGuardrail's licensing includes **enterprise-grade anti-tamper protection**:
- 🔐 Clock rollback detection (NTP + monotonic tracking)
- 🔐 File integrity seal (HMAC-SHA256)
- 🔐 Machine-bound fingerprint
- 🔐 Deletion-resistant breadcrumb storage
- 🔐 PBKDF2-derived signing keys

## Links

- **GitHub:** [github.com/Nitin-100/agentgate](https://github.com/Nitin-100/agentgate)
- **PyPI:** [pypi.org/project/agentguardrail](https://pypi.org/project/agentguardrail/)
- **Docs:** [User Guide](https://github.com/Nitin-100/agentgate/tree/master/docs)
- **Issues:** [Report a bug](https://github.com/Nitin-100/agentgate/issues)
- **Changelog:** [CHANGELOG.md](https://github.com/Nitin-100/agentgate/blob/master/CHANGELOG.md)

## License

Apache 2.0 — free to use, modify, and distribute. See [LICENSE](https://github.com/Nitin-100/agentgate/blob/master/LICENSE).

---

**🛡️ AgentGuardrail — Guardrails for AI agents. Control what they do. Prove what they did.**

*Keywords: agentguardrail, agent guardrail, ai agent guardrails, ai guardrails, agent security, agent safety, agent policy enforcement, agent runtime safety, mcp gateway, llm guardrails, ai agent security, runtime enforcement, tool security, agentic ai guardrails, multi-agent session management, agent heartbeat, mcp plugin system*