agent-gatekeeper 1.0.0

Identity and permission layer for AI agents — Auth0 for agents

AgentGate

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

pip install agent-gatekeeper

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 for details.