Building a Pluggable AI Agent System with Django

The Problem with Monolithic AI Integrations

Most SaaS boilerplates hard-wire a single AI framework into their codebase. When you want to switch from LangChain to PydanticAI, or add a custom inference pipeline, you're looking at a full rewrite.

Our Approach: Framework-Agnostic Boundaries

HyperSaaS introduces a simple but powerful pattern:

1. AgentMessage — a framework-agnostic dataclass that all handlers produce
2. BaseAgentHandler — an abstract base class defining invoke() and astream()
3. Plain Python tools — no @tool decorators, no framework imports

Each handler converts its native output (LangChain messages, PydanticAI results) into AgentMessage at the boundary. The service layer never imports any AI framework.

Adding a New Framework

To add support for a new AI framework:

1. Create a new handler in chat/handlers/your_framework/
2. Implement BaseAgentHandler.invoke() and astream()
3. Register it in the handler factory
4. Set agent_framework on the chat session

The tools, service layer, and frontend all work without changes.

Why This Matters

Your AI stack will evolve. New frameworks emerge constantly. By keeping a clean boundary between your business logic and your AI runtime, you can adopt new tools without rewriting your application.