Quick Start Guide
=================

This guide will help you get started with django-agents in 5 minutes.

1. Create Your First Agent
---------------------------

Use the management command to scaffold a new agent:

.. code-block:: bash

    python manage.py create_agent EmailNotification myapp

This creates an agent in ``myapp/agents.py``:

.. code-block:: python

    from django_agents.base import BaseAgent
    from typing import Any, Dict

    class EmailNotificationAgent(BaseAgent):
        """Agent for email_notification functionality"""

        name = "email_notification"
        description = "Agent for email_notification functionality"
        version = "1.0.0"

        def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
            """
            Execute the agent logic.

            Args:
                context: Execution context

            Returns:
                Execution result
            """
            # TODO: Implement agent logic here
            self.log_info("Executing email_notification")

            result = {
                "success": True,
                "message": "Agent executed successfully",
            }

            return result

2. Implement Agent Logic
-------------------------

Edit the agent to add your custom logic:

.. code-block:: python

    from django.core.mail import send_mail
    from django_agents.base import BaseAgent
    from typing import Any, Dict

    class EmailNotificationAgent(BaseAgent):
        """Send email notifications to users."""

        name = "email_notification"
        description = "Sends email notifications"
        version = "1.0.0"

        def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
            """Send an email notification."""
            recipient = context.get('recipient')
            subject = context.get('subject')
            message = context.get('message')

            if not recipient or not subject or not message:
                return {
                    'success': False,
                    'error': 'Missing required fields'
                }

            self.log_info(f"Sending email to {recipient}")

            try:
                send_mail(
                    subject=subject,
                    message=message,
                    from_email='noreply@example.com',
                    recipient_list=[recipient],
                    fail_silently=False,
                )

                return {
                    'success': True,
                    'recipient': recipient,
                    'subject': subject
                }
            except Exception as e:
                self.log_error(f"Failed to send email: {str(e)}")
                return {
                    'success': False,
                    'error': str(e)
                }

3. Run Your Agent
-----------------

Execute the agent from the command line:

.. code-block:: bash

    python manage.py run_agent email_notification --context '{
        "recipient": "user@example.com",
        "subject": "Welcome!",
        "message": "Welcome to our platform!"
    }'

Or use the agent programmatically:

.. code-block:: python

    from django_agents import get_registry

    # Get the agent
    registry = get_registry()
    agent = registry.get_agent('email_notification')

    # Execute
    result = agent.run({
        'recipient': 'user@example.com',
        'subject': 'Welcome!',
        'message': 'Welcome to our platform!'
    })

    print(result)

4. List All Agents
------------------

View all registered agents:

.. code-block:: bash

    python manage.py list_agents --verbose

5. Check Agent Health
---------------------

Verify your agents are working correctly:

.. code-block:: bash

    python manage.py check_agents_health

6. View Agent Statistics
-------------------------

Monitor agent execution:

.. code-block:: bash

    python manage.py agent_stats

Creating Different Agent Types
-------------------------------

Base Agent (Synchronous)
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

    python manage.py create_agent DataValidator myapp --template base

Async Agent
^^^^^^^^^^^

.. code-block:: bash

    python manage.py create_agent ReportGenerator myapp --template async

Workflow Agent
^^^^^^^^^^^^^^

.. code-block:: bash

    python manage.py create_agent OrderProcessor myapp --template workflow

API Agent
^^^^^^^^^

.. code-block:: bash

    python manage.py create_agent ExternalAPIClient myapp --template api

Data Processing Agent
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

    python manage.py create_agent CSVProcessor myapp --template data

Next Steps
----------

* Learn about :doc:`api/base` classes
* Explore :doc:`api/registry` for agent management
* Check out :doc:`examples` for real-world use cases
* Set up :doc:`api/auditors` for code quality checks