Best Practices Guide¶

This guide outlines recommended practices for creating effective and maintainable workflow agents.

Task Design¶

Naming Conventions¶

✅ Do:

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

❌ Don't:

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

Task Organization¶

1. Logical Grouping

   graph TD
       A[Data Input] --> B[Data Validation]
       B --> C[Data Processing]
       C --> D[Result Output]

2. Clear Dependencies

   • Keep dependencies minimal
   • Avoid complex chains
   • Document connection purposes

Input/Output Configuration¶

Input Parameters¶

1. Clear Naming

   {
       "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

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

Output Parameters¶

1. Structured Output

   {
       "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

   {
       "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

   {
       "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

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

App Tasks¶

1. Tool Configuration

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

2. Error Handling

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

Coder Tasks¶

1. Code Artifact Management

   {
       "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