django-ai-assistant: tool calling and RAG inside a Django app

What django-ai-assistant solves for a Django codebase

The README states the goal plainly: "Let AI Assistants call methods from Django's side and do anything your users need!" That is the whole pitch. Most Django teams that add an LLM end up writing the same three things by hand: a place to keep conversation state, a JSON schema describing the functions the model may call, and a dispatcher that maps a model's tool call back to a Python function with the requesting user attached. django-ai-assistant packages all three as a reusable Django app.

The intended reader is a backend Django developer, not a data scientist. The project's classifiers list Django 4.2, 5.0 and 5.1 and Python 3.10 through 3.13, so it targets the versions a normal production project already runs. Tool definitions live next to the code that owns the data, which means the assistant inherits Django's permission checks instead of bypassing them through a separate service.

It is a poor fit if you only need a chat box that answers questions from a static document set. The tool-calling machinery is the point, and a plain retrieval pipeline over a vector store would be less code.

How the assistant, the model and your Django code connect

The dependency list in pyproject.toml tells you the architecture before you open a file. Django and django-ninja provide the web layer, pydantic validates the tool arguments, and langchain, langgraph and langchain-openai sit underneath as the agent runtime. The provider packages are optional extras, so an install without them gives you the Django app but no model client.

According to the repository layout, the app package is django_ai_assistant/, with tests/ beside it and an example/ directory containing several small Django projects: issue_tracker, movies, rag, tour_guide and weather. Those names map to the demo flows the documentation describes, and they are the fastest way to see how a tool is registered and how a thread is persisted.

The data flow is the familiar LangGraph one wrapped in Django conventions. A request arrives at a view, the view resolves the assistant class, the assistant builds the message list plus the tool schemas, the model returns either text or a tool call, and the tool call is dispatched to a Python method. Conversation history is stored through Django models rather than in process memory, which is what makes the assistant usable behind multiple workers.

One consequence worth naming: because langgraph is a hard dependency, the assistant is a graph execution engine, not a single prompt-response call. That buys you multi-step tool use and costs you a heavier dependency tree than a thin OpenAI client would.

Installing django-ai-assistant and running a first assistant

The project is distributed on PyPI under the name django-ai-assistant and managed with Poetry in its own repository. The extras are defined in pyproject.toml, so you pick a provider at install time. The openai extra pulls in langchain-openai. The repository's .env.example holds the only credential the basic setup needs, and it is a single line.

OPENAI_API_KEY=your-key-here

Add the app to INSTALLED_APPS and run Django's migration command so the assistant tables are created. The documentation at vintasoftware.github.io/django-ai-assistant covers the settings module and the exact app label, so copy the label from there rather than guessing it.

Assistants are declared as Python classes with a name and an instruction string, and tools are methods on that class. The README does not inline a full class definition, so the authoritative example is the example/ directory: weather/ for a small tool-calling assistant and issue_tracker/ for one that touches models. Read one of those before writing your own, because the method signature is what the model sees as the tool schema.

Finally, the frontend/ directory and the example projects show the streaming endpoint. If you are not building a custom UI, the example's JavaScript is the reference implementation for consuming the stream.

Where django-ai-assistant gets in your way

The classifier in pyproject.toml reads "Development Status :: 3 - Alpha". Take that literally. Three releases landed between 2026-01-26 and 2026-03-23, and the version reached 0.4.0 in that window, so internal APIs can move between minor versions. If your project pins dependencies tightly, budget time for upgrades rather than assuming a patch bump.

Provider lock-in is narrower than the extras list suggests. langchain-openai, langchain-anthropic and langchain-google-genai are all optional, but the package description in pyproject.toml still says "Django app to integrate with OpenAI Assistants API", and the README's only environment example is OPENAI_API_KEY. The documentation is the place to check whether a non-OpenAI provider is a first-class path or a thin adapter.

Cost and latency are the other failure mode. Every tool round trip is a model call, so an assistant with five tools can issue several calls per user message. Nothing in the repository caps that loop for you. The README does not document rate limiting, budget guards or a maximum tool-call depth, so if you deploy this to real users you own that control yourself.

Finally, if your team has no Django investment, the app's value collapses. The tool dispatcher is useful precisely because it can reach your ORM and your permission classes. In a FastAPI or Flask service you would be adopting Django to get the assistant.

django-ai-assistant compared with calling LangChain directly

The honest alternative is not another Django package. It is using langchain and langgraph on their own, which is exactly what django-ai-assistant does underneath. The difference is what the wrapper adds: a Django app with migrations and models for persisted threads, a class-based way to declare assistants and tools, and a django-ninja layer for the HTTP endpoint.

If you call LangChain directly, you write the persistence yourself. That is more code, but it also means you choose the storage schema, the retention policy and the serialization format, and you are not coupled to another project's release cadence on top of LangChain's. Given that django-ai-assistant is at 0.4.0 and LangChain itself moves quickly, that stacking is a real risk to weigh.

The trade favors django-ai-assistant when your assistant needs to call Django model methods with the current request's user in scope. Reimplementing that dispatch, with the permission checks and the argument validation, is the tedious part, and it is the part this project has already written. If your assistant only reads from a vector store and never touches your database, the wrapper earns less.

Maintenance, licensing and what an upgrade costs

The repository is not archived. The last push was on 2026-03-23, roughly six months before today, so the project is between active bursts rather than abandoned, and the release history shows a steady cadence through the first quarter of 2026. The maintainer is Vinta Software, which states in the README that it offers commercial support at [email protected], so there is a paid path if you need one.

The licence is MIT, declared in pyproject.toml and present as LICENSE.txt at the repository root. MIT is permissive: you can use the code in a closed product, and you must keep the copyright notice. That is a summary of the licence text, not legal advice, and your own counsel should review how it interacts with the licences of the optional provider packages you install.

Upgrade cost is driven by the dependency chain. A bump of langchain or langgraph can change behaviour without any change in django-ai-assistant itself, and the version ranges in pyproject.toml are the contract you are accepting. The changelog is published at vintasoftware.github.io/django-ai-assistant/latest/changelog, and the repository keeps a CHANGELOG.md, so read the entries between 0.3.0 and 0.4.0 before you upgrade a running deployment.

Editorial conclusion

Adopt django-ai-assistant if your team already runs Django and wants the assistant to call existing model methods and views instead of rebuilding that plumbing. Do not adopt it if you need a stable API surface: pyproject.toml still classifies the project as Development Status 3 - Alpha, and the 0.4.0 release on 2026-03-23 is the fourth minor line in under a year. Before writing code, verify that the LangChain and LangGraph versions your project already pins are compatible with the ranges in pyproject.toml, and read the changelog page linked from the repository for the migration notes between 0.3.0 and 0.4.0.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vintasoftware/django-ai-assistant on GitHub