Metadata-Version: 2.4
Name: agent-gatekeeper
Version: 1.0.0
Summary: Identity and permission layer for AI agents — Auth0 for agents
Author: Jack Blacketter
License: MIT
Project-URL: Homepage, https://github.com/jblacketter/agent-gate
Project-URL: Repository, https://github.com/jblacketter/agent-gate
Project-URL: Issues, https://github.com/jblacketter/agent-gate/issues
Keywords: ai,agents,identity,permissions,auth,gatekeeper,security,llm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Dynamic: license-file

# AgentGate

[![PyPI](https://img.shields.io/pypi/v/agentgate)](https://pypi.org/project/agent-gatekeeper/)
[![Python](https://img.shields.io/pypi/pyversions/agentgate)](https://pypi.org/project/agent-gatekeeper/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Auth0 for AI agents** — verifiable identity, scoped permissions, human-approval escalation.

AgentGate gives every AI agent a cryptographic identity, enforces deny-by-default
permissions through YAML-defined policies, and escalates high-risk actions to a
human before they execute.

## Quick Start

```bash
pip install agent-gatekeeper
```

```python
from agentgate import AgentIdentity, PermissionPolicy, GateKeeper, Action
from agentgate.policy import ActionRule

# 1. Create an agent identity
agent = AgentIdentity.create("research-bot", capabilities=["search", "summarize"])

# 2. Define a permission policy
policy = PermissionPolicy(
    name="research-policy",
    rules=[
        ActionRule(action=Action.TOOL_USE, allowed=True, allowed_targets=["search"]),
        ActionRule(action=Action.LLM_CALL, allowed=True, max_per_minute=10),
        ActionRule(action=Action.SHELL, allowed=False),
    ],
)

# 3. Enforce at runtime
gate = GateKeeper(identity=agent, policy=policy)

decision = gate.check("tool_use", target="search")
print(decision.type)  # DecisionType.ALLOW

decision = gate.check("shell")
print(decision.type)  # DecisionType.DENY
```

## Features

- **HMAC-signed identity** — every agent gets a unique key pair for message signing and verification
- **Deny-by-default policies** — nothing is allowed unless explicitly permitted
- **YAML round-trip** — define policies as code, load and save from YAML files
- **Target-level scoping** — allow specific tools, files, or endpoints while denying others
- **Usage thresholds** — escalate or hard-deny after N uses of an action
- **Rate limiting** — cap actions per minute to prevent runaway agents
- **Human-approval escalation** — plug in your own approval handler (Slack bot, CLI prompt, webhook)
- **Decision audit log** — full history of every gate check for observability

## API Reference

### AgentIdentity

Verifiable identity for an AI agent, backed by HMAC-SHA256.

| Method | Description |
|---|---|
| `AgentIdentity.create(name, capabilities=None)` | Create a new agent with a generated UUID and secret key |
| `agent.sign(message) -> str` | Sign a message string, returns hex digest |
| `agent.verify(message, signature) -> bool` | Verify a signature against this agent's key |

**Fields:** `id`, `name`, `capabilities`, `created_at`, `secret_key`, `metadata`

### PermissionPolicy

Deny-by-default permission policy with YAML serialization.

| Method | Description |
|---|---|
| `policy.check(action, target=None) -> str` | Returns `"allow"`, `"deny"`, or `"escalate"` |
| `policy.get_rule(action) -> ActionRule` | Get the rule for a specific action type |
| `PermissionPolicy.from_yaml(path)` | Load a policy from a YAML file |
| `policy.to_yaml(path)` | Save a policy to a YAML file |

**Actions:** `tool_use`, `llm_call`, `file_read`, `file_write`, `network`, `shell`, `data_access`

### GateKeeper

Runtime enforcement engine that combines identity, policy, thresholds, and escalation.

| Method | Description |
|---|---|
| `gate.check(action, target=None) -> Decision` | Check permission; returns a `Decision` object |
| `gate.is_allowed(action, target=None) -> bool` | Convenience boolean check |
| `gate.require(action, target=None) -> Decision` | Check and raise `PermissionError` if denied |
| `gate.decisions -> list[Decision]` | Full audit history of all gate checks |

**Decision fields:** `type` (ALLOW/DENY/ESCALATE), `agent_id`, `action`, `target`, `reason`, `timestamp`, `approved_by`

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                    Your Agent                       │
│                                                     │
│   action request                                    │
│        │                                            │
│        v                                            │
│   ┌──────────┐    ┌──────────────────┐              │
│   │GateKeeper│───>│PermissionPolicy  │              │
│   │          │    │  (YAML rules)    │              │
│   │          │    └──────────────────┘              │
│   │          │                                      │
│   │          │──> threshold / rate-limit check      │
│   │          │                                      │
│   │          │──> escalation ──> approval_handler() │
│   │          │                     (human / webhook)│
│   └──────────┘                                      │
│        │                                            │
│        v                                            │
│   Decision(ALLOW / DENY / ESCALATE)                 │
│   + full audit log                                  │
└─────────────────────────────────────────────────────┘
         │
         v
   AgentIdentity
   (HMAC-signed, UUID-backed)
```

## Comparison

| Feature | AgentGate | Raw LLM APIs | LangChain Tools | Custom middleware |
|---|---|---|---|---|
| Agent identity with crypto signing | Yes | No | No | Manual |
| Deny-by-default policies | Yes | No | No | Manual |
| YAML policy definition | Yes | No | No | No |
| Per-action rate limiting | Yes | No | No | Manual |
| Human-approval escalation | Yes | No | No | Manual |
| Decision audit log | Yes | No | No | Manual |
| Zero dependencies beyond pydantic | Yes | N/A | Heavy | Varies |

## License

MIT License. See [LICENSE](LICENSE) for details.
