Agent Ops
Live demo: agent-ops-sage.vercel.app
— browse completed sessions and inspect their full traces without signing in.
The free backend may take about a minute to wake up.
Recruiter walkthrough: open the no-credentials resilience demo
to see multi-step research, provider failover, tool-error recovery, prompt-injection
defense, and an explicit approval boundary in one auditable trace.
Architecture at a glance
Every stage emits structured events into the append-only trace. Irreversible tool calls pause at
the persisted approval gate, while transient provider and tool failures remain visible through
automatic failover and bounded recovery. See ARCHITECTURE.md for the detailed
state machine and design rationale.
A multi-agent orchestration copilot: a planner agent breaks an incoming task
into steps and delegates each to a tool-using sub-agent (web search, a
notes/document store, a calculator). Every irreversible action pauses for
human approval before it runs. Every session has persistent memory and a
full trace of what each agent decided, which tool it called, and why —
visible in the UI, not just in logs.
See ARCHITECTURE.md for how it's built and
ADR.md for why each stack/design choice was made (including the
LangGraph-vs-CrewAI decision and the Gemini+OpenRouter failover design).
Stack
- Backend: Python, FastAPI, LangGraph
- LLM: Gemini (primary) with an automatic OpenRouter
:free-model
fallback behind one provider interface
- Frontend: React, TypeScript, Vite, Tailwind
- Database: Supabase Postgres + pgvector
- Deploy: Render (backend), Vercel (frontend), both auto-deploy on
main
- CI: GitHub Actions (lint, type checks, tests, builds, and backend
container smoke verification)
Local development
Backend
cd backend
python -m venv .venv
source .venv/Scripts/activate # Windows Git Bash; use .venv/bin/activate on macOS/Linux
pip install -r requirements-dev.txt
cp ../.env.example ../.env # fill in real values, see below
python -m scripts.migrate # applies backend/migrations/*.sql — run once, and again after any schema change
uvicorn app.main:app --reload
python -m scripts.archive_sessions prints which sessions its QA/demo-fixture
heuristics would soft-archive, without changing anything; add --apply to
archive them for real, or --restore-all to undo every archive in one shot.
python -m scripts.reap_sessions prints which sessions look stranded — a
running session with no update in over 15 minutes, or a created session
never messaged in over a day — without changing anything; add --apply to
mark the stalled ones failed and archive the never-messaged ones for real.
It never touches awaiting_approval sessions.
Set an AGENT_OPS_API_KEY containing at least 32 bytes, then check the service with
curl http://localhost:8000/health and
curl http://localhost:8000/health/ready (the second reports which of
Gemini/OpenRouter/Supabase/DB config is missing, without ever printing a
secret value). Readiness confirms configuration and database reachability;
it does not spend provider requests or prove that configured credentials are valid.
Sessions, messages, the trace log, and the approval state machine (Day 3)
live in Postgres — POST /sessions, GET /sessions,
GET /sessions/{id}, POST /sessions/{id}/messages,
GET /sessions/{id}/trace, POST /approvals/{id}/approve /
.../reject. See /docs for the full schema, or ADR.md (ADR-014/015/016)
for how the approval pause survives across separate requests.
A session accepts a follow-up message once it reaches done, degraded, or
failed (ADR-033) — the agent keeps its prior messages and notes for that
session, so a second message can build on the first. running and
awaiting_approval still reject a second message with a 409; a session is
never mid-flight across two requests in this fully synchronous design.
Sessions can be soft-archived without deleting them: POST /sessions/{id}/archive / .../restore set or clear archived_at. GET /sessions excludes archived sessions by default; pass
?include_archived=true to see everything. An archived session still opens
directly by GET /sessions/{id}.
Every POST requires X-Agent-Ops-Key. The frontend asks for that key at
runtime and keeps it in sessionStorage; it is never a VITE_* value and is
not compiled into the public bundle. Read-only session, trace, liveness, and
readiness requests remain unauthenticated for demo observability.
Run checks locally exactly as CI does:
ruff check .
black --check .
pytest -v
Frontend
cd frontend
npm install
cp .env.example .env # VITE_API_URL — defaults to http://localhost:8000
npm run dev
npm run lint
npm run format:check
npm test
VITE_API_URL=https://api.example.invalid npm run build
Production builds require VITE_API_URL; local development falls back to
http://localhost:8000. See frontend/README.md for browser behavior and
Vercel setup.
Backend container
The backend Dockerfile builds a non-root runtime image containing the app and
forward migrations. Its health check uses /health (liveness), never
dependency readiness.
Pre-commit hooks
pip install pre-commit
pre-commit install
Ruff and Black run in isolated pre-commit environments. Frontend hooks use the
project's installed ESLint and Prettier and check only the changed files, so
run npm install in frontend/ before installing the hooks.
Environment variables
Copy .env.example to .env at the repo root (backend reads it) and
frontend/.env.example to frontend/.env (Vite only reads env files from
within frontend/). Every variable is documented inline in the .example
files, including which free-tier signup page to get each key from and how to
pick a current OpenRouter :free tool-calling model (the lineup rotates —
see ADR-002 in ADR.md for the live-verification method).
Never commit .env. It's gitignored from the first commit in this repo;
double-check git status before pushing if you ever see it listed.
Production deployment
render.yaml defines one free Docker web service and points platform health
checks at /health. frontend/vercel.json defines the Vite output and SPA
rewrite. All secrets stay in provider dashboards.
Release order:
- From the release commit, build the backend image:
docker build -t agent-ops-backend:release ./backend.
- Before a schema-bearing deploy, run the same image explicitly against the
production database:
docker run --rm --env-file .env agent-ops-backend:release python -m scripts.migrate.
The runner holds a PostgreSQL advisory lock, records each applied filename,
and is safe to repeat. It is deliberately not part of API startup.
After a deploy that adds archived_at (or any future soft-delete flag),
dry-run docker run --rm --env-file .env agent-ops-backend:release python -m scripts.archive_sessions, read the printed plan, then re-run with --apply.
- With the same dashboard environment, actively verify database, Supabase,
Gemini, Tavily, and the optional OpenRouter fallback:
docker run --rm --env-file .env agent-ops-backend:release python -m scripts.release_check.
This command logs only check names and outcomes, never provider response bodies.
- Create the Render service from
render.yaml, fill every sync: false
variable, and verify /health over HTTPS.
- Import the repository into Vercel with
frontend as the Root Directory.
Set VITE_API_URL to the exact Render origin and deploy.
- Set Render's
CORS_ORIGINS to the exact scheme-qualified Vercel production
origin, redeploy, then run the authenticated approval and rejection flows.
Application rollback means redeploying the previous known-good commit. Database
migrations are forward-only: never edit or reverse an applied file; ship a new
corrective migration if a schema issue is found. Current public URLs and live
walkthrough evidence are recorded in .planning/SPRINT_03_RELEASE_CANDIDATE.md.
Free-tier quirks you'll hit
- Supabase free projects can pause after prolonged inactivity. If readiness
reports the database unreachable, restore the project in Supabase before
retrying the demo.
- Render free web services spin down after 15 minutes idle. The first
request after a while will take 30-60 seconds to cold-start — that's
expected, not a bug, if you're smoke-testing the live URL. The frontend
retries idempotent reads once and shows cold-start guidance; mutations are
never automatically retried because their server outcome may be ambiguous.
- OpenRouter free models cap at 20 requests/minute and 50/day per model
with no card on file — reserved for the fallback path and its own tests,
not routine dev-loop iteration (use Gemini for that).
Repo layout
backend/ FastAPI app, agent graph, tests
backend/migrations/ SQL schema, applied by backend/scripts/migrate.py
frontend/ React + Vite + Tailwind app, tests
.github/ CI workflow, issue/PR templates
ADR.md Architecture Decision Records — what we chose and gave up
ARCHITECTURE.md System design: components, data flow, deployment topology
Build log
This project is being built in public over 7 days as a portfolio piece. Each
day is tagged (day-1-complete, day-2-complete, ...) once its scope from
the build plan is done. RETROSPECTIVE.md (Day 7) has the full writeup.
