Django Model Agent
Note: This project is experimental and the API will change.
A Django Ninja-style abstraction for binding Django models to Pydantic AI Agents.
Documentation · Getting started · Cookbook · Examples
This library provides a declarative way to create AI agents that understand and operate on Django model instances, similar to how Django Ninja's ModelSchema provides a declarative way to serialize models.
Installation
This package is not yet published on PyPI. Install directly from GitHub:
uv add git+https://github.com/jefftriplett/django-model-agent
Or with pip:
pip install git+https://github.com/jefftriplett/django-model-agent
Once published on PyPI:
uv add django-model-agent
Or with pip:
pip install django-model-agent
Quick Start
Today, the stable part of the package is the Django model/schema/tool abstraction layer. To execute prompts, subclass ModelAgent and implement build_agent() for your own pydantic-ai integration.
Class Attribute Style
from django_model_agent import ModelAgent, ModelTool
class RestaurantAgent(ModelAgent):
model = Restaurant
fields = ["name", "address", "hours", "neighborhood"]
_system_prompts = """
You are an assistant that helps reason about restaurant information.
Use the provided model fields as your source of truth.
"""
tools = [UpdateHoursTool, FlagForReviewTool]
Decorator Style (Pydantic-AI inspired)
class RestaurantAgent(ModelAgent):
model = Restaurant
fields = ["name", "address", "hours"]
@ModelAgent.system_prompt
def context_prompt(self) -> str:
return "You help with restaurant information."
@ModelAgent.instructions
def dynamic_instructions(self) -> str:
return f"Current restaurant: {self.instance.name}"
@ModelAgent.tool
def get_hours(self) -> str:
"""Get the restaurant hours."""
return str(self.instance.hours)
Usage
Inspect the schema, prompts, and tools:
restaurant = Restaurant.objects.get(pk=123)
agent = RestaurantAgent(restaurant)
schema = agent.schema
system_prompt = agent.get_system_prompts()
instructions = agent.get_instructions()
tools = agent.get_tools()
# Override prompts at init time
agent = RestaurantAgent(
restaurant,
system_prompt="You are a concise assistant.",
instructions="Focus only on hours of operation.",
)
Wire in your own runtime:
from pydantic_ai import Agent
class RunnableRestaurantAgent(RestaurantAgent):
def build_agent(self) -> Agent:
return Agent(
model=self.schema,
system_prompt=self.get_system_prompts(),
instructions=self.get_instructions(),
tools=self.get_tools(),
)
Features
- Declarative model binding: Define which Django model fields your agent can access
- Field sets: Create named groups of fields for role-based exposure
- Multiple prompt sources: Combine class-level prompts with decorated methods
- Tool registration: Register tools via class attributes or decorators
- Template support: Use Django templates for dynamic instructions
- Automatic schema generation: Pydantic schemas are generated from Django models
Init Parameters
| Parameter | Description |
|---|---|
instance |
The Django model instance to operate on |
system_prompt |
Override or extend the class-level system prompts |
instructions |
Override or extend the class-level instructions |
field_set |
Name of a field set to use for schema generation |
Class Attributes
| Attribute | Description |
|---|---|
model |
The Django model class this agent operates on |
fields |
List of field names to expose to the agent (None = all fields) |
exclude |
List of field names to exclude from the schema |
_system_prompts |
System prompt string or list of strings for the agent |
_instructions |
Instructions string or list of strings for the agent |
_instructions_template |
Path to a Django template for instructions |
tools |
List of tool classes available to the agent |
_field_sets |
Named groups of fields for role-based exposure |
Decorators
| Decorator | Description |
|---|---|
@ModelAgent.system_prompt |
Register a method as a system prompt provider |
@ModelAgent.instructions |
Register a method as an instructions provider |
@ModelAgent.tool |
Register a method as a tool available to the agent |
Creating Tools
from django_model_agent.tools import UpdateTool, ToolResult
class UpdateHoursTool(UpdateTool):
name = "update_hours"
description = "Update the operating hours"
def update(self, *, new_hours: str) -> None:
self.instance.hours = new_hours
# save() is called automatically by UpdateTool
Or for read-only tools:
from django_model_agent.tools import ReadOnlyTool
class GetHoursTool(ReadOnlyTool):
name = "get_hours"
description = "Get the current operating hours"
def read(self, **kwargs) -> dict:
return {"hours": self.instance.hours}
Local Development
Python 3.13+ is currently required, including free-threaded (t) builds.
uv sync --group dev
just test
just lint
Useful commands:
just test tests/test_model_agent.pyjust lintuv build
License
PolyForm Noncommercial License 1.0.0
Metadata
Release files for django-model-agent 2026.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_model_agent-2026.1.1.tar.gz | 54.8 kB | Without provenance | Details for django_model_agent-2026.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_model_agent-2026.1.1-py3-none-any.whl | Python 3 | none | any | Details for django_model_agent-2026.1.1-py3-none-any.whl |
Total release size: 91.7 kB
Release files / django_model_agent-2026.1.1.tar.gz
| Download URL | django_model_agent-2026.1.1.tar.gz |
|---|---|
| Size | 54.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
417a48f6358b7bcc9e1d0ee14b75d515746ed6d5f8fd64c9a9f7ce03b54cb1c5
|
|
BLAKE2b-256 checksum How to use checksums |
4315a7065c1ecd7164dffe3a4b84d233e021a5d43a9e5c8cd65bf553e7759dbd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.0
|
Release files / django_model_agent-2026.1.1-py3-none-any.whl
| Download URL | django_model_agent-2026.1.1-py3-none-any.whl |
|---|---|
| Size | 36.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
38f8866540e60c9c8a5fe275984c9eaacc253c5158aab5d2e3cc51045fa5f66d
|
|
BLAKE2b-256 checksum How to use checksums |
d8b2672b75d8cc387ec470dbc3d2a86b30c69d1fbab9a651bf6d0178320bd716
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.0
|
Security for django-model-agent 2026.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.