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
uv add django-model-agent
Or with pip:
pip install django-model-agent
Requires Python 3.13+, Django 5.2+, and pydantic-ai 2.22+.
Quick Start
Declare which fields the agent can see, give it instructions, and run it against an instance:
from django_model_agent import ModelAgent
class RestaurantAgent(ModelAgent):
model = Restaurant
fields = ["name", "address", "hours", "neighborhood"]
ai_model = "openai:gpt-4o"
_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]
restaurant = await Restaurant.objects.aget(pk=123)
result = await RestaurantAgent(restaurant).run("Are we open on Christmas Day?")
print(result.output)
The field schema and the instance's current values reach the model as
instructions, re-read on every request, so they're never stale. run_sync(),
run_stream(), and run_stream_events() are there too.
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)
Overrides
Most class attributes can be overridden per agent:
agent = RestaurantAgent(
restaurant,
instructions="Focus only on hours of operation.",
ai_model="anthropic:claude-sonnet-4-20250514",
output_type=HoursAnswer,
)
When no model is set anywhere, the PYDANTIC_AI_MODEL environment variable is
used.
Features
- Declarative model binding: choose which Django model fields the agent can see
- Field sets: named groups of fields for role-based exposure
- Tools:
ModelTool,ReadOnlyTool, andUpdateToolclasses, or decorated methods; sync or async - Structured output: set
output_typeto get a validated Pydantic model back - Human approval:
requires_confirmation = Truesuspends the run before a tool executes - Workflow state:
allowed_stateshides tools that can't run in the instance's current state - Memory:
DjangoMemoryCapabilitykeeps conversations per instance in the database - Audit trail:
DjangoAuditCapabilityreports field changes, tool calls, and token usage - Usage limits: cap requests, tool calls, and tokens per run, agent, or project
- Composable: everything is a pydantic-ai capability, usable with a plain
pydantic_ai.Agenttoo
Init Parameters
| Parameter | Description |
|---|---|
instance |
The Django model instance to operate on |
system_prompt |
Override the class-level system prompts |
instructions |
Override the class-level instructions |
field_set |
Name of a field set to use for schema generation |
ai_model |
The pydantic-ai model to use, e.g. "openai:gpt-4o" |
output_type |
Structured output type for this agent |
usage_limits |
UsageLimits applied to every run |
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 |
ai_model |
Default pydantic-ai model |
output_type |
Default structured output type (None = plain text) |
usage_limits |
Default UsageLimits |
_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 |
Override get_extra_capabilities() to add capabilities such as memory, auditing,
or any pydantic-ai capability.
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.2
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.2.tar.gz | 53.9 kB | Without provenance | Details for django_model_agent-2026.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_model_agent-2026.1.2-py3-none-any.whl | Python 3 | none | any | Details for django_model_agent-2026.1.2-py3-none-any.whl |
Total release size: 89.6 kB
Release files / django_model_agent-2026.1.2.tar.gz
| Download URL | django_model_agent-2026.1.2.tar.gz |
|---|---|
| Size | 53.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
192d3eab365090beff3a3196011071ada571142c2b11521299389fb4152f05d6
|
|
BLAKE2b-256 checksum How to use checksums |
dd73dd7470eca498ba3216dfe65b22a53d6b735cc7001cb68966cfd00ea5d491
|
| 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.2-py3-none-any.whl
| Download URL | django_model_agent-2026.1.2-py3-none-any.whl |
|---|---|
| Size | 35.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
74b3c7c9335b77cbc8b2e982546aa6d90f402053f1bbdc029843bb7d532c9c53
|
|
BLAKE2b-256 checksum How to use checksums |
f8b7be2b44ba9d2b1b6a6e593b80a16c5de462c79f693b810508e33dc877f71e
|
| 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.2
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.