AgentGate

[English](#english) | [中文](#中文)

# AgentGate

**Runtime security for autonomous AI agents. / 自主 AI 智能体的运行时安全框架。**

[![PyPI version](https://img.shields.io/pypi/v/agentgate.svg)](https://pypi.org/project/agentgate/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/agentgate/agentgate/ci.yml?branch=main)](https://github.com/agentgate/agentgate/actions)
[![Python](https://img.shields.io/pypi/pyversions/agentgate.svg)](https://pypi.org/project/agentgate/)

---

## The Problem / 问题背景 {#english}

AI agents are growing explosively. Frameworks like LangChain, CrewAI, and AutoGen make it trivial to build agents that call tools, browse the web, execute code, and modify files -- often with minimal human oversight.

Security tooling has not kept up. The [OWASP Top 10 for Agentic AI (2025)](https://owasp.org/www-project-agentic-ai-top-10/) highlights critical risks including unbounded tool access, insufficient sandboxing, missing audit trails, and privilege escalation between agents.

Existing solutions focus on **LLM-level** guardrails -- prompt injection detection, content filtering, hallucination checks. Almost none address **agent-level** security: controlling *what tools an agent can call*, *with what arguments*, *how often*, and *what happens when it misbehaves*.

---

{#中文}

AI 智能体正在爆发式增长。LangChain、CrewAI、AutoGen 等框架使得构建能够调用工具、浏览网页、执行代码和修改文件的智能体变得极其简单——而这些操作往往缺乏充分的人工监督。

安全工具远未跟上这一发展速度。[OWASP Agentic AI Top 10 (2025)](https://owasp.org/www-project-agentic-ai-top-10/) 指出了若干关键风险，包括不受限的工具访问、不充分的沙箱隔离、缺失的审计追踪，以及智能体之间的权限提升问题。

现有方案大多关注 **LLM 层面**的防护——提示注入检测、内容过滤、幻觉检查。几乎没有方案专门解决**智能体层面**的安全问题：控制*智能体能调用哪些工具*、*使用什么参数*、*调用频率如何*，以及*出现异常行为时如何处置*。

---

## What AgentGate Does / AgentGate 做了什么

AgentGate is an open-source security framework purpose-built for the agent layer. It sits between your AI agents and the tools they invoke, providing:

- **Fine-grained permissions** -- declarative YAML policies that control which tools each agent can call, with argument-level constraints (regex patterns, enum values, numeric bounds).
- **Deny-first evaluation** -- deny rules are always checked before allow rules, ensuring explicit blocks cannot be bypassed.
- **Rate limiting** -- sliding-window rate limits per agent and tool to prevent runaway execution.
- **Session controls** -- hard limits on total tool calls and session duration.
- **Comprehensive audit trail** -- every tool call is logged with arguments, decision, result summary, timing, and anomaly scores. Stored in SQLite with optional Ed25519 cryptographic signatures.
- **Anomaly detection** -- built-in heuristic detector flags burst activity, unusual tool diversity, and suspiciously fast execution.
- **Framework integrations** -- drop-in support for LangChain, CrewAI, AutoGen, and any Python function via a simple decorator.
- **No code changes required** -- wrap existing tools with a decorator or plug in framework middleware. Your agent code stays untouched.

---

AgentGate 是一个专为智能体层打造的开源安全框架。它位于 AI 智能体和其调用的工具之间，提供以下能力：

- **细粒度权限控制** -- 声明式 YAML 策略，控制每个智能体可以调用哪些工具，并支持参数级别的约束（正则表达式、枚举值、数值范围）。
- **拒绝优先评估** -- 拒绝规则始终先于允许规则执行，确保显式阻断不会被绕过。
- **速率限制** -- 基于滑动窗口的速率限制，按智能体和工具分别生效，防止失控执行。
- **会话控制** -- 对工具调用总次数和会话时长施加硬性上限。
- **全面审计追踪** -- 记录每次工具调用的参数、决策结果、返回摘要、耗时及异常评分。数据存储在 SQLite 中，支持可选的 Ed25519 加密签名。
- **异常检测** -- 内置启发式检测器，可标记突发活动、异常工具多样性和可疑的极短执行时间。
- **多框架集成** -- 开箱即用地支持 LangChain、CrewAI、AutoGen，以及通过简单装饰器集成任意 Python 函数。
- **无需修改代码** -- 通过装饰器或框架中间件即可包装已有工具，原有智能体代码无需改动。

---

## Quick Start / 快速上手

### Installation / 安装

```bash
pip install agentgate
```

### Protect any function with the `@protect` decorator / 使用 `@protect` 装饰器保护任意函数

```python
from agentgate import protect

@protect(policy="policy.yaml", agent_id="code-assistant")
def read_file(path: str) -> str:
    return open(path).read()

# This call is checked against the policy before executing.
# If denied, raises agentgate.ToolCallDenied.
# 调用前会依据策略进行检查。若被拒绝，将抛出 agentgate.ToolCallDenied。
content = read_file(path="/tmp/data.txt")
```

### Use the `AgentGate` class directly / 直接使用 `AgentGate` 类

```python
from agentgate import AgentGate

gate = AgentGate(policy="policy.yaml")

result = await gate.intercept_tool_call(
    agent_id="code-assistant",
    session_id="sess-001",
    tool_name="read_file",
    tool_args={"path": "/tmp/data.txt"},
    execute_fn=actual_read_file,
)

gate.close()
```

### Scan a policy file from the CLI / 通过命令行扫描策略文件

```bash
agentgate scan policy.yaml
```

---

## Key Features / 核心功能

### Declarative YAML Policies / 声明式 YAML 策略

Define security rules in version-controlled YAML files. No code changes, no runtime configuration drift.

在版本管理的 YAML 文件中定义安全规则。无需修改代码，杜绝运行时配置漂移。

```yaml
version: "1"
agents:
  code-assistant:
    tools:
      denied:
        - name: "execute_shell"
          reason: "Shell execution is not permitted"
      allowed:
        - name: "read_file"
          args:
            path:
              pattern: "^/tmp/.*"
              max_length: 256
        - name: "write_file"
          rate_limit:
            max_calls: 10
            window_seconds: 60
```

### Framework Integrations / 框架集成

Works with LangChain, CrewAI, AutoGen, and any Python callable -- see [Integration Examples](#integration-examples--集成示例) below.

支持 LangChain、CrewAI、AutoGen 以及任意 Python 可调用对象——参见下方[集成示例](#integration-examples--集成示例)。

### Comprehensive Audit Trail / 全面审计追踪

Every tool call is recorded with full context: agent ID, session ID, tool name, arguments, policy decision, result summary, execution duration, anomaly score, and optional Ed25519 signature.

每次工具调用均被完整记录，包括：智能体 ID、会话 ID、工具名称、调用参数、策略决策、结果摘要、执行耗时、异常评分，以及可选的 Ed25519 签名。

### Anomaly Detection / 异常检测

Built-in heuristic detector with configurable sensitivity (low / medium / high). Flags burst activity, high tool diversity, and suspiciously fast execution. Supports alert delivery via log, webhook, or email.

内置启发式检测器，灵敏度可配置（low / medium / high）。能够标记突发活动、异常工具多样性和可疑的极短执行时间。支持通过日志、webhook 或邮件发送告警。

### CLI Tools / 命令行工具

| Command | Description / 说明 |
|---------|-------------|
| `agentgate init` | Generate a starter `policy.yaml` / 在当前目录生成初始 `policy.yaml` |
| `agentgate check <policy>` | Validate a policy file / 校验策略文件并报告错误或警告 |
| `agentgate scan <policy>` | Deep-scan for security issues / 深度扫描策略的安全问题和最佳实践 |
| `agentgate audit` | Query the audit trail / 查询并展示审计追踪记录 |
| `agentgate report` | Generate an HTML or JSON report / 生成 HTML 或 JSON 安全报告 |

---

## Integration Examples / 集成示例

### Generic `@protect` Decorator / 通用 `@protect` 装饰器

```python
from agentgate import protect

@protect(policy="policy.yaml", agent_id="data-pipeline")
async def fetch_url(url: str) -> str:
    async with aiohttp.ClientSession() as session:
        resp = await session.get(url)
        return await resp.text()
```

### LangChain Middleware / LangChain 中间件

```python
from agentgate.integrations.langchain import AgentGateMiddleware

middleware = AgentGateMiddleware(policy="policy.yaml")
agent = initialize_agent(tools, llm, agent_type=...)
agent.middleware = [middleware]
```

### CrewAI Callback / CrewAI 回调

```python
from agentgate.integrations.crewai import AgentGateCallback

callback = AgentGateCallback(policy="policy.yaml")
crew = Crew(agents=[...], tasks=[...], callbacks=[callback])
crew.kickoff()
```

### AutoGen Adapter / AutoGen 适配器

```python
from agentgate.integrations.autogen import AgentGateAdapter

adapter = AgentGateAdapter(policy="policy.yaml")
assistant = AssistantAgent("assistant", llm_config=llm_config)
adapter.wrap(assistant)
```

---

## Policy File Reference / 策略文件参考

The following example shows a full-featured policy file. See inline comments for explanations.

以下示例展示了一个功能完整的策略文件，请参阅行内注释了解各字段含义。

```yaml
version: "1"
description: "Production security policy"

agents:
  # Named agent with specific permissions
  # 具名智能体及其专属权限
  code-assistant:
    role: "Code analysis and generation"
    tools:
      d

[truncated…]