production-agent-template

A production-shaped FastAPI agent template. It gives you the operational shell that every long-running service ends up needing, so you can focus on your own logic:

• Async-first FastAPI app with a clean lifespan (startup/shutdown), plus health and dashboard endpoints.
• Resilience primitives: a circuit breaker registry that application code can use around outbound calls, plus a health monitor that can invoke dependency-specific recovery callbacks supplied by the application.
• Observability: a /metrics endpoint in Prometheus text format, plus standard application logging.
• Optional autonomous loop: a background task that runs on an interval, off by default and toggled from config.
• Scaffolder: a small script to stamp out a new agent from this template.

Drop your logic into engine.py and keep the rest.

Quickstart

git clone https://github.com/Musyg/production-agent-template.git
cd production-agent-template
python -m pip install -e ".[dev]"  # or: just install
just run                     # uvicorn on http://127.0.0.1:8000
curl localhost:8000/health

Without just:

uvicorn agent_template.main:app --reload

Architecture

flowchart LR
    client(["Client"]) -->|HTTP| app["FastAPI app"]
    app --> engine["Engine - your logic"]
    engine -. application integration .-> cb["Circuit breaker primitives"]
    cb --> deps[("External deps")]
    monitor["Health monitor"] -. watches / recovers .-> deps
    auto["Autonomous loop (optional)"] -. on interval .-> engine
    app --> obs["/metrics (Prometheus)"]

Loading

Module	Responsibility
main.py	FastAPI app, lifespan wiring, and the /health, /dashboard, /metrics, /process endpoints.
engine.py	Your business logic. The one file you customise.
circuit_breaker.py	Per-dependency failure isolation (CLOSED / OPEN / HALF_OPEN).
health_monitor.py	Periodic dependency checks with optional recovery callbacks.
autonomous.py	Optional background loop on a fixed interval.
metrics.py	Dependency-free counters and gauges, Prometheus text output.
settings.py	Env-driven configuration (prefix AGENT_).

Features

• Async-first FastAPI app with a clean startup/shutdown lifespan.
• /health and /dashboard endpoints reporting live dependency and breaker state.
• /metrics in Prometheus text format, with no external metrics dependency.
• /process endpoint that runs payloads through your engine and counts requests.
• Circuit breaker primitives per dependency, with half-open probing and trip counts; application code chooses which outbound operations to protect.
• Health monitor that checks dependencies on an interval and invokes an optional recovery callback when a check fails.
• Optional autonomous loop, off by default, toggled from config.
• Fully env-driven configuration (AGENT_*) plus scripts/scaffold.py to stamp out new instances.
• CI (Ruff, pytest, and package build) across Python 3.11, 3.12, 3.13, and 3.14.

Scope and non-goals

This project is production-shaped, not a complete production deployment. It provides a tested application shell and extension points. A real service still needs the controls appropriate to its environment, including authentication and authorization, domain-specific input validation, secrets management, durable storage or queues, rate limits, TLS/ingress, deployment manifests, tracing and log shipping, and a threat model.

Dependency checks and recovery actions are intentionally application-defined. The template schedules them and reports their state; it cannot infer a safe recovery procedure for an arbitrary external system.

Extending

Put your business logic in src/agent_template/engine.py. The operational shell (health, metrics, recovery callbacks, lifecycle) stays as is.

Tests

pytest -q       # or: just test
ruff check .    # or: just lint
ruff format .   # or: just fmt
python -m build # source and wheel distributions

Related libraries

These standalone MIT libraries were extracted and generalised from this template. Use the template as the integrated reference, or pull the bricks on their own:

• async-api-client - resilient async REST client (rate limiting, retries, pagination).
• agent-resilience - circuit breaker, Redis-backed DLQ, offline MQTT buffer.
• multi-agent-orchestrator - capability-based task routing.

License

MIT - see LICENSE.