A Python framework that lets developers build AI agents with structured control flow and built‑in auditing of database and tool accesses.

Quick Start • Features • Examples • Contributing

What is this?

AgentGuard provides a declarative DSL for defining agent behavior and automatically records every database call, file operation, or external tool access. It is aimed at backend and DevOps engineers who need transparent, auditable LLM‑driven agents without adding manual logging.

$ agentguard run-agent --tool db.query "SELECT 1"
[INFO] Audit recorded: {"ts":1728000000000,"actor":"db","action":"db.query","resource":"SELECT 1","outcome":"SUCCESS","duration":2.3}

Problem

Developers lack a middle ground between black‑box AI computer‑use agents and raw tool calls, making it hard to enforce security policies or trace agent behavior. Current solutions either hide internal steps or require manual logging, leading to opaque and potentially unsafe agents in production.

Features

Feature	Description
Structured Control‑Flow DSL	Define states, transitions, and guards with a tiny typed language; enables static analysis and model‑checking of agent behavior.
Built‑in Auditing Middleware	Every tool call, database query, or file operation is wrapped automatically with a structured audit record (timestamp, actor, action, resource, outcome, duration).
Pluggable Storage Backend	Abstract interface for persisting audit logs; provided implementations for SQLite, JSON files, and in‑memory ring buffer.
Click‑Based CLI	Parses commands and dispatches to the control‑flow interpreter; provides subcommands for checking flows, running agents, and storing audit data.
Tool Registry Loader	Loads JSON/YAML descriptors for external services (databases, APIs, file‑system) and makes them available to the agent core.
Zero‑Cost Instrumentation	Auditing middleware adds no developer‑written logging calls; overhead is limited to the actual I/O operation.

Quick Start

1. Clone the repository:

   git clone https://github.com/m2ai-portfolio/agentguard.git
   cd agentguard

2. Install the package in editable mode:

   pip install -e .

3. Verify the CLI works:

   agentguard run --help

   Expected output shows usage information and exits with code 0.

Examples

Validate a control‑flow graph

agentguard check-flow --file examples/simple.agf

Sample output:

PASS
States: init, query, write, end
Transitions: init -> query on start, query -> write on rows_returned, write -> end on write_done

Run an agent with a database tool and see the audit entry

agentguard run-agent --tool db.query "SELECT id FROM users WHERE active = 1"

Sample output:

[INFO] Audit recorded: {"ts":1728000001200,"actor":"db","action":"db.query","resource":"SELECT id FROM users WHERE active = 1","outcome":"SUCCESS","duration":4.7}

Switch storage backend to JSON and persist records

AGENT_STORAGE_BACKEND=json agentguard store-audit --backend json --record '{"ts":1728000002000,"actor":"file","action":"file.write","resource":"log.txt","outcome":"SUCCESS","duration":1.2}'

Sample output:

[OK] Stored record to ./audit.json

Reading back the file shows the same JSON line appended.

File Structure

AgentGuard: Auditable AI Agent Framework/
  agentguard/               # Core source code
    __init__.py
    cli.py                  # Click entrypoint
    control_flow.py         # DSL parser & interpreter
    agent.py                # Core loop & tool dispatcher
    audit.py                # Middleware & record model
    storage/                # Backend implementations
      __init__.py
      sqlite.py
      json.py
      memory.py
    tools/                  # Tool descriptors & wrappers
      __init__.py
      example_tool.py
  tests/                    # Test suite
    test_control_flow.py
    test_audit.py
    test_storage.py
  examples/                 # Sample flow files and scripts
    simple.agf
    invalid_goto.agf
    invalid_unreachable.agf
    workflow.py
  pyproject.toml            # Build configuration
  README.md                 # This file

Tech Stack

Technology	Purpose
Python 3.11+	Core language runtime
Click	Command‑line interface framework
Pytest	Test harness
sqlite3 (stdlib)	Default audit storage backend
json (stdlib)	Optional JSON file backend
YAML (via PyYAML optional)	Tool descriptor parsing (if used)

Contributing

Fork the repository, make changes, run pytest -q to verify, then submit a pull request.

License

MIT

Author

Matthew Snow -- [M2AI](https://m2ai.co) | [@m2ai-portfolio](https://github.com/m2ai-portfolio)