Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
218 lines (145 loc) · 4.86 KB

GETTING_STARTED.md

File metadata and controls

218 lines (145 loc) · 4.86 KB

Getting Started with PII Agent

PII Agent is an AI agent demo that interacts with personally identifiable information (PII) stored in a PostgreSQL database. You ask questions in plain English, and the agent translates them into SQL queries, runs them, and returns the results.

This guide walks you through every step from a fresh clone to a running agent session.

What You Will End Up With

  • A running PostgreSQL 16 container holding 30 sample PII records
  • A working Python environment with all agent dependencies installed
  • At least one agent (MSFT Agent Framework or Agno) accepting natural language queries

Prerequisites

Tool Version Purpose
Python 3.12 Agent runtime
uv Any recent Package and virtual environment manager
Docker Any recent Runs the PostgreSQL container
A LiteLLM-compatible API endpoint — Powers the agent LLM calls

Verify each before proceeding:

python --version
uv --version
docker --version

Step 1 — Clone the Repository

git clone <repository-url>
cd pii-agent

Step 2 — Create the Virtual Environment and Configure .env

2a. Create the virtual environment

uv venv
source .venv/bin/activate      # macOS / Linux
# .venv\Scripts\activate       # Windows

2b. Copy .env.sample to .env

cp .env.sample .env

2c. Fill in your credentials

LLM_API_KEY=<your-api-key>
LLM_BASE_URL=<your-gateway-url>
LLM_MODEL_ID=<model-identifier>

Step 3 — Install Dependencies

# Core data dependencies (required for all agents)
uv pip install -r data/requirements.txt

# MSFT Agent Framework
uv pip install -r src/msft-agent-framework/requirements.txt

# Agno Agent (install manually)
uv pip install agno python-dotenv

Step 4 — Start the Database

docker compose -f data/docker-compose.yml up -d
Setting Value
Host localhost
Port 5432
Database pii_demo
Username postgres
Password MyDbPassword

Verify the container is running:

docker ps --filter name=pii

Step 5 — Load Sample Data

python -m data.load_csv
# Expected: Loaded 30 new rows into persons table.

This is idempotent — safe to run multiple times. Re-running prints "Loaded 0 new rows."

Sample Data Fields

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

Step 6 — Run the Tests

# Unit tests (no database required — uses in-memory SQLite)
python -m pytest data/tests/ -v

# Smoke tests (requires running database with data loaded)
python -m pytest src/msft-agent-framework/test_tools.py -v

Step 7 — Run an Agent

MSFT Agent Framework (interactive REPL)

python src/msft-agent-framework/data-agent.py

Example queries:

  • "What tables are available?"
  • "Show me all records for people in California."
  • "What is the breakdown of records by gender?"

Type quit or exit to stop.

Agno Agent (single-shot)

python src/agno/db-agent.py

Edit agent.print_response(...) in src/agno/db-agent.py to change the query.

Environment Variables Reference

Variable Required Default
LLM_API_KEY Yes None
LLM_BASE_URL Yes None
LLM_MODEL_ID Yes (MSFT agent) gpt-4o
DATABASE_URL No postgresql+psycopg://postgres:MyDbPassword@localhost:5432/pii_demo
DB_CONNINFO No host=localhost port=5432 dbname=pii_demo user=postgres password=MyDbPassword

Troubleshooting

Docker is not running

Start Docker Desktop (macOS/Windows) or sudo systemctl start docker (Linux).

Port 5432 already in use

Stop the conflicting Postgres instance, or change the host port in data/docker-compose.yml and update DATABASE_URL / DB_CONNINFO accordingly.

.env is missing or has angle brackets in values

Copy from .env.sample and replace <placeholders> with real values — no angle brackets.

Connection refused when loading CSV

The container is not running. Run docker compose -f data/docker-compose.yml up -d first.

Password authentication failed

Default credentials are postgres / MyDbPassword. Match these in your env vars if you changed docker-compose.yml.

Smoke tests fail with assert count == 30

Run python -m data.load_csv before the smoke tests.

Agent prints nothing after a query

LLM call is likely failing. Verify LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL_ID in .env.

ModuleNotFoundError: No module named 'data'

Run commands from the project root with the virtual environment active:

source .venv/bin/activate
cd /path/to/pii-agent
python -m data.load_csv
⚡