n8n Workflow Builder

# Release v1.9.0: Execution-Aware Feedback Loop **Release Date:** 2025-12-16 ## 🚀 Overview This release introduces the **Execution-Aware Feedback Loop** - a groundbreaking feature that transforms the system from "deploy & hope" to "deploy → learn → fix". **The Problem:** Most MCP servers end at "Workflow deployed ✅". But the real learning starts **after** execution. LLMs deploy workflows and never know if they actually work. **The Solution:** Automatic execution monitoring with intelligent error analysis and actionable feedback generation. ## ✨ New Features ### 1. Execution Monitoring **ExecutionMonitor** class automatically analyzes workflow executions: - Detects failed executions - Identifies error nodes - Calculates execution metrics (duration, status, mode) - Extracts error details from execution data ### 2. Error Context Extraction **ErrorContextExtractor** provides full context around errors: - Failed node definition - Node parameters and configuration - Output from previous nodes - Intent metadata (WHY this node exists) - Workflow connections ### 3. Intelligent Error Simplification **ErrorSimplifier** recognizes 40+ error patterns and simplifies complex messages: **HTTP Errors:** - 401 Unauthorized → "API authentication failed" - 403 Forbidden → "API access forbidden" - 404 Not Found → "Resource not found" - 429 Rate Limit → "API rate limit exceeded" - 500/502/503 Server Errors → Simplified server error messages - Timeout errors → "Request timed out" **JSON Errors:** - "Unexpected token in JSON" → "Failed to parse JSON response" - "Invalid JSON" → "Invalid JSON format" **Network Errors:** - ECONNREFUSED → "Connection refused - service not reachable" - DNS errors → "DNS resolution failed - domain not found" - Timeout → "Network timeout" **Data Errors:** - undefined data access → "Accessing undefined data" - null reference → "Null reference error" - Missing required field → "Required field is missing" **Authentication Errors:** - Invalid credentials/token/key → "Invalid credentials or API key" - Expired token → "Authentication token expired" ### 4. Actionable Feedback Generation **FeedbackGenerator** creates structured, actionable feedback for LLMs: **Error-Type Specific Suggestions:** **Authentication (401):** - Verify API key or credentials are correctly configured - Check if authentication type matches API requirements - Ensure credentials have not expired - Test authentication manually with curl/Postman **Rate Limit (429):** - Add delay between requests - Implement exponential backoff retry logic - Check API rate limit documentation - Consider upgrading API plan **JSON Parse Errors:** - Check if API is returning HTML error page instead of JSON - Verify Content-Type header is set correctly - Add error handling to parse non-JSON responses - Check API documentation for correct response format **Connection Errors:** - Verify the service is running and accessible - Check firewall rules and network connectivity - Ensure correct hostname and port - Check if service requires VPN or special network access ## 🔧 New MCP Tools ### 1. `watch_workflow_execution` Monitor workflow execution and get error feedback. **Parameters:** - `workflow_id` (required): Workflow to monitor - `execution_id` (optional): Specific execution ID. If not provided, analyzes most recent. **Returns:** - Execution status (success/failed) - Duration and timestamps - Simplified error messages - Tip to use `get_execution_error_context` for details **Example:** ```python watch_workflow_execution(workflow_id="abc123") # Returns: # ❌ Failed # Error in node "HTTP Request": API authentication failed (401) # Tip: Use get_execution_error_context for detailed fix suggestions ``` ### 2. `get_execution_error_context` Get detailed error analysis with fix suggestions. **Parameters:** - `execution_id` (required): Failed execution ID - `workflow_id` (required): Workflow ID **Returns:** - Error summary - Node details (name, type, parameters) - Simplified error message - Original intent (WHY this node exists) - Previous node output context - 3-5 actionable fix suggestions - Raw error message **Example:** ```python get_execution_error_context( execution_id="xyz789", workflow_id="abc123" ) # Returns structured feedback: # ❌ Error in node 'Airtable Create' # Type: authentication # Message: API authentication failed (401) # # Original Intent: # Why: Create customer record in Airtable # Assumption: API key is configured in credentials # # Suggested Fixes: # 1. Verify API key in n8n credentials # 2. Check if authentication type matches (OAuth vs API key) # 3. Test API key manually in Postman # ... ``` ### 3. `analyze_execution_errors` Analyze error patterns across multiple executions. **Parameters:** - `workflow_id` (required): Workflow to analyze - `limit` (optional): Number of recent executions (default: 10) **Returns:** - Total executions analyzed - Success/failure counts - Success rate percentage - Error patterns sorted by frequency - Most problematic nodes **Example:** ```python analyze_execution_errors(workflow_id="abc123", limit=20) # Returns: # Total: 20 executions # Successful: 12 (60%) # Failed: 8 (40%) # # Error Patterns: # 1. HTTP Request - authentication (5 times) # 2. Airtable Create - rate_limit (2 times) # 3. JSON Parser - json_parse (1 time) # # Recommendation: Focus on authentication issue in HTTP Request node ``` ## 🎯 Autonomous Agent Flow The execution-aware feedback loop enables near-autonomous operation: ``` 1. LLM: "Create workflow to sync Notion → Airtable" 2. System: Builds workflow 3. System: Test-executes workflow 4. System: ❌ Error detected in "Airtable Create" node 5. System: Analyzes error → "API authentication failed (401)" 6. System: Extracts context → Missing API key in credentials 7. System: → LLM: "Error: Airtable authentication failed. Suggestion: Configure API key in credentials." 8. LLM: Adds proper authentication 9. System: Re-executes workflow 10. System: ✅ Success 11. System: Logs learning for future workflows ``` ## 🏗️ Architecture ### New Module Structure ``` src/n8n_workflow_builder/execution/ ├── __init__.py └── error_analyzer.py ├── ExecutionMonitor ├── ErrorContextExtractor ├── ErrorSimplifier └── FeedbackGenerator ``` ### Integration with Existing Features **Intent Metadata Integration:** - Error context includes intent metadata - Shows WHY the node was built and what assumptions were made - Helps LLM understand if assumptions were wrong **Example:** ``` Error in node "API Request" Original Intent: Fetch customer data, assuming API returns JSON Error: Failed to parse JSON response (got HTML) → LLM understands the assumption was wrong ``` **Semantic Analysis Integration:** - Error patterns feed into semantic analysis - Builds knowledge base of common mistakes - Improves future workflow suggestions **Feedback System Integration:** - Execution errors stored as feedback - Contributes to AI learning loop - Patterns recognized for future prevention ## 📊 Error Pattern Recognition ### Supported Error Categories 1. **HTTP Errors** (401, 403, 404, 429, 500, 502, 503) 2. **JSON Errors** (parse errors, invalid format) 3. **Network Errors** (connection refused, DNS, timeout) 4. **Data Errors** (undefined, null, missing fields) 5. **Authentication Errors** (invalid credentials, expired tokens) ### Pattern Matching Uses regex patterns to identify errors: ```python ERROR_PATTERNS = [ (r"401|Unauthorized", "authentication", "API authentication failed"), (r"429|Too Many Requests|rate limit", "rate_limit", "API rate limit exceeded"), (r"JSON|json.*parse", "json_parse", "Failed to parse JSON response"), # ... 40+ patterns total ] ``` ## 💡 Use Cases ### 1. Automatic Error Detection ```python # Deploy workflow workflow = create_workflow(...) # Execute execution = execute_workflow(workflow_id) # Monitor automatically result = watch_workflow_execution(workflow_id) # → Immediate feedback if something fails ``` ### 2. Debug Failed Workflows ```python # Workflow keeps failing, but error messages are cryptic context = get_execution_error_context( execution_id="failed_exec_123", workflow_id="abc" ) # → Clear explanation + fix suggestions ``` ### 3. Identify Recurring Issues ```python # Multiple executions failing at different times analysis = analyze_execution_errors(workflow_id="abc", limit=50) # → "Authentication error in HTTP Request happens 80% of the time" # → Focus fix efforts on most common issues ``` ### 4. LLM Self-Healing ```python # LLM workflow: 1. Build workflow 2. Execute & watch 3. If error → get_execution_error_context 4. Read suggestions 5. Apply fix 6. Re-execute 7. Repeat until success ``` ## 🔍 Technical Details ### Error Context Structure ```python { "node_name": "HTTP Request", "node_type": "n8n-nodes-base.httpRequest", "error_details": { "message": "Request failed with status code 401", "stack": "..." }, "node_parameters": { "url": "https://api.example.com", "authentication": "headerAuth", "method": "GET" }, "previous_output": { "Trigger": {...} # Output from previous node }, "intent": { "reason": "Fetch customer data from CRM", "assumption": "API key is configured correctly", "risk": "Rate limit might be exceeded with many customers" } } ``` ### Simplified Error Structure ```python { "error_type": "authentication", "simplified_message": "API authentication failed (401 Unauthorized)", "raw_message": "Request failed with status code 401...", "status_code": 401, "timestamp": "2025-12-16T..." } ``` ### Feedback Structure ```python { "summary": "Error in node 'HTTP Request': API authentication failed", "node": { "name": "HTTP Request", "type": "n8n-nodes-base.httpRequest" }, "error": { "type": "authentication", "message": "API authentication failed (401)", "status_code": 401 }, "suggestions": [ "Verify API key or credentials are correctly configured", "Check if authentication type matches API requirements", ... ], "context": { "has_intent": true, "intent": {...}, "previous_nodes": ["Trigger", "Data Transform"] } } ``` ## 📝 Example Output ### watch_workflow_execution ```markdown # Execution Monitor: Customer Sync Workflow **Execution ID**: `exec_abc123` **Status**: ❌ Failed **Mode**: trigger **Started**: 2025-12-16T10:30:00Z **Stopped**: 2025-12-16T10:30:05Z **Duration**: 5000ms ## ❌ Errors Detected ### Node: HTTP Request **Error Type**: `authentication` **Message**: API authentication failed (401 Unauthorized) --- 💡 **Tip**: Use `get_execution_error_context` with execution_id `exec_abc123` to get detailed error analysis and fix suggestions. ``` ### get_execution_error_context ```markdown # ❌ Execution Error Detected ## Error Summary Error in node 'HTTP Request': API authentication failed (401 Unauthorized) ## Node Details - **Name**: HTTP Request - **Type**: `n8n-nodes-base.httpRequest` ## Error Details - **Type**: `authentication` - **Message**: API authentication failed (401 Unauthorized) - **Status Code**: 401 ## 📝 Original Intent **Why this node exists**: Fetch customer data from CRM API **Assumption**: API key is configured in n8n credentials **Known Risk**: API might be rate limited with many customers ## 💡 Suggested Fixes 1. Verify API key or credentials are correctly configured 2. Check if authentication type matches API requirements (Basic, Bearer, OAuth, etc.) 3. Ensure credentials have not expired 4. Test authentication manually with a tool like curl or Postman ## 🔍 Debug Context **Previous nodes**: Trigger, Data Transform **Has input data**: Yes --- **Raw Error**: `Request failed with status code 401: {"error":"Unauthorized"}` ``` ### analyze_execution_errors ```markdown # Execution Error Analysis: Customer Sync Workflow **Total Executions Analyzed**: 10 **Successful**: ✅ 3 **Failed**: ❌ 7 **Success Rate**: 30.0% ## 🔥 Error Patterns Most common errors across executions: ### HTTP Request **Error Type**: `authentication` **Message**: API authentication failed (401 Unauthorized) **Occurrences**: 5 times **Execution IDs**: exec_1, exec_2, exec_3 (+2 more) ### Airtable Create **Error Type**: `rate_limit` **Message**: API rate limit exceeded (429) **Occurrences**: 2 times **Execution IDs**: exec_4, exec_7 --- 💡 **Recommendation**: Focus on fixing the most frequent errors first. Use `get_execution_error_context` for detailed fix suggestions. ``` ## 🎉 Impact This feature represents a **massive quality leap**: ### Before v1.9.0: ``` LLM: "I built a workflow" User: "It's not working" LLM: "Can you tell me what error you see?" User: *copies cryptic error* LLM: *guesses what might be wrong* ``` ### After v1.9.0: ``` LLM: "I built a workflow and tested it" System: "Error detected: Authentication failed in HTTP Request node" System: "Suggestion: Check API key configuration in credentials" LLM: "I'll fix the authentication" LLM: *applies fix and re-tests* System: "✅ Success" ``` ### Benefits: ✅ **Faster Development** - Immediate feedback on failures ✅ **Better Quality** - Errors caught and fixed automatically ✅ **Autonomous Operation** - LLM can self-heal workflows ✅ **Knowledge Building** - Error patterns feed into learning ✅ **User Experience** - No more manual error debugging ✅ **Context Continuity** - Intent metadata provides WHY context ## 🔧 Files Changed ### New Files - `src/n8n_workflow_builder/execution/__init__.py` - `src/n8n_workflow_builder/execution/error_analyzer.py` (600+ lines) ### Modified Files - `src/n8n_workflow_builder/server.py` (+218 lines) - Added 3 new tool definitions - Added 3 new tool handlers - Integrated error analysis components ## 📦 Dependencies No new dependencies required. Uses existing n8n API capabilities. ## 🚀 Getting Started ```python # 1. Deploy a workflow workflow = create_workflow(...) # 2. Execute it execution = execute_workflow(workflow_id) # 3. Watch for errors result = watch_workflow_execution(workflow_id) # 4. If failed, get context if result["has_errors"]: context = get_execution_error_context( execution_id=result["execution_id"], workflow_id=workflow_id ) # Apply suggested fixes... # 5. Analyze patterns over time analysis = analyze_execution_errors(workflow_id, limit=20) ``` ## 🎯 Future Enhancements Potential future improvements: - Automatic fix application for common errors - Machine learning on error patterns - Predictive error detection before execution - Integration with external monitoring tools - Error notifications via webhook/email --- **Full Changelog**: v1.8.2...v1.9.0