django-pydantic-agent 0.3.0

Settings-agnostic Django agent-host substrate for Pydantic-AI: config in, built agent out.

django-pydantic-agent

The settings-agnostic agent-host substrate shared by Django's Pydantic-AI transports.

It takes an AgentConfig in and returns a built pydantic_ai.Agent — with composed toolsets, audit, and user resolution — and reads no Django settings of its own. Each transport owns its settings namespace, builds an AgentConfig, and hands it down:

• django-ag-ui — AG-UI over SSE for a browser client.
• django-a2a — agent-to-agent (planned).

pip install django-pydantic-agent

Most projects install a transport and get this as a dependency. Reach for it directly when you are building a transport, sharing agent construction between two of them, or embedding an agent with no HTTP surface at all.

from django_pydantic_agent import AgentConfig, ToolRegistry, build_agent, tool

registry = ToolRegistry()


@tool(registry)
def list_orders(status: str) -> list[dict]:
    """List orders with the given status."""
    ...


agent = build_agent(registry, AgentConfig(model="anthropic:claude-sonnet-4-5"))

What it provides

• Agent construction — AgentConfig → build_agent, model and provider resolution, and an escape hatch to replace construction entirely.
• A tool registry — @tool with destructive / category / confirm / summary metadata, and JSON Schema derived from the signature.
• Storage contracts — ConversationStore / AttachmentStore protocols, reference implementations, and Django models in contrib.store.
• Policy — an audit trail over every tool call, and a server-side approval gate for destructive tools. Both off by default.
• Integrations — optional bridges exposing djangorestframework-services specs or a drf-mcp-server registry as agent tools, in process.

Optional extras: [drf-mcp] (bridge a drf-mcp-server registry as a toolset), [spec-tools] (drf-services specs as agent tools), [harness] (pydantic-ai-harness capabilities), and the provider extras [anthropic] / [openai] / [google].

Documentation

https://artui.github.io/django-pydantic-agent/

• Concepts — how a config becomes an agent, and what belongs here versus in a transport.
• Tools — registering tools and what the metadata does.
• Storage — the store contracts, owner scoping, and the reference models.
• Policy — audit and the destructive-tool gate.
• Integrations — DRF specs and MCP tools as agent tools.
• Reference — the full public API.