Skip to main content

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, and UpdateTool classes, or decorated methods; sync or async
  • Structured output: set output_type to get a validated Pydantic model back
  • Human approval: requires_confirmation = True suspends the run before a tool executes
  • Workflow state: allowed_states hides tools that can't run in the instance's current state
  • Memory: DjangoMemoryCapability keeps conversations per instance in the database
  • Audit trail: DjangoAuditCapability reports 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.Agent too

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.py
  • just lint
  • uv 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)

Source distribution for django-model-agent 2026.1.2
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)

Table of built distributions (wheels) for django-model-agent 2026.1.2
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

2026.1.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page