AgentGuardrail

Extensible reverse proxy for AI agent traffic management.

---

AgentGuardrail sits between your AI agents and upstream services, enforcing traffic policies defined in declarative YAML contracts. It prevents agents from overwhelming downstream APIs with uncontrolled request bursts.

Features

• Rate Limiting — Token bucket per endpoint with burst support
• SLO Tracking — Pass-rate metrics compared against configurable targets
• Declarative Contracts — YAML-based traffic policy definitions
• Plugin Architecture — Extensible feature pipeline for adding SRE, RAG, and custom capabilities
• Observability — Prometheus metrics, Jaeger traces, Grafana dashboards

Quick Start

# Install
pip install -e ".[dev]"

# Define a contract
cat > my-contract.yaml << 'EOF'
apiVersion: agentsentry.io/v1alpha1
kind: RateLimitContract
metadata:
  name: my-guardrails
spec:
  egress_rate_limits:
    "api.example.com/orders": 5.0
  rate_limit_slos:
    "api.example.com/orders": 0.95
EOF

# Start the proxy
agentguardrail start --contract my-contract.yaml --port 8080

# Send requests through the proxy
curl http://localhost:8080/orders -H "X-Target-Host: api.example.com"

Architecture

AI Agent → AgentGuardrail (:8080) → Upstream API
               │
               ├── Rate Limiting (token bucket)
               ├── SRE (planned: circuit breakers, retries)
               └── RAG (planned: token budgets, embedding throttling)

Requests pass through a feature pipeline. Each feature can inspect, modify, or reject a request. First feature to return a response short-circuits the pipeline.

Project Structure

src/agentguardrail/
├── core/proxy.py              # HTTP reverse proxy (FastAPI + httpx)
├── features/                  # Plugin system
│   ├── __init__.py            # Feature ABC + FeatureRegistry
│   └── rate_limiting/         # Token bucket rate limiter
├── metrics/                   # MetricsRegistry + SLOEvaluator
├── contracts/                 # Contract re-exports
├── cli.py                     # CLI (start, validate)
├── config.py                  # Environment-based configuration
├── errors.py                  # Exception hierarchy
└── types.py                   # Shared types (RequestContext, FeatureConfig)

Development

make dev          # Install with dev dependencies
make test         # Run unit tests
make lint         # Run ruff linter
make type-check   # Run mypy

Docker

docker build -t agentguardrail .
docker run -p 8080:8080 -v $(pwd)/my-contract.yaml:/app/reliability-contract.yaml agentguardrail

With monitoring (Prometheus + Grafana + Jaeger):

cd observability/docker
docker compose -f compose.yml --profile with-monitoring up --build

Documentation

Document	Description
Product Overview	What AgentGuardrail does and why
Getting Started	Installation and setup
Architecture	Technical design and plugin system
API Reference	Public API, routing headers, CLI
Developer Guide	Contributing and adding features
Contract Reference	Contract schema and endpoint format
Local Demo	Docker Compose demo with monitoring
LangChain Example	ReAct agent quickstart

License

MIT