Skip to content

django-ag-ui

A Django ↔ Pydantic-AI ↔ AG-UI integration. It turns a Pydantic-AI agent into a streaming Django endpoint that any AG-UI client can talk to, and gives you a typed, server-side tool registry with per-tool risk metadata.

What it is

django-ag-ui provides the server half of an AG-UI conversation:

  • A tool registry (ToolRegistry, the @tool decorator) with destructive= and category= metadata. build_input_schema derives a JSON Schema from each tool's signature and stamps an x-destructive extension when the tool is destructive.
  • An async Django view (DjangoAGUIView) that wraps Pydantic-AI's pydantic_ai.ui.ag_ui.AGUIAdapter, parses the posted RunAgentInput, builds a per-request Agent, and returns a StreamingHttpResponse of AG-UI events (Server-Sent Events).
  • An audit boundary: the AuditLogger Protocol with NullAuditLogger (default) and LoggingAuditLogger implementations.
  • Authentication hooks on the view: require_authenticated=True fails closed (401) for anonymous requests, and a get_user(request) callable establishes the user tools act as.
  • A skill catalog (SkillRegistry) of pre-defined prompts, served at <prefix>skills/ for the web component.
  • A tool metadata catalog (ToolsView), served at <prefix>tools/ via get_urls(view, tools=registry), giving the web component friendly card labels for server-side tools.
  • Optional, pluggable conversation persistence (ConversationStore), off by default.
  • An optional drf-mcp bridge that exposes a djangorestframework-mcp-server registry to the agent in-process.

Where it sits

django-ag-ui is Phase 1 of a three-package design — the Django side of the bridge, with no admin specifics:

Package Role
django-ag-ui (this package) Django ↔ Pydantic-AI ↔ AG-UI bridge for any Django project. Async view, tool registry, audit + persistence protocols. No admin code, no frontend bundle.
@artooi/ag-ui-web-component Framework-free <ag-ui-chat> Web Component for any frontend. Wraps @ag-ui/client, drives the DOM, and renders the inline confirmation card that gates x-destructive tools client-side.
django-admin-agent Depends on both. Ships the admin-specific server tools, the admin-aware frontend handlers, and the admin-site plumbing.

The wire between them stays vanilla AG-UI. This package never re-implements the AG-UI wire types; they come from pydantic-ai-slim[ag-ui].

How a turn flows

Browser (AG-UI client)
   │  POST RunAgentInput { messages, tools, context, state }
   ▼
DjangoAGUIView.__call__               (async)
   │  build per-request Pydantic-AI Agent from the ToolRegistry
   ▼
AGUIAdapter (pydantic-ai)
   │  merges FE-declared tools, runs the agent, encodes events
   ▼
StreamingHttpResponse  ──SSE──▶  RUN_STARTED, TEXT_MESSAGE_*,
                                 TOOL_CALL_*, RUN_FINISHED, …

Server-side tools run in-process; tools declared by the client in RunAgentInput.tools execute in the browser. Conversation state lives in the posted message history by default, so the server stays stateless and multi-worker deployments are safe.

Next steps

  • Installation — pip install, the ASGI requirement, the [drf-mcp] extra.
  • Quickstart — register tools and mount the view.
  • Configuration — every DJANGO_AG_UI settings key.
  • Key concepts — registry, audit, streaming, persistence, the drf-mcp bridge.
  • API reference — autodoc of the public surface.