Best Practices

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

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