Purple8-platform

Agent Development Instructions

Overview

This document defines the standard contract and behavior for all agents in the Purple8 platform. ALL agents MUST follow these guidelines for proper HITL (Human-In-The-Loop) integration.

---

Agent Output Contract (MANDATORY)

Every agent’s run() method MUST return a dictionary with the following structure:

{
    "human_summary": str,     # REQUIRED - Human-readable summary for HITL review
    "<primary_output>": Any,  # REQUIRED - Main agent output (varies by agent type)
    "agent_type": str,        # REQUIRED - Agent identifier
    "key_decisions": list,    # OPTIONAL - List of important decisions made
    "metadata": dict,         # OPTIONAL - Additional context
}

human_summary Requirements

The human_summary field is CRITICAL for HITL. It must:

1. Start with a header using emoji + agent name: ## 🎨 Design Summary
2. Include “What Was Generated” section describing outputs
3. List key decisions made by the agent
4. End with “For HITL Review” checklist

Example template:

def _create_human_summary(self, result: str, context: str) -> str:
    return f"""## 🎨 {self.agent_name} Summary

### What Was Generated
- Brief description of outputs
- Key artifacts created

### Key Decisions
- Decision 1 and rationale
- Decision 2 and rationale

### For HITL Review
✅ Checkpoint 1
✅ Checkpoint 2
✅ Checkpoint 3
"""

---

Agent Input Contract

Required Attributes

Every agent MUST define:

class MyAgent(BaseAgent):
    def __init__(self, llm_instance=None):
        super().__init__(llm_instance, agent_name="MyAgent")
        
        # Phase and dependencies
        self.phase = "planning"  # conception|planning|implementation|qa|delivery|safety
        self.dependencies = ['previous_agent']  # Agents that must run before this
        
        # Input contract
        self.required_inputs = [
            {
                "name": "requirements",
                "type": "string",
                "description": "Project requirements from IdeationAgent",
                "format": "markdown"
            }
        ]
        
        self.optional_inputs = [
            {
                "name": "context",
                "type": "dict",
                "description": "Additional context",
                "format": "json"
            }
        ]
        
        # Output contract
        self.output_format = "json"  # json|markdown|code
        self.output_schema = {
            "primary_output": {
                "type": "string",
                "description": "Main output description"
            },
            "human_summary": {
                "type": "string",
                "description": "Human-readable summary for HITL"
            }
        }

---

Data Flow Between Agents

Foundational Agent Chain

ideation → design → architecture → database → api_development 
    ↓          ↓          ↓            ↓            ↓
requirements  design_spec  architecture  database_schema  api_spec
                                              ↓
        ┌─────────────────┬─────────────────┬─────────────────┐
        ↓                 ↓                 ↓                 ↓
frontend_development  backend_development  infrastructure_development
        ↓                 ↓                 ↓
    frontend_code     backend_code     infrastructure_code
        └─────────────────┴─────────────────┘
                          ↓
                      unittest
                          ↓
                         sit
                          ↓
                         uat
                          ↓
                  software_packaging
                          ↓
                      deployment

Key Data Passed Between Agents

From Agent	To Agent	Data Key	Description
ideation	ALL	requirements	Project requirements specification
design	frontend, architecture	design_spec	UI/UX design document
architecture	backend, api, database, infra	architecture	System architecture
database	backend, api, infra	database_schema	Database design
api_development	frontend, backend	api_spec	OpenAPI specification
frontend_development	unittest, packaging	frontend_code	Frontend source code
backend_development	unittest, packaging	backend_code	Backend source code
infrastructure_development	deployment	infrastructure_code	Docker/K8s configs
unittest	sit	unit_test_results	Unit test suite
sit	uat	sit_results	Integration test results
uat	deployment	uat_results	UAT sign-off
software_packaging	deployment	package	Deployment package

---

Agent Categories

Core Agents (Foundational - Always Run)

• IdeationAgent - Requirements gathering
• DesignAgent - UI/UX design
• ArchitectureAgent - System architecture
• DatabaseAgent - Database design
• APIDevelopmentAgent - API contracts (generates OpenAPI/Swagger)
• FrontendDevelopmentAgent - Frontend code
• BackendDevelopmentAgent - Backend code
• InfrastructureDevelopmentAgent - DevOps configs
• UnitTestAgent - Unit tests
• SITAgent - System integration tests
• UATAgent - User acceptance tests
• SoftwarePackagingAgent - Build configs
• DeploymentAgent - Deployment plans

Specialized Agents (Context-Driven)

• MobileAgent - Mobile app development
• AIMLAgent - AI/ML features
• RAGAgent - Retrieval-augmented generation
• SecurityQAAgent - Security testing
• PerformanceQAAgent - Performance testing
• ObservabilityAgent - Monitoring setup
• GuardrailsAgent - AI safety
• LegalAgent - Compliance checking
• DocumentationAgent - Doc generation

---

Best Practices

1. Always Extract Context from Upstream

async def run(self, requirements: str, upstream_output: Dict = None, **kwargs):
    # Extract relevant data from upstream
    if upstream_output:
        relevant_data = upstream_output.get('key_data', '')
    else:
        relevant_data = "Default fallback"

2. Handle Missing Inputs Gracefully

def _format_input(self, data: Optional[Dict]) -> str:
    if not data:
        return "Not provided - use reasonable defaults"
    if isinstance(data, str):
        return data
    return str(data)

3. Always Include Human Summary

async def run(self, ...) -> Dict[str, Any]:
    result = await self._invoke_llm(prompt)
    
    # ALWAYS create human summary
    human_summary = self._create_human_summary(result)
    
    return {
        "primary_output": result,
        "human_summary": human_summary,
        "agent_type": "my_agent"
    }

4. Use Consistent Logging

import logging
logger = logging.getLogger(__name__)

class MyAgent(BaseAgent):
    async def run(self, ...):
        logger.info(f"{self.agent_name} starting...")
        # ... work ...
        logger.info(f"{self.agent_name} completed")

---

Checklist for New Agents

• Inherits from BaseAgent
• Defines phase and dependencies
• Defines required_inputs and optional_inputs
• Defines output_format and output_schema
• Returns dict with human_summary field
• Registered in shared/agents/registry.py
• Added to FOUNDATIONAL_AGENTS or specialized list in orchestrator
• Pipeline kwargs handling in services/gateway/routers/pipeline.py
• Tests written for agent

---

API Documentation Generation

The APIDevelopmentAgent generates:

1. OpenAPI 3.0 Specification (Swagger) - For API documentation
2. Endpoint definitions - All REST endpoints
3. Request/Response schemas - Pydantic models
4. TypeScript API client - For frontend integration

The Swagger/OpenAPI spec can be:

• Served via Swagger UI at /docs
• Exported as openapi.json or openapi.yaml
• Used to generate client SDKs