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:

.. code-block:: bash

    python manage.py <command> [options]

Agent Discovery & Listing
--------------------------

list_agents
^^^^^^^^^^^

Lists all registered agents in your Django project.

.. code-block:: bash

    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:**

.. code-block:: bash

    # 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.

.. code-block:: bash

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

**Examples:**

.. code-block:: bash

    # 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.

.. code-block:: bash

    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:**

.. code-block:: bash

    # 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.

.. code-block:: bash

    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:**

.. code-block:: bash

    # 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.

.. code-block:: bash

    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:**

.. code-block:: bash

    # 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.

.. code-block:: bash

    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:**

.. code-block:: bash

    # 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.).

.. code-block:: bash

    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:**

.. code-block:: bash

    # 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.

.. code-block:: bash

    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.

.. code-block:: bash

    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:

.. code-block:: bash

    # 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:

.. code-block:: yaml

    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:

.. code-block:: bash

    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'