Django-native orchestration framework for building agentic workflows with database-backed job management, YAML-configurable pipelines, and real-time event streaming.
django-ais provides a structured, opinionated way to build agentic AI workflows inside Django projects. Instead of bolting on external orchestration tools, it works with Django's ORM, Celery, and Channels to give you:
- Worker / Strategy / Gateway pattern — clean separation between lifecycle management (Worker), intelligence & prompt engineering (Strategy), and compute execution (Gateway)
- DB-backed job tracking — persistent
JobPacketmodel with status, payload, result, parent-child relationships, and idempotency keys - Real-time event streaming —
AgentEventmodel + Redis-backed EventBus for SSE/WebSocket streaming of agent thoughts, logs, and state changes - YAML workflow definitions — declarative pipeline configuration, importable via management commands
- Dynamic worker registry — register workers in
AppConfig.ready(), dispatch jobs by type - Multi-tenant safety — scoped event streaming and job isolation per user/workspace
Those are great tools — but they operate outside your Django ecosystem. django-ais is for teams that want:
- Jobs persisted in your existing PostgreSQL database
- Celery as the task runner you already operate
- Django Channels for real-time streaming you already deploy
- Django ORM for querying job history, not a separate state store
- Standard Django patterns — models, migrations, admin, signals, management commands
If your stack is Django, your orchestration should be too.
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Worker │────▶│ Strategy │────▶│ Gateway │
│ (Lifecycle) │ │ (Brain) │ │ (Execution) │
│ │ │ │ │ │
│ • prepare() │ │ • compose() │ │ • execute() │
│ • route() │ │ • schema() │ │ • stream() │
│ • on_done() │ │ • tools() │ │ • trace() │
└─────────────┘ └──────────────┘ └─────────────────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ JobPacket │ │ EventBus │
│ (DB) │ │ (Redis) │
└──────────┘ └──────────┘
| Layer | Responsibility | Rule |
|---|---|---|
| Worker | Job lifecycle, state transitions, child job spawning | Knows Django models, owns the job |
| Strategy | Prompt engineering, context composition, output schema | No Django models — Pydantic only |
| Gateway | LLM/compute execution, streaming, tracing | Interchangeable backends |
Pre-release — This project is being extracted from a production system serving real users. The core patterns are battle-tested but the standalone package is under active development.
pip install django-ais# settings.py
INSTALLED_APPS = [
...
'django_ais',
]
DJANGO_AIS = {
'CELERY_QUEUE': 'default',
'EVENT_CHANNEL_LAYER': 'default',
}# your_app/workers.py
from django_ais.workers import BaseWorker
from django_ais.strategies import BaseStrategy
from django_ais.gateways import BaseGateway
class SummarizationStrategy(BaseStrategy):
def compose_context(self, job):
return {"prompt": f"Summarize: {job.payload['text']}"}
def get_output_schema(self):
return SummaryOutput
class SummarizationWorker(BaseWorker):
strategy_class = SummarizationStrategy
gateway_class = BaseGateway# workflows/summarize_pipeline.yaml
name: document_summarizer
version: "1.0"
jobs:
- type: SUMMARIZE
worker: your_app.workers.SummarizationWorker
config:
max_retries: 3
timeout: 300python manage.py import_workflow workflows/summarize_pipeline.yaml- Python 3.11+
- Django 4.2+
- Celery 5.3+
- Redis
- Django Channels (optional, for real-time streaming)
See the docs/ directory for detailed guides:
- Architecture Overview
- Getting Started
- YAML Workflow Reference
- Writing Workers
- Writing Strategies
- Writing Gateways
We welcome contributions! See CONTRIBUTING.md for guidelines.
See ROADMAP.md for the full development plan.
MIT — see LICENSE