API reference¶

The public Python surface re-exported from django_admin_agent.

Package entry points¶

get_urls ¶

get_urls(
    prefix: str = "admin-agent/",
    *,
    registry: ToolRegistry | None = None,
    **view_kwargs: Any,
) -> list[URLPattern]

Return URL patterns mounting the admin agent's AG-UI endpoint.

Builds a :class:~django_ag_ui.DjangoAGUIView over the default server-side admin tool registry (or a registry you pass) and mounts it at <prefix>agent/ named django_admin_agent_endpoint — the name the sidebar reverses. Also mounts the server-tool label catalog at <prefix>agent/tools/ (named django_admin_agent_tools) which the sidebar passes to the Web Component as data-tools-url. Extra keyword arguments (model, instructions, audit_logger, csrf_exempt) pass through to the view.

Include the result from your project's root URLconf::

urlpatterns = [
    path("admin/", admin.site.urls),
    *get_urls(),
]

build_default_registry ¶

build_default_registry() -> ToolRegistry

Build a fresh registry with the default server-side admin tools.

register_admin_tools ¶

register_admin_tools(registry: ToolRegistry) -> None

Register the full server-side admin tool set on registry.

Combines the read-only shell.* (ORM) and introspect.* (Django + admin introspection) tools.

register_shell_tools ¶

register_shell_tools(registry: ToolRegistry) -> None

Register the read-only ORM/shell tool set on registry.

register_introspect_tools ¶

register_introspect_tools(registry: ToolRegistry) -> None

Register the read-only Django-introspection tool set on registry.

Settings¶

AdminAgentSettings `dataclass` ¶

Snapshot of the user-configurable DJANGO_ADMIN_AGENT settings.

Built fresh on every read so test overrides take effect immediately. The agent model itself is configured separately via django-ag-ui's DJANGO_AG_UI["MODEL"].

title `instance-attribute` ¶

title: str

Header text shown on the sidebar chat panel.

auto_confirm `instance-attribute` ¶

auto_confirm: bool

When True, destructive UI tools run without a confirmation modal. Passed to the Web Component as autoConfirm.

endpoint_url_name `instance-attribute` ¶

endpoint_url_name: str

URL name to reverse for the AG-UI endpoint. Mount it with :func:django_admin_agent.get_urls (which names it django_admin_agent_endpoint).

tool_display `instance-attribute` ¶

tool_display: str

How much detail tool-call cards show: "minimal", "compact", or "full". Passed to the Web Component as the data-tool-display attribute; defaults to "compact" for a dense admin sidebar.

skills `instance-attribute` ¶

skills: list[dict[str, Any]] | None

Optional override for the skill catalog (client Skill dicts). None uses the built-in admin catalog (:func:build_skills).

theme `instance-attribute` ¶

theme: str | None

Web Component theme: "light" / "dark" / "auto" / "code". None leaves the component default (light).

density `instance-attribute` ¶

density: str | None

"comfortable" / "compact". None leaves the default.

placement `instance-attribute` ¶

placement: str | None

"bottom-left" / "side" / "full" / "embedded" (or unset for the default floating bottom-right).

text_animation `instance-attribute` ¶

text_animation: str | None

Incoming-text animation: "none" / "fade" / "word". None leaves the default (none).

get_settings ¶

get_settings() -> AdminAgentSettings

Read the active DJANGO_ADMIN_AGENT settings dict.

Admin wiring¶

build_sidebar_context ¶

build_sidebar_context() -> dict[str, Any]

Build the context the sidebar template needs.

Reverses the AG-UI endpoint URL, resolves the bootstrap module's static URL, reads the title / auto-confirm flag from settings, and resolves the admin index URL so the frontend nav.* tools can build changelist / changeform URLs without reversing named routes in the browser. Shared by the {% django_admin_agent_sidebar %} template tag and the :class:~django_admin_agent.admin.sidebar_admin_site.SidebarAdminSite each_context hook.

build_route_map ¶

build_route_map() -> list[dict[str, Any]]

Build the agent's navigable-route manifest from the admin registry.

One changelist route (and one add route, when available) per registered model, shaped for the Web Component's routeMap — {id, path, title, group}. The agent calls list_routes to discover destinations and navigate_to_route to jump to one, instead of guessing admin URLs.

build_skills ¶

build_skills() -> list[dict[str, Any]]

The built-in admin skill catalog (client Skill dicts).

SidebarAdminSite ¶

Bases: AdminSite

A drop-in AdminSite that exposes the sidebar config to every page.

Adds django_admin_agent (the sidebar context) to each_context so a base template can render the chat without the template tag. Using the {% django_admin_agent_sidebar %} tag in admin/base_site.html is the more common path and does not require swapping the admin site.

Server-side tools¶

`shell.*`¶

query_model ¶

query_model(
    app_label: str,
    model: str,
    filter: dict[str, Any] | None = None,
    exclude: dict[str, Any] | None = None,
    order_by: list[str] | None = None,
    select_related: list[str] | None = None,
    prefetch_related: list[str] | None = None,
    fields: list[str] | None = None,
    limit: int = 50,
    offset: int = 0,
) -> list[dict[str, Any]]

Query a Django model and return matching rows as JSON-safe dicts.

filter and exclude accept ORM lookup kwargs (e.g. {"email__icontains": "@foo"}). fields projects via .values(); if omitted, every concrete field is returned. limit is hard-capped at 1000 to keep responses bounded.

get_model_instance ¶

get_model_instance(
    app_label: str,
    model: str,
    pk: Any,
    select_related: list[str] | None = None,
    fields: list[str] | None = None,
) -> dict[str, Any] | None

Fetch a single row by primary key. Returns None when not found.

count_model ¶

count_model(
    app_label: str,
    model: str,
    filter: dict[str, Any] | None = None,
    exclude: dict[str, Any] | None = None,
) -> int

Return the row count for a model, optionally filtered.

inspect_model_schema ¶

inspect_model_schema(app_label: str, model: str) -> dict[str, Any]

Return a JSON-safe description of a model's schema.

Includes concrete fields with types, nullability, relations, indexes, db_table, and Meta ordering — a good first step before writing queries.

`introspect.*`¶

list_installed_apps ¶

list_installed_apps() -> list[dict[str, Any]]

Return the configured Django apps with labels, names, and model counts.

list_models ¶

list_models(app_label: str | None = None) -> list[dict[str, Any]]

List installed Django models, optionally filtered to one app.

Each entry carries the app label, model name, DB table, and Meta-derived flags. Use inspect_model_schema for the full field-level shape.

list_urls ¶

list_urls(prefix: str | None = None) -> list[dict[str, Any]]

Walk the root URL configuration and return every registered route.

Each entry includes the rendered pattern, view identifier, and URL name. prefix filters by string-containment against the pattern.

list_signals ¶

list_signals() -> list[dict[str, Any]]

Enumerate Django's built-in signals and their connected receivers.

Returns one row per signal with the count and identifier of each connected receiver. Custom third-party signals are not enumerated — there is no central registry for them.

get_settings_summary ¶

get_settings_summary() -> dict[str, Any]

Return a curated, JSON-safe subset of Django settings.

Sensitive keys (SECRET_KEY, DB passwords, raw OPTIONS) are excluded or redacted, so the result is safe to surface to an agent.

list_admin_models ¶

list_admin_models() -> list[dict[str, Any]]

List every model registered with the default admin site.

Each entry carries the model's admin metadata (list_display, list_filter, search_fields) and the reverse-resolved admin URLs (changelist + add) so the agent can navigate without guessing URL shapes. Works for both vanilla ModelAdmin and subclasses (Unfold) because every attribute is read defensively.

inspect_modeladmin ¶

inspect_modeladmin(app_label: str, model: str) -> dict[str, Any]

Describe the ModelAdmin registered for a model.

Reads options via getattr so it transparently surfaces both standard Django options and the additive attributes that subclasses (Unfold) add. Raises LookupError if the model is not registered.