Management Commands

django-agents provides powerful Django management commands for agent lifecycle management.

Overview

All commands follow Django’s management command conventions and can be run using:

python manage.py <command> [options]

Agent Discovery & Listing

list_agents

Lists all registered agents in your Django project.

python manage.py list_agents [--verbose] [--app APP] [--enabled-only] [--format FORMAT]

Options:

--verbose - Show detailed agent information
--app APP - Filter by specific Django app
--enabled-only - Show only enabled agents
--format {table,json,list} - Output format

Examples:

# Basic listing
python manage.py list_agents

# Verbose output
python manage.py list_agents --verbose

# JSON output
python manage.py list_agents --format json

# Filter by app
python manage.py list_agents --app myapp

Agent Execution

run_agent

Execute a specific agent with provided context.

python manage.py run_agent AGENT_NAME [--context JSON] [--context-file FILE]

Examples:

# Run with inline context
python manage.py run_agent email_notification --context '{
    "recipient": "user@example.com",
    "subject": "Hello",
    "message": "Test message"
}'

# Run with context file
python manage.py run_agent data_processor --context-file input.json

# Async execution
python manage.py run_agent report_generator --async

Agent Creation

create_agent

Scaffold a new agent in an existing Django app.

python manage.py create_agent AGENT_NAME APP_NAME [--template TYPE]

Templates:

base - Basic synchronous agent
async - Asynchronous agent with queue support
workflow - Multi-step workflow orchestrator
api - REST API integration agent
data - Data processing agent

Examples:

# Create basic agent
python manage.py create_agent EmailNotification myapp

# Create async agent
python manage.py create_agent ReportGen myapp --template async

# Create with description
python manage.py create_agent DataProcessor myapp \\
    --description "Process CSV files"

# Skip test generation
python manage.py create_agent QuickAgent myapp --no-tests

Monitoring & Health

agent_stats

Display execution statistics for all agents.

python manage.py agent_stats [--agent NAME] [--format FORMAT] [--sort-by FIELD]

Sort Options:

name - Sort alphabetically by agent name
executions - Sort by execution count
last_run - Sort by last execution time
app - Sort by Django app

Examples:

# Show all statistics
python manage.py agent_stats

# Stats for specific agent
python manage.py agent_stats --agent email_notification

# Sort by execution count
python manage.py agent_stats --sort-by executions

# Detailed format
python manage.py agent_stats --format detailed

check_agents_health

Perform comprehensive health checks on all agents.

python manage.py check_agents_health [--verbose] [--test-execution]

Checks Performed:

Agent instantiation
Required attributes (name, description, version)
Execute method existence
Context validation
Enabled status
Optional: Test execution with empty context

Examples:

# Basic health check
python manage.py check_agents_health

# Verbose output
python manage.py check_agents_health --verbose

# Include execution tests
python manage.py check_agents_health --test-execution

# Check specific app
python manage.py check_agents_health --app myapp

Code Quality & Auditing

agent-audit

Run comprehensive project audit.

python manage.py agent-audit [--format FORMAT] [--output FILE]

Audit Categories:

Codebase structure and quality
Test coverage
Django settings security
Production readiness
Database configuration
Server setup

Examples:

# Text report
python manage.py agent-audit

# Markdown report
python manage.py agent-audit --format markdown

# Save to file
python manage.py agent-audit --format html --output audit.html

AI Assistant Integration

generate_context

Generate context files for AI coding assistants (Claude Code, GitHub Copilot, etc.).

python manage.py generate_context [--format FORMAT] [--include-stats]

Generated Information:

Project structure
Available agents and capabilities
Django apps overview
Management commands reference
Coding conventions and patterns
Agent base classes

Examples:

# Generate JSON context
python manage.py generate_context

# Generate YAML context
python manage.py generate_context --format yaml

# Include execution statistics
python manage.py generate_context --include-stats

Project Scaffolding

startproject

Create a new Django project with django-agents pre-configured.

django-agents startproject PROJECT_NAME [directory]

This creates a Django project with:

django-agents in INSTALLED_APPS
Pre-configured settings
Example agents
Management command aliases

startapp

Create a new Django app with agent scaffolding.

python manage.py startapp APP_NAME [directory]

This creates a Django app with:

Empty agents.py file
Agent test structure
Documentation templates

Command Chaining

You can chain commands for complete workflows:

# Create, check, and run
python manage.py create_agent MyAgent myapp && \\
python manage.py check_agents_health --app myapp && \\
python manage.py run_agent my_agent --context '{}'

# Audit and generate report
python manage.py agent-audit --format markdown > audit.md && \\
python manage.py agent_stats --format json > stats.json

Integration with CI/CD

Example GitHub Actions workflow:

name: Agent Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.9
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
      - name: Check agent health
        run: |
          python manage.py check_agents_health --test-execution
      - name: Run audit
        run: |
          python manage.py agent-audit --format json

Shell Aliases

Add these to your .bashrc or .zshrc for quick access:

alias agents='python manage.py list_agents'
alias agent-run='python manage.py run_agent'
alias agent-create='python manage.py create_agent'
alias agent-health='python manage.py check_agents_health'
alias agent-stats='python manage.py agent_stats'