AlexandrAI AGENTS.md
agents-md

Personal Work Agent Admin API Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent FastAPI internal routes, admin query service, runtime controls, metrics, memory snapshot, and tests.

AGENTS.md

Guidance for coding agents working on the Personal Work Agent internal FastAPI admin boundary.

Project Overview

The app exposes internal routes for runtime run-once, review push, outbound processing, admin status, case timeline, metrics, memory snapshot, and agent sync state. Routes should remain thin adapters over app state and AdminQueryService.

Use this boundary when changing internal operational APIs, admin snapshots, case timelines, memory reporting, middleware logging, or error responses.

Project Map

  • src/workagent/app/server.py creates the FastAPI app and attaches runtime dependencies.
  • src/workagent/app/routes.py defines internal runtime and admin routes.
  • src/workagent/app/deps.py provides async DB sessions.
  • src/workagent/app/errors.py registers structured error handlers.
  • src/workagent/app/middleware.py redacts request context for logs.
  • src/workagent/services/admin.py builds status, timeline, metrics, memory, and agent sync snapshots.
  • tests/test_app_routes.py, test_admin_routes.py, test_app_middleware.py, and test_app_runtime.py cover the route boundary.

Setup Commands

bashuv run pytest tests/test_app_routes.py tests/test_admin_routes.py tests/test_app_middleware.py -q
uv run pytest tests/test_app_runtime.py tests/test_outbound_processor.py tests/test_review_push.py -q
make lint

Change Rules For Agents

  • Keep routes thin: request parsing, dependency lookup, service call, JSON response.
  • Return service-unavailable responses when optional runtime services are not attached.
  • Preserve not-found behavior for missing case timelines.
  • Keep admin snapshot queries in AdminQueryService, not inline in routes.
  • Redact sensitive headers, query params, body fields, tokens, secrets, and credentials in middleware.
  • Do not expose local filesystem roots or private endpoints through admin payloads intended for public sharing.
  • Use async DB sessions consistently.

Verification

bashuv run pytest tests/test_app_routes.py tests/test_admin_routes.py tests/test_app_middleware.py -q
make lint

For route additions, include tests for missing dependencies and successful service delegation.

Security Notes

Internal routes reveal operational state. Keep them scoped, redact logs, and avoid returning secrets, tokens, raw credentials, private endpoint values, or machine-specific paths.

PR Checklist

  • Routes remain adapter-thin.
  • Error responses are covered.
  • Middleware redaction still catches sensitive fields.
  • Admin snapshots are generated by service code.