AgentGuard

The safety and audit layer for autonomous marketing agents.

AgentGuard is a governance proxy that sits between marketing AI agents and the systems they control (HubSpot, Meta Ads, Marketo, etc.). It logs every action, enforces budget/scope policies, and escalates risky decisions for human review.

Why

Marketing teams are deploying autonomous agents that spend budgets, change bids, and publish content — with zero visibility into why decisions were made. AgentGuard makes agent behavior observable, auditable, and controllable.

Architecture

[Marketing Agent]
       ↓
 ┌─────────────┐
 │  AgentGuard  │  ← intercept · log · enforce · escalate
 └─────────────┘
       ↓
[HubSpot / Meta Ads / Marketo / etc.]

Three layers, built in order:

Layer	What it does	Status
1. Intercept & Log	Record every agent action with full context	🔨 Building
2. Policy Engine	YAML-defined rules: budget caps, rate limits, blocklists	⏳ Next
3. Human-in-the-Loop	Slack escalations, approval queues, anomaly alerts	⏳ Later

Project Structure

agent-guard/
├── backend/          # FastAPI API + policy engine
│   ├── app/
│   │   ├── api/      # Route handlers
│   │   ├── core/     # Config, database, auth
│   │   ├── models/   # SQLAlchemy models + Pydantic schemas
│   │   └── services/ # Policy engine, notifications
│   ├── tests/
│   └── policies/     # Example YAML policy files
├── sdk/
│   └── python/       # pip-installable SDK with @guard.track() decorator
├── dashboard/        # React + Recharts observability UI
└── docs/

Getting Started

Option A: GitHub Codespaces (recommended)

1. Push this repo to GitHub
2. Click Code → Codespaces → Create codespace
3. The dev environment auto-configures (Python 3.12, Node 20, PostgreSQL, pip deps)
4. Start building:

   sudo service postgresql start
   cd backend && uvicorn app.main:app --reload

Option B: Local setup

cp .env.example .env
# Install and start Postgres, then:
cd backend
pip3 install -r requirements.txt
uvicorn app.main:app --reload

Tech Stack

• API: FastAPI (Python 3.12)
• Database: PostgreSQL + SQLAlchemy (async)
• Dashboard: React + Vite + Tailwind + Recharts
• SDK: Python package (pip install agentguard)
• Hosting: Railway / Render (~$20/month)

Build Roadmap

• Chunk 1: Project skeleton + Codespaces setup
• Chunk 2: FastAPI backend with health check
• Chunk 3: Database models (agents + action_events)
• Chunk 4: Event ingestion API (POST /api/v1/events/)
• Chunk 5: Event query API + stats endpoint
• Chunk 6: Python SDK (@guard.track() decorator)
• Chunk 7: Dashboard (event feed + stats)

License

MIT