PII Agent

An AI agent demo that queries a PostgreSQL database containing personally identifiable information through natural language. Compare how different agent frameworks — Agno and Microsoft Agent Framework — handle tool use, schema discovery, and conversational interaction against the same dataset.

What It Does

You ask questions in plain English. The agent translates them into SQL, runs the queries, and returns the results.

You: How many people in the database are from California?

Agent: There are 5 people from California in the database.
       [runs: SELECT COUNT(*) FROM persons WHERE state = 'CA']

Agent Frameworks

Framework	File	Interaction	Highlights
MSFT Agent Framework	src/msft-agent-framework/data-agent.py	Interactive REPL	Streaming output, session memory, explicit schema discovery
Agno	src/agno/db-agent.py	Single-shot	Minimal setup, framework-managed tools
LangGraph	src/langgraph/	—	Planned

Quick Start

Prerequisites

• Python 3.12, uv, Docker
• A LiteLLM-compatible API endpoint (or direct LLM API key)

Setup

# 1. Environment
cp .env.sample .env              # Fill in LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_ID
uv venv && source .venv/bin/activate

# 2. Dependencies
uv pip install -r data/requirements.txt
uv pip install -r src/msft-agent-framework/requirements.txt

# 3. Database
docker compose -f data/docker-compose.yml up -d
python -m data.load_csv           # Loads 30 sample PII records

Run

# Interactive REPL (MSFT Agent Framework)
python src/msft-agent-framework/data-agent.py

# Single-shot query (Agno)
python src/agno/db-agent.py

Test

python -m pytest data/tests/ -v                              # Unit tests (no DB needed)
python -m pytest src/msft-agent-framework/test_tools.py -v   # Smoke tests (needs running DB)

Project Structure

pii-agent/
├── data/                          # Database provisioning (standalone)
│   ├── docker-compose.yml         # Postgres 16 container
│   ├── model.py                   # SQLAlchemy ORM (Person, 16 columns)
│   ├── load_csv.py                # Idempotent CSV loader
│   ├── sample-pii-data.csv        # 30 rows of synthetic PII
│   └── tests/                     # Unit tests (in-memory SQLite)
├── src/
│   ├── agno/                      # Agno framework agent
│   ├── msft-agent-framework/      # Microsoft Agent Framework agent
│   └── langgraph/                 # Planned
└── docs/
    ├── ARCHITECTURE.md            # System design, diagrams, design decisions
    ├── API_REFERENCE.md           # Module and function reference
    └── GETTING_STARTED.md         # Step-by-step setup guide

Sample Data

30 synthetic PII records with:

Category	Fields
Identity	id, fname, lname, maiden_name, gender, birthdate
Contact	address, city, state, zip, phone, email
Financial	cc_type, cc_number, cc_cvc, cc_expiredate

All columns are strings — intentional simplicity for the demo.

Documentation

• Getting Started — Full setup walkthrough with troubleshooting
• Architecture — System design, data flow diagrams, agent comparison
• API Reference — Module, function, and tool documentation

Environment Variables

Variable	Required	Description
LLM_API_KEY	Yes	API key for LiteLLM gateway
LLM_BASE_URL	Yes	Base URL for LLM gateway
LLM_MODEL_ID	Yes	Model identifier (e.g., claude-sonnet-4-5)
DATABASE_URL	No	Override default Postgres connection string