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:

python manage.py create_agent EmailNotification myapp

This creates an agent in myapp/agents.py:

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:

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:

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

Or use the agent programmatically:

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:

python manage.py list_agents --verbose

5. Check Agent Health

Verify your agents are working correctly:

python manage.py check_agents_health

6. View Agent Statistics

Monitor agent execution:

python manage.py agent_stats

Creating Different Agent Types

Base Agent (Synchronous)

python manage.py create_agent DataValidator myapp --template base

Async Agent

python manage.py create_agent ReportGenerator myapp --template async

Workflow Agent

python manage.py create_agent OrderProcessor myapp --template workflow

API Agent

python manage.py create_agent ExternalAPIClient myapp --template api

Data Processing Agent

python manage.py create_agent CSVProcessor myapp --template data

Next Steps