n8n Workflow Builder

# Release v1.3.0: AI Feedback & Error Analysis System **Release Date**: 2025-12-16 **Type**: Feature Release --- ## 🎯 Overview Version 1.3.0 introduces an intelligent error analysis system that provides AI-friendly feedback for failed workflow executions, enabling learning loops and continuous improvement for AI agents. --- ## ✨ New Features ### AIFeedbackAnalyzer Class Intelligent error analysis for failed workflow executions with pattern recognition and root cause identification. ### Pattern Recognition Automatically detects 6+ common failure types: 1. **Authentication/Authorization** (401, 403, unauthorized) 2. **Network/Connection** (timeout, ECONNREFUSED) 3. **Data/Type** (undefined, null, type errors) 4. **Database/SQL** (syntax, query errors) 5. **Rate Limiting** (429, too many requests) 6. **Missing/Invalid Parameters** ### Root Cause Identification For each error pattern, provides: - Root cause explanation - Step-by-step suggestions - AI-specific guidance for future workflow generation - Code examples (wrong vs. correct) - Node configuration recommendations ### AI-Friendly Feedback Structured guidance specifically designed for AI agents to learn from errors and improve workflow generation. --- ## 🛠️ New MCP Tools (2 tools) ### 1. `analyze_execution_errors` Analyze failed executions with AI-friendly feedback. **Parameters:** - `execution_id` (required): Execution ID to analyze **Returns:** - Root cause identification - Structured suggestions - Fix examples with code - AI guidance for future workflow generation **Example Output:** ```markdown ## Error Analysis: Execution exec_123 ### Root Cause: Authentication Error The HTTP Request node failed with 401 Unauthorized. ### What Went Wrong: - Hardcoded API key instead of credential reference - Missing Authorization header - Wrong authentication type (Bearer vs Basic) ### How to Fix: 1. Use credential reference: `{{$credentials.apiName}}` 2. Set authentication type to "Bearer Token" 3. Add Authorization header: `Bearer {{$credentials.apiName}}` ### AI Guidance (for future workflow generation): When generating workflows with API calls: - Always use `{{$credentials.name}}` instead of hardcoded values - Specify correct authentication type (Bearer, Basic, OAuth) - Include proper headers (Authorization, API-Key) - Test credentials before deploying ### Code Example: ❌ Wrong: { "authentication": "none", "options": { "headers": { "Authorization": "Bearer sk-abc123" } } } ✅ Correct: { "authentication": "predefinedCredentialType", "nodeCredentialType": "apiKeyAuth", "options": {} } ``` --- ### 2. `get_workflow_improvement_suggestions` Generate specific improvement recommendations for a workflow based on execution failures. **Parameters:** - `workflow_id` (required): Workflow ID to analyze - `execution_id` (optional): Specific execution to analyze **Returns:** - Nodes to modify (with specific field changes) - Nodes to add (error handlers, delays, validation) - Parameter updates - Configuration fixes **Example Output:** ```markdown ## Improvement Suggestions: Workflow "API Integration" ### Nodes to Modify: #### HTTP Request "API Call" - Change `authentication` from "none" to "predefinedCredentialType" - Add `nodeCredentialType`: "apiKeyAuth" - Remove hardcoded Authorization header #### Code "Transform Data" - Add null check: `if (item.data) { ... }` - Add error handling: `try { ... } catch (e) { ... }` ### Nodes to Add: #### Error Trigger - Add after "API Call" node - Configure to catch API errors - Send notification on failure #### Wait Node - Add before "API Call" node - Configure 1 second delay - Prevents rate limiting ### Best Practices: 1. Use credential references instead of hardcoded values 2. Add error handling for all API calls 3. Implement retry logic for network operations 4. Add validation for incoming data ``` --- ## 🤖 AI Guidance Features ### For Each Error Type #### 1. Authentication/Authorization Errors **AI Guidance:** - Use `{{$credentials.name}}` instead of hardcoded values - Specify correct authentication type (Bearer, Basic, OAuth) - Include proper headers (Authorization, API-Key) - Test credentials before deploying #### 2. Network/Connection Errors **AI Guidance:** - Set appropriate timeout values (default: 30s) - Add retry logic (3 attempts with exponential backoff) - Check network connectivity before API calls - Use connection pooling for high-volume requests #### 3. Data/Type Errors **AI Guidance:** - Validate input data structure - Add null/undefined checks - Use type coercion carefully - Test with sample data before deployment #### 4. Database/SQL Errors **AI Guidance:** - Use parameterized queries (prevent SQL injection) - Validate SQL syntax before execution - Check database connection before queries - Use transactions for multi-step operations #### 5. Rate Limiting Errors **AI Guidance:** - Add delay between requests (Wait node) - Implement exponential backoff - Check rate limit headers - Use batching for bulk operations #### 6. Missing/Invalid Parameters **AI Guidance:** - Validate required parameters before execution - Provide default values for optional parameters - Use IF node to check parameter existence - Add parameter validation in Code nodes --- ## 📚 Error Pattern Detection ### Pattern Matching Rules | Error Type | Detection Keywords | Severity | |------------|-------------------|----------| | Authentication | 401, 403, unauthorized, forbidden | HIGH | | Network | timeout, ECONNREFUSED, ETIMEDOUT | HIGH | | Data | undefined, null, TypeError, cannot read | MEDIUM | | Database | SQL syntax, query error, connection refused | HIGH | | Rate Limiting | 429, too many requests, rate limit | MEDIUM | | Parameters | missing parameter, invalid parameter | MEDIUM | --- ## 📚 New Documentation ### `docs/AI_FEEDBACK.md` Complete AI feedback system guide (450+ lines) covering: - Error pattern reference - AI guidance for each error type - Integration examples - Learning loop workflows - Analytics & insights - Custom pattern detection --- ## 🔧 Technical Implementation ### AIFeedbackAnalyzer Class ```python class AIFeedbackAnalyzer: @staticmethod def analyze_execution_error(execution_data: Dict) -> Dict: """Analyze execution error and provide feedback""" @staticmethod def detect_error_pattern(error_message: str) -> str: """Detect error pattern from error message""" @staticmethod def get_ai_guidance(error_pattern: str) -> Dict: """Get AI-specific guidance for error pattern""" @staticmethod def generate_improvement_suggestions(workflow_data: Dict, execution_data: Dict) -> Dict: """Generate workflow improvement suggestions""" ``` ### Error Extraction - Extract errors from execution data - Identify failing nodes - Parse error messages - Detect error patterns ### Structured Feedback Generation - Root cause identification - Step-by-step suggestions - Code examples (wrong vs. correct) - AI guidance for future workflows ### Node-Specific Improvement Suggestions - Analyze failing nodes - Generate specific field changes - Recommend additional nodes - Provide configuration fixes --- ## 📊 Benefits ### AI Learning AI agents learn from failures and improve workflow generation over time. **Learning Loop:** ``` 1. AI generates workflow 2. Workflow executes and fails 3. AI analyzes error with AIFeedbackAnalyzer 4. AI learns from feedback 5. AI generates improved workflow 6. Workflow succeeds ✅ ``` ### Faster Debugging Root cause identification speeds up troubleshooting from hours to seconds. ### Better Workflows Specific guidance leads to higher quality workflows from the start. ### Prevents Repeated Errors AI remembers error patterns and avoids making the same mistakes. ### Actionable Feedback Not just "what" failed, but "how" to fix it with concrete examples. --- ## 🎯 Use Cases ### 1. AI Workflow Generation with Feedback Loop ``` User: "Create a workflow that syncs Salesforce to PostgreSQL" Claude: Generates workflow User: "The workflow failed" Claude: Analyzes error, learns pattern, generates improved workflow ``` ### 2. Automated Workflow Debugging ``` User: "Debug execution exec_123" Claude: Uses analyze_execution_errors, identifies root cause, suggests fixes ``` ### 3. Learning from Production Failures ``` User: "Analyze all failed executions this week" Claude: Identifies common patterns, suggests systemic improvements ``` ### 4. Self-Healing Workflows ``` Workflow fails → AI analyzes error → AI suggests fix → AI applies fix → Workflow retries ``` ### 5. Error Pattern Analytics ``` User: "What are the most common errors in my workflows?" Claude: Analyzes execution history, identifies patterns, suggests preventive measures ``` ### 6. Developer Assistance ``` Developer: "Why did my workflow fail?" Claude: Provides detailed analysis with examples and best practices ``` --- ## 🔄 Integration with Existing Features ### Works Seamlessly With: - **Validation System**: Catch errors before deployment - **State Management**: Log analysis actions to history - **Error Debugging**: Enhanced with AI-friendly feedback - **Workflow Generation**: Improve generation based on feedback ### Integration Flow: ``` 1. Workflow Generation → 2. Validation → 3. Execution → 4. Error Analysis → 5. Learning Loop ``` --- ## 🚀 Performance - **Error Pattern Detection**: ~5ms per error - **Root Cause Analysis**: ~20ms per execution - **Improvement Suggestions**: ~50ms per workflow - **Total Analysis**: ~75ms per failed execution --- ## 🔮 Future Enhancements Planned for future releases: - Custom error pattern detection - Machine learning for pattern recognition - Error prediction before execution - Automated fix application - Error analytics dashboard --- ## 📝 Breaking Changes **None** - This release is fully backward compatible. --- ## 🙏 Credits **Developed by**: AI Agent Assistant + Human Collaboration **Inspiration**: GitHub Copilot feedback, Stack Overflow error patterns --- **Happy Learning!** 🎉