Agentic Django Example Project

This Django project exercises the agentic-django package from PyPI. The library provides agent run/session primitives, tool calling, and web-friendly UI hooks to build LLM-powered Django apps. See the agentic-django GitHub repo and the agentic-django PyPI page.

For repo navigation and maintenance rules, start with AGENTS.md and docs/index.md. The docs directory is the source of truth for architecture, operations, quality expectations, and legibility notes.

The dependency is wired in pyproject.toml as:

agentic-django[rq]>=0.5.1
django-htmx>=1.29.0

Quick start (Docker)

Prereqs: Docker Desktop (or compatible Docker CLI + Compose plugin).

1. Configure env vars:

cp .env.example .env

Set OPENAI_API_KEY in .env. Optionally set OPENAI_DEFAULT_MODEL.

2. Build and run:

docker compose up --build

Visit http://localhost:8000/ and use the "Demo login" button.

Quick start (local)

Prereqs: Python 3.14+, PDM, and (optionally) Redis if you want background runs.

1. Install dependencies:

pdm install --group dev

2. Configure env vars:

cp .env.example .env

Set OPENAI_API_KEY in .env. Optionally set OPENAI_DEFAULT_MODEL.

3. Run migrations:

pdm run python manage.py migrate

4. Start the dev server:

pdm run python manage.py runserver

Visit http://localhost:8000/ and use the "Demo login" button.

Optional: enable background runs by setting TASKS_BACKEND=django_tasks_rq.RQBackend and starting an RQ worker:

pdm run python manage.py rqworker --job-class django_tasks_rq.Job

Validation

pdm run lint
pdm run typecheck
pdm run docs
pdm run test
pdm run check
npm test
npm run build:css

pdm run check runs lint, strict type checks, offline documentation checks, and Python tests. Install Perfect Doc 0.1.0 or later on PATH before this command. See Quality for setup and type-check rules.

What this demo shows (and where)

• Agent registry and prompt loading: apps/sample_app/agent_registry.py builds the demo Agent and pulls instructions from apps/sample_app/prompts/demo_agent.prompt.md using promptdown.
• Tool calling: apps/sample_app/tools.py defines three @function_tool examples (find, price, book) to show tool usage.
• Agent runs and sessions: apps/sample_app/views.py wires per-user AgentSession and uses the agentic_django run/session models to track history.
• HTMX run flow: apps/sample_app/templates/sample_app/home.html posts to agents:run-create, polls agents:run-fragment, and refreshes the conversation via agents:session-items.
• HTMX integration wiring: agentic_django_example/settings.py enables django_htmx, apps/sample_app/templates/sample_app/base.html renders {% htmx_script %}, and CSP is limited to self-hosted scripts.
• Conversation rendering: templates/agentic_django/partials/conversation.html and apps/sample_app/templatetags/sample_app_tags.py format messages, tool calls, and reasoning summaries.
• Background execution (optional): agentic_django_example/settings.py configures django_tasks with an RQ backend; docker-compose.yml starts Redis + an RQ worker.

Integration notes

• The library now uses django-htmx internally. The example therefore enables django_htmx in INSTALLED_APPS and django_htmx.middleware.HtmxMiddleware in MIDDLEWARE so package views can rely on request.htmx.
• HTMX is now served through django-htmx's {% htmx_script %} template tag instead of a CDN <script> tag. This keeps the demo aligned with Django 6 CSP support and avoids an external script-src exception.
• Run polling now stops server-side with django_htmx.http.HttpResponseStopPolling (HTTP 286) when a run reaches a terminal state. The example test suite covers that behavior.