​

Best Practices Guide

​

Task Design

​

Naming Conventions

{
    "name": "ValidateCustomerData",
    "description": "Validates customer information from input form"
}

{
    "name": "task1",
    "description": "validates data"
}

​

Task Organization

1. Logical Grouping
2. Clear Dependencies
   • Keep dependencies minimal
   • Avoid complex chains
   • Document connection purposes

​

Input/Output Configuration

​

Input Parameters

1. Clear Naming
   Copy

   {
       "name": "customerEmail",
       "type": "STRING",
       "description": "Customer's primary email address"
   }
   

2. Type Selection
   • Use simplest type possible
   • Consider data flow requirements
   • Document format requirements
3. Validation Rules
   Copy

   {
       "name": "age",
       "type": "INTEGER",
       "description": "Customer age in years",
       "required": true,
       "source": "task_config"
   }
   

​

Output Parameters

1. Structured Output
   Copy

   {
       "name": "validationResult",
       "type": "OBJECT",
       "properties": {
           "isValid": "BOOLEAN",
           "errors": "ARRAY"
       }
   }
   

2. Error Handling
   • Include error information
   • Provide status indicators
   • Add validation messages

​

Task-Specific Best Practices

​

AI Tasks

1. Clear Instructions
   Copy

   {
       "instructions": "Analyze the customer feedback and categorize the sentiment as POSITIVE, NEGATIVE, or NEUTRAL. Extract key points and improvement suggestions.",
       "expected_output": {
           "sentiment": "STRING",
           "keyPoints": "ARRAY",
           "suggestions": "ARRAY"
       }
   }
   

2. Output Structure
   • Define clear categories
   • Include confidence scores
   • Structure for easy processing

​

Human Tasks

1. Clear Decision Points
   Copy

   {
       "instructions": "Review the generated content for accuracy and brand alignment. Choose APPROVE or REJECT and provide feedback.",
       "expected_output": {
           "decision": "STRING",
           "feedback": "STRING"
       }
   }
   

2. Assignment Rules
   Copy

   {
       "rule_type": "Human Feedback",
       "assignment_type": "Team",
       "assignment_logic": "Round Robin"
   }
   

​

App Tasks

1. Tool Configuration
   Copy

   {
       "tool_name": "EmailService",
       "provider": "SendGrid",
       "input_parameters": [
           {
               "name": "template_id",
               "type": "STRING",
               "required": true
           }
       ]
   }
   

2. Error Handling
   Copy

   {
       "error_policy": "RETRY",
       "max_retries": 3,
       "retry_delay": 60
   }
   

​

Coder Tasks

1. Code Artifact Management
   Copy

   {
       "code_artifact_id": "12345",
       "input_parameters": [
           {
               "name": "data",
               "type": "OBJECT",
               "description": "Data structure following schema XYZ"
           }
       ]
   }
   

​

Error Handling

​

Global Error Policies

{
    "error_policy": "RAISE",
    "notification_channels": ["email", "slack"],
    "error_details": "DETAILED"
}

​

Task-Level Error Handling

{
    "on_error": {
        "action": "RETRY",
        "max_attempts": 3,
        "fallback_task": "ErrorHandler"
    }
}

​

Performance Optimization

​

1. Task Efficiency

• Minimize dependencies
• Optimize data transfer
• Use appropriate task types

​

2. Resource Management

• Configure timeouts
• Set memory limits
• Monitor execution time

​

Security Best Practices

​

1. Data Handling

• Minimize sensitive data
• Use secure parameters
• Implement data masking

​

2. Access Control

• Proper assignment rules
• Role-based access
• Audit logging

​

Testing Guidelines

​

1. Task Testing

{
    "test_cases": [
        {
            "input": "sample_input",
            "expected_output": "expected_result"
        }
    ]
}

​

2. Workflow Testing

• Test complete flows
• Validate error handling
• Check performance

​

Maintenance

​

1. Documentation

• Clear descriptions
• Updated configurations
• Change history
• Usage examples

​

2. Monitoring

• Track execution time
• Monitor error rates
• Review usage patterns

​

Common Pitfalls to Avoid

1. Over-complexity
   • Too many dependencies
   • Unnecessary tasks
   • Complex logic
2. Poor Error Handling
   • Missing error cases
   • Unclear error messages
   • No recovery path
3. Insufficient Validation
   • Missing input validation
   • Weak type checking
   • Incomplete error checks