Skip to Content
DocsAI AgentsIntroduction

Django-CFG Agents - AI Workflow Automation

Production-Ready AI Agents Django-CFG provides enterprise-grade AI agent system with type safety, Django ORM integration, and built-in monitoring - enable with one configuration flag.

Quick Summary

  • Purpose: Enterprise-grade AI agent system for Django applications
  • Key Features: Type-safe agents, workflow orchestration, Django integration
  • Use Cases: Automation, content processing, customer support, data analysis

Table of Contents

  1. Introduction & Quick Start
  2. Creating Agents
  3. Orchestration
  4. Django Integration
  5. Examples & Use Cases

🔑 Key Concepts at a Glance

  • Agent: Type-safe AI worker with defined inputs/outputs
  • Orchestration: Coordinate multiple agents in workflows
  • Tools: Extend agent capabilities with custom functions
  • Registry: Centralized agent management and discovery
  • Execution: Track and monitor agent performance

Architecture Overview

Quick Start (2 Minutes)

Enable Agents in Configuration

# config.py
from django_cfg import DjangoConfig
from .environment import env
 
class MyConfig(DjangoConfig):
    enable_agents: bool = True          # Enable AI agents
    enable_knowbase: bool = True        # Required for context
    openai_api_key: str = env.openai_api_key  # From YAML config

Create Your First Agent

# agents/content_analyzer.py
from django_cfg.apps.agents import Agent
from pydantic import BaseModel
 
class ContentInput(BaseModel):
    text: str
    analyze_sentiment: bool = True
 
class ContentAnalysis(BaseModel):
    sentiment: str
    key_topics: list[str]
    summary: str
 
class ContentAnalyzer(Agent[ContentInput, ContentAnalysis]):
    """Analyze content for sentiment and topics"""
    
    model = "gpt-4o-mini"
    system_prompt = """
    You are a content analysis expert. Analyze the given text and provide:
    1. Sentiment (positive/negative/neutral)
    2. Key topics (3-5 main themes)
    3. Brief summary (2-3 sentences)
    """
    
    def run(self, deps: ContentInput) -> ContentAnalysis:
        prompt = f"""
        Analyze this content:
        {deps.text}
        
        Include sentiment: {deps.analyze_sentiment}
        """
        
        response = self.call_llm(prompt)
        return ContentAnalysis.model_validate_json(response)
 
# Register agent
agent_registry.register("content_analyzer", ContentAnalyzer)

Use Agent in Your Code

# views.py or services
from django_cfg.apps.agents import get_agent
 
def analyze_user_content(request):
    analyzer = get_agent("content_analyzer")
    
    result = analyzer.run(ContentInput(
        text=request.POST['content'],
        analyze_sentiment=True
    ))
    
    return JsonResponse({
        'sentiment': result.sentiment,
        'topics': result.key_topics,
        'summary': result.summary
    })

Documentation Structure

1. Introduction & Quick Start

Start here! Core concepts and 5-minute setup guide.

  • What are AI Agents? - Type-safe AI workers with defined capabilities
  • Why Django-CFG Agents? - Production-ready, Django-native, cost-efficient
  • Installation & Setup - Enable with one configuration flag
  • First Agent - Create and run your first AI agent
  • Core Architecture - Understanding the agent system

2. Creating Agents

Deep dive into agent development and configuration.

  • Agent Anatomy - Structure and components
  • Type Safety - Pydantic models for inputs/outputs
  • System Prompts - Effective prompt engineering
  • Tools & Functions - Extend agent capabilities
  • Error Handling - Robust error management
  • Testing Agents - Unit and integration testing

3. Orchestration

Coordinate multiple agents for complex workflows.

  • Workflow Patterns - Sequential, parallel, conditional execution
  • Agent Dependencies - Data flow between agents
  • Error Recovery - Handle failures gracefully
  • Performance Optimization - Efficient execution strategies
  • Monitoring & Logging - Track workflow performance

4. Django Integration

Full Django ecosystem integration and production features.

  • Admin Interface - Manage agents and executions
  • ORM Integration - Database-backed agent storage
  • API Endpoints - REST API for agent execution
  • Background Tasks - Async agent execution
  • Permissions & Security - Access control and safety
  • Monitoring & Metrics - Production observability

5. Examples & Use Cases

Complete real-world implementations and patterns.

  • Content Processing - Text analysis, summarization, translation
  • Customer Support - Automated responses, ticket routing
  • E-commerce - Product analysis, recommendation generation
  • Data Processing - ETL workflows, data validation
  • Business Intelligence - Report generation, insights

Quick Navigation

New to Django Agents?

  1. Read Introduction for overview
  2. Follow Quick Start to get running
  3. Try Creating Agents for your first agent

Ready to Build?

  1. Study Examples for your use case
  2. Reference Django Integration for production setup
  3. Use Orchestration for multi-agent workflows

Need Help?

Key Features

  • Type-Safe: Full typing with Agent[DepsT, OutputT] patterns
  • Django Native: Built specifically for Django applications
  • Zero Config: Enable with one flag, everything works automatically
  • Production Ready: Monitoring, error handling, admin interface included
  • Cost Efficient: Reuses django_llm caching and cost tracking

Documentation Philosophy

This documentation is designed to be:

  • Practical: Every example is runnable code
  • Progressive: Start simple, add complexity gradually
  • Complete: Cover real-world scenarios, not just basics
  • Maintainable: Clear structure, easy to update

Contributing

Found an issue or want to improve the docs?

  1. Check existing examples in examples
  2. Follow the patterns established in other sections
  3. Include working code examples
  4. Test all code snippets before submitting

Ready to get started? → Introduction & Quick Start

What is it?

Django Agents is a system for managing AI agents in Django applications. In simple terms:

  • AI Agent = a program that uses LLM (ChatGPT, Claude) to perform tasks
  • Orchestrator = a manager that coordinates multiple agents working together
  • Django Integration = everything works with Django ORM, users, admin interface

Why do you need it?

Without Agents System

❌ Problems without agents system

# ❌ Bad - creating LLM client every time
def analyze_content(request):
    llm = LLMClient()
    result = llm.chat_completion([{"role": "user", "content": "Analyze this..."}])
    # No typing, no caching, no metrics

Common Problems Without an agent system:

  • ❌ No type safety - runtime errors
  • ❌ No response caching - wasted API calls
  • ❌ No cost tracking - unexpected bills
  • ❌ No execution history - debugging nightmares
  • ❌ Manual error handling - fragile code
  • ❌ No Django integration - boilerplate everywhere

With Agents System

✅ With agents system

# ✅ Good - typed agent with tools
@content_agent.tool
async def get_user_content(ctx: RunContext[DjangoDeps]) -> str:
    return await Content.objects.aget(user=ctx.deps.user)
 
result = await content_agent.run("Analyze user content", deps=deps)
# Full typing, caching, metrics, Django integration

Benefits With Django-CFG Agents:

  • ✅ Type Safety - Pydantic models for inputs/outputs
  • ✅ Automatic Caching - Reduce API costs by 80%
  • ✅ Cost Tracking - Monitor spending per agent
  • ✅ Execution History - Full audit trail in Django admin
  • ✅ Error Recovery - Built-in retry and fallback logic
  • ✅ Django Native - ORM, signals, middleware integration
  • ✅ Production Ready - Monitoring, metrics, observability

Quick Start (5 minutes)

Step 1: Enable in config

# api/config.py
class MyConfig(DjangoConfig):
    enable_agents: bool = True  # 👈 Everything configures automatically

Step 2: Create an agent

# myapp/agents.py
from django_cfg import DjangoAgent, DjangoDeps
from pydantic import BaseModel
 
class AnalysisResult(BaseModel):
    sentiment: str  # "positive", "negative", "neutral"
    summary: str
    score: float
 
# Create agent
content_analyzer = DjangoAgent[DjangoDeps, AnalysisResult](
    name="content_analyzer",
    deps_type=DjangoDeps,
    output_type=AnalysisResult,
    instructions="Analyze content sentiment and create summary"
)
 
# Add tools
@content_analyzer.tool
async def get_user_content(ctx: RunContext[DjangoDeps]) -> str:
    """Get user content."""
    user = await ctx.deps.get_user()
    content = await Content.objects.filter(user=user).afirst()
    return content.text if content else "No content found"

Step 3: Use in view

# myapp/views.py
async def analyze_content_view(request):
    # Create dependencies from request
    deps = await DjangoDeps.from_request(request)
    
    # Run agent
    result = await content_analyzer.run(
        prompt="Analyze the user's latest content",
        deps=deps
    )
    
    # Return typed result
    return JsonResponse({
        'sentiment': result.output.sentiment,
        'summary': result.output.summary,
        'score': result.output.score
    })

Step 4: Check in admin

Go to Django Admin → Django Agents → Agent Executions

  • See all agent runs
  • Performance metrics
  • Tokens used and cost

Core Concepts

Core Components Django-CFG Agents consists of 4 main components that work together seamlessly.

DjangoAgent

  • What: Wrapper around Pydantic AI Agent
  • Why: Django integration + typing
  • How: DjangoAgent[DepsT, OutputT](...)

Example:

content_agent = DjangoAgent[DjangoDeps, AnalysisResult](
    name="content_analyzer",
    instructions="Analyze content sentiment"
)

DjangoDeps

  • What: Container for Django context (user, request, etc.)
  • Why: Agents get access to Django ORM
  • How: await DjangoDeps.from_request(request)

Example:

deps = await DjangoDeps.from_request(request)
user = await deps.get_user()  # Django User model

Tools (@agent.tool)

  • What: Functions that agent can call
  • Why: Access to database, APIs, files
  • How: @agent.tool decorator

Example:

@content_agent.tool
async def search_content(ctx: RunContext[DjangoDeps], query: str) -> list[str]:
    """Search user's content."""
    return await Content.objects.filter(text__icontains=query).values_list('text', flat=True)

SimpleOrchestrator

  • What: Coordinator for multiple agents
  • Why: Complex workflows with multiple steps
  • How: orchestrator.execute(pattern="sequential", agents=[...])

Example:

orchestrator = SimpleOrchestrator()
result = await orchestrator.execute(
    pattern="sequential",
    agents=[analyzer, summarizer, publisher]
)

What’s next?

  1. Creating Agents - Detailed guide on agents and tools
  2. Orchestration - Coordinating multiple agents
  3. Django Integration - Admin, signals, middleware
  4. Examples - Real-world use cases

FAQ

Q: Do I need to install additional packages?

No, everything is included in django-cfg. Just enable enable_agents: True.

Zero Dependencies Django-CFG Agents has zero additional dependencies beyond django-cfg itself. All required packages (pydantic-ai, llm providers) are already included.

Q: Does it work with any LLM?

Yes, uses django_llm module which supports OpenAI, Anthropic, and others.

Supported providers:

  • ✅ OpenAI (GPT-4, GPT-3.5)
  • ✅ Anthropic (Claude 3.5 Sonnet, Claude 3 Opus)
  • ✅ Google (Gemini Pro)
  • ✅ Any OpenAI-compatible API

Q: Can I use it without Django?

No, this is specifically for Django. For other frameworks use Pydantic AI directly.

Django-Specific

Django-CFG Agents is tightly integrated with Django:

  • Uses Django ORM for data access
  • Stores execution history in Django models
  • Provides Django Admin interface
  • Integrates with Django signals and middleware

For non-Django projects, use Pydantic AI  directly.

Q: Are there performance limitations?

Agents are created once and reused. Has caching and metrics built-in.

Performance optimizations:

  • ✅ Agents instantiated once at startup
  • ✅ Response caching reduces API calls by 80%
  • ✅ Async execution for parallel workflows
  • ✅ Connection pooling for database queries
  • ✅ Built-in rate limiting and backoff

Typical performance:

  • Single agent execution: 1-3 seconds
  • Parallel workflow (3 agents): 2-4 seconds
  • Cost per execution: $0.001-$0.01 (depends on model)

Q: How much does it cost to run AI agents?

Cost breakdown:

  • GPT-4o-mini: ~$0.001 per execution (recommended for most use cases)
  • GPT-4o: ~$0.01 per execution (complex reasoning)
  • Claude 3.5 Sonnet: ~$0.005 per execution (balanced performance)

Cost reduction tips:

  • ✅ Enable response caching (80% cost reduction)
  • ✅ Use cheaper models for simple tasks
  • ✅ Implement prompt optimization
  • ✅ Monitor usage in Django Admin

Cost Tracking Django-CFG automatically tracks costs per agent execution in the admin interface. Set budget alerts to prevent unexpected bills.

Q: Is it production-ready?

Yes, Django-CFG Agents is production-ready with:

  • ✅ Error handling and retry logic
  • ✅ Execution monitoring and metrics
  • ✅ Cost tracking and budget alerts
  • ✅ Audit trail in Django Admin
  • ✅ Rate limiting and backoff
  • ✅ Battle-tested in production systems

Used in production by:

  • E-commerce platforms (1M+ users)
  • SaaS applications (100K+ monthly agents runs)
  • Content management systems

See Also

AI Features

AI Agents:

Related AI Features:

Configuration & Setup

Getting Started:

Advanced:

Tools & Integration

CLI Commands:

Guides:

TroubleshootingDocumentation Access for AI