Agent Guardrail MCP Server

Agent Guardrail

面向 AI Agent 的操作级治理——控制它们做什么，而不是说什么。

---

问题

AI Agent 正在获得工具访问权限。它们可以运行 shell 命令、调用 API、读取文件、花费资金。但大多数“护栏”只会过滤 Agent 说什么，而不会过滤它们做什么。

真实事件：

• AutoGPT 在单次会话中自主花费了超过 $10K 的 API 调用费用
• ChaosGPT 曾试图访问军事系统并招募其他 AI Agent
• Air Canada chatbot 虚构了一项退款政策，导致航空公司损失超过 $800

你需要的是操作级控制，而不是输出过滤。

Agent Guardrail 的功能

Agent Framework --> Agent Guardrail --> {allow, deny, require_approval}
                                    --> Flight Recorder logs everything

• 策略引擎 — 为工具和目标设置允许列表、拒绝列表及 glob 模式
• 支出上限 — 为每个 Agent 设置每日和总计美元限额
• 紧急停止开关 — 立即拒绝失控 Agent 的所有操作
• 飞行记录器 — 记录每项操作，并支持完整回放
• 审批关卡 — 将高风险操作提交人工审核
• 风险评分 — 根据操作类型自动评估风险
• 3 种模板 — 限制型、中等型、宽松型（一条命令即可应用）
• 按评估付费 — 免费额度 + 通过 Blockonomics 购买 BTC 额度包

零依赖。 仅使用 Python 标准库。使用 SQLite 存储。

30 秒快速入门

pip install agent-guardrail

# Register an agent
agent-guardrail register "my-research-agent" --framework langchain

# Apply the moderate policy template
agent-guardrail apply-template moderate <agent-id>

# Test it
agent-guardrail eval <agent-id> bash --target /workspace/test.sh     # -> allow
agent-guardrail eval <agent-id> bash --target /etc/shadow             # -> deny
agent-guardrail eval <agent-id> sudo                                  # -> deny

Python API

from agent_guardrail import GuardrailStore, PolicyEngine, DEFAULT_POLICIES

# Initialize
store = GuardrailStore()  # ~/.agent-guardrail/guardrail.db
engine = PolicyEngine(store)

# Register agent
agent = store.register_agent("my-agent", framework="langchain")

# Apply policy template
store.save_policy({
    "name": "moderate",
    "agent_id": agent["id"],
    "rules": DEFAULT_POLICIES["moderate"]["rules"],
})

# Evaluate actions
decision = engine.evaluate(agent["id"], "bash", target="/workspace/run.sh")
# -> PolicyDecision(decision="allow", risk_score=0.7)

decision = engine.evaluate(agent["id"], "bash", target="/etc/shadow")
# -> PolicyDecision(decision="deny", reason="Target '/etc/shadow' is denied...")

# Evaluate + record to flight recorder
decision = engine.evaluate_and_record(
    agent_id=agent["id"],
    action_type="api_call",
    tool_name="openai_chat",
    cost_usd=0.05,
    session_id="session-123",
)

框架集成

LangChain 回调

from agent_guardrail import GuardrailStore, PolicyEngine

class GuardrailCallback:
    """Drop into any LangChain agent as a callback handler."""
    def __init__(self, agent_id, db_path=None):
        self._engine = PolicyEngine(GuardrailStore(db_path=db_path))
        self.agent_id = agent_id

    def on_tool_start(self, serialized, input_str, **kwargs):
        decision = self._engine.evaluate_and_record(
            agent_id=self.agent_id,
            action_type="tool_call",
            tool_name=serialized.get("name"),
            target=input_str[:200],
        )
        if decision.decision == "deny":
            raise PermissionError(f"Guardrail: {decision.reason}")

CrewAI 任务护栏

from agent_guardrail import GuardrailStore, PolicyEngine

def make_guardrail(agent_id, db_path=None):
    engine = PolicyEngine(GuardrailStore(db_path=db_path))

    def check(task_output):
        decision = engine.evaluate_and_record(
            agent_id=agent_id, action_type="task_output",
            target=str(task_output)[:200],
        )
        if decision.decision == "deny":
            return (False, f"Blocked: {decision.reason}")
        return (True, task_output)
    return check

# task = Task(description="...", guardrail=make_guardrail("agent-id"))

通用装饰器

from agent_guardrail import GuardrailStore, PolicyEngine
import functools

def guardrail(agent_id, action_type="function_call", db_path=None):
    engine = PolicyEngine(GuardrailStore(db_path=db_path))
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            target = str(args[0])[:200] if args else None
            decision = engine.evaluate_and_record(
                agent_id=agent_id, action_type=action_type,
                tool_name=func.__name__, target=target,
            )
            if decision.decision == "deny":
                raise PermissionError(f"Guardrail: {decision.reason}")
            return func(*args, **kwargs)
        return wrapper
    return decorator

@guardrail("my-agent", action_type="bash")
def run_command(cmd):
    ...

托管 API（供 Agent 使用）

此库面向人类，API 面向 Agent。

运行 5 个子 Agent 的编排器不会运行 pip install，而是调用端点。

# Start the proxy server
pip install agent-guardrail[proxy]
guardrail-proxy --port 8300 --admin-key YOUR_ADMIN_KEY

# Register an agent (admin)
curl -X POST http://localhost:8300/v1/agents \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "research-agent", "framework": "crewai"}'

# Evaluate an action (agent)
curl -X POST http://localhost:8300/v1/evaluate \
  -H "X-API-Key: gw_agent_key_here" \
  -d '{
    "agent_id": "...",
    "action_type": "bash",
    "tool_name": "shell",
    "target": "/etc/shadow",
    "cost_usd": 0.0
  }'
# -> {"decision": "deny", "reason": "Target denied...", "risk_score": 0.7}

完整 API 文档见 http://localhost:8300/docs（Swagger UI）。

账单与定价

包含免费额度。如需更多额度，可使用 Bitcoin 付款。

套餐	评估次数	价格	单次评估价格
免费	每个 Agent 每天 100 次	$0	$0
入门	1,000 次	$10	$0.010
成长	5,000 次	$40	$0.008
规模	25,000 次	$150	$0.006

额度需预先购买，且永不过期。经过管理员身份验证的请求完全免除计费。

工作方式：

# Check your balance
curl http://localhost:8300/v1/billing/balance \
  -H "X-API-Key: gw_your_agent_key"

# Buy credits (returns a BTC address + amount)
curl -X POST http://localhost:8300/v1/billing/checkout \
  -H "X-API-Key: gw_your_agent_key" \
  -d '{"pack_id": "pack_1000"}'
# -> {"btc_address": "bc1q...", "amount_btc": 0.00015, "amount_satoshi": 15000, ...}

# Pay the BTC address -> webhook confirms -> credits granted automatically

免费额度用尽且没有剩余额度时，/v1/evaluate 会返回 402 Payment Required，并附上可用额度包的链接。

可自托管的计费功能： 设置 BLOCKONOMICS_API_KEY 和 BLOCKONOMICS_WEBHOOK_SECRET 环境变量。未设置这些变量时，计费功能将禁用，所有评估均不计量（向后兼容）。

策略规则参考

{
    "tool_allowlist": ["read_file", "write_file"],    # Only these tools allowed
    "tool_denylist": ["sudo", "rm", "delete*"],       # These tools always denied
    "target_allowlist": ["/workspace/*"],              # Only these targets allowed
    "target_denylist": ["/etc/*", "*.env", "*.key"],   # These targets always denied
    "network_allowlist": ["api.openai.com"],           # Allowed network targets
    "network_denylist": ["*"],                         # Denied network targets
    "spend_cap_daily_usd": 25.0,                      # Daily spend limit
    "spend_cap_total_usd": 500.0,                     # Lifetime spend limit
    "require_approval": ["bash", "install"],           # Human approval required
    "risk_threshold": 0.8,                             # Auto-approval gate
}

模式支持 glob 匹配（*、?、[abc]）。

决策流程

Kill switch? ──deny──> DENY
      |
Agent enabled? ──no──> DENY
      |
Spend cap? ──exceeded──> DENY
      |
Tool denylist? ──match──> DENY
      |
Target denylist? ──match──> DENY
      |
Approval required? ──match──> REQUIRE_APPROVAL
      |
Risk threshold? ──exceeded──> REQUIRE_APPROVAL
      |
Tool allowlist? ──not in list──> DENY
      |
Target allowlist? ──not in list──> DENY
      |
DEFAULT ──> ALLOW

架构

+-------------------+     +------------------+     +-----------------+
|  Agent Framework  |---->|  Billing Check   |---->|  Policy Engine  |
|  (LangChain,     |     |  (free tier /    |     |  (evaluate)     |
|   CrewAI, custom) |     |   credits)       |     +-----------------+
+-------------------+     +------------------+            |
                                 |                        v
                                 |           +------------------------+
                          402 if empty       |  Decision:             |
                                             |  allow / deny /        |
                                             |  require_approval      |
                                             +------------------------+
                                                         |
                                                         v
                                             +-----------------+
                                             |  Flight Recorder|
                                             |  (SQLite)       |
                                             +-----------------+

+-------------------+     +------------------+
|  BTC Payment      |---->|  Blockonomics    |
|  (checkout)       |     |  (xpub-derived   |
+-------------------+     |   addresses)     |
                          +------------------+
                                 |
                          webhook (status=2)
                                 |
                                 v
                          +------------------+
                          |  Credit Grant    |
                          |  (billing_ledger)|
                          +------------------+

对比

功能	Agent Guardrail	Guardrails AI	NeMo Guardrails	DIY
操作级控制	是	否（仅输出）	否（仅对话）	手动
支出上限	是	否	否	手动
紧急停止开关	是	否	否	手动
飞行记录器	是	否	否	手动
按评估付费	是（BTC）	否	否	手动
零依赖	是	否（依赖众多）	否（依赖众多）	不定
框架无关	是	以 LangChain 为主	以 LangChain 为主	是
托管 API	是	仅云端	否	手动

CLI 参考

agent-guardrail agents                      # List registered agents
agent-guardrail register "name"             # Register a new agent
agent-guardrail kill <agent_id>             # Emergency kill switch
agent-guardrail unkill <agent_id>           # Revoke kill switch
agent-guardrail policies                    # List policies
agent-guardrail apply-template <template> <agent_id>
agent-guardrail actions [--agent X] [--decision deny]
agent-guardrail replay <session_id>         # Session replay
agent-guardrail approvals                   # Pending approvals
agent-guardrail approve <id>                # Approve action
agent-guardrail deny <id>                   # Deny action
agent-guardrail eval <agent_id> <type> [--target X] [--cost 0.5]
agent-guardrail stats                       # Statistics

配置

变量	默认值	用途
GUARDRAIL_DB	~/.agent-guardrail/guardrail.db	SQLite 数据库路径
GUARDRAIL_LOG_DIR	~/.agent-guardrail/logs	CLI 日志目录
GUARDRAIL_ADMIN_KEY	(none)	代理的 Admin API 密钥
BLOCKONOMICS_API_KEY	(none)	Blockonomics Store API 密钥（启用计费）
BLOCKONOMICS_WEBHOOK_SECRET	(none)	用于验证 webhook 的密钥
GUARDRAIL_BILLING_ENABLED	true	即使设置了 API 密钥，也可设为 false 以停用计费

许可证

MIT