Quickstart

Prerequisites: Python >=3.12.9, uv, Git, and make. The demos also use curl and python3 on your PATH. No Docker, PostgreSQL, cloud credentials, or AI coding tool required.

Terminal 1 — start the backend:

git clone https://github.com/Mr-DooSun/fastapi-agent-blueprint.git
cd fastapi-agent-blueprint
make quickstart

This installs the quickstart dependencies, creates a SQLite database, and keeps the server running on port 8001. Use a fresh checkout for evaluation: quickstart syncs the admin extra and can remove other installed extras. For development dependencies and commit hooks, use make setup when moving to the development setup.

Terminal 2 — from the same repository directory:

make demo       # JWT auth, admin-realm login, user CRUD, refresh and logout
make demo-rag   # document upload, retrieval and an answer with citations

Keep terminal 1 running. Both demos check their API responses and report failure if a request does not succeed. The default RAG demo uses a keyword-based stub embedder and a templated stub answer agent; it demonstrates the pipeline without calling an external model.

• API docs — browse the API or download its OpenAPI spec.
• Admin UI — evaluation bootstrap login: admin / admin.
• Quickstart details · Full integration walkthrough.

These defaults are for local evaluation. Follow the development and deployment guides before using real data or exposing the service.

<a id="platform-in-action"></a>

Worked example: add an API to an existing domain

For a request such as “add a filtered list endpoint to the order domain,” the workflow is:

This is an illustrative workflow, not a command that runs every step automatically. Human decisions remain part of the process.

What is enforced? Configured pre-commit/CI checks block detected violations such as prohibited imports, broken documentation links, or shared-file language policy failures. Workflow reminders are advisory in many cases. For example, the plan-to-execution gate blocks matching source edits in Claude, while Codex receives a Stop-time advisory. Tool adapters share policy but do not provide identical enforcement. See the operating model for current coverage and exceptions.

Domain scaffolding is another supported task:

Set up Claude Code or Codex · Antigravity harness · Shared rules · Manual development path

Worked example: document QA

The docs domain composes document upload, chunking, embedding, retrieval, and answers with citations. Its shared RAG pipeline can be reused by other domains (ADR 040).

For real model calls, install the pydantic-ai extra, configure EMBEDDING_PROVIDER + EMBEDDING_MODEL and LLM_PROVIDER + LLM_MODEL, and supply the selected providers' credentials. See the configuration reference for optional extras and settings; the RAG walkthrough shows the flow.

<a id="interfaces"></a>

HTTP, worker, and admin interfaces are implemented. The MCP server interface is planned, not part of the runnable backend today.