Building a Pluggable AI Agent System with Django

Updated October 2026: HyperSaaS ships one agent framework, LangGraph. The boundary this post describes is what keeps adding another a contained change.

The Problem with Monolithic AI Integrations

Most SaaS boilerplates hard-wire a single AI framework into their codebase, and its message types end up in your views, your database code and your tests. When you want to move to another framework, or add your own inference pipeline, you're looking at a rewrite.

Our Approach: Framework-Agnostic Boundaries

HyperSaaS keeps the framework behind three things:

1. AgentMessage: a framework-agnostic dataclass that every handler returns.
2. BaseAgentHandler: the abstract base class every handler implements: invoke(), astream(), and stream() for streamed replies.
3. Plain Python tools: ordinary functions with no framework imports, which a handler wraps for its runtime.

The LangGraph handler converts LangChain's messages into AgentMessage at the boundary, so the code that streams replies to the browser, saves them and counts their usage doesn't depend on LangGraph. A chat set to none skips the agent and calls the model directly.

Adding a New Framework

To run chats on another framework, such as PydanticAI or the OpenAI Agents SDK:

1. Create a handler in chat/handlers/your_framework/.
2. Implement invoke() and astream(), and stream() if replies should stream.
3. Wrap the plain tools for your framework, and register the handler in the factory.
4. Add it to the agent_framework choices.

Saving replies, counting usage, streaming and the frontend 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.