@pixelml/claw-linux-x64 2.0.0 → 3.0.0

package/.claw/skill/agenticflow-skill/GUIDES.md

@@ -0,0 +1,2269 @@
+# Solution Creation Process (Workflows & Agents)
+
+This guide provides the complete process for creating AgenticFlow workflows and specialized AI agents from natural language requirements to production-ready solutions.
+
+## 🎯 The 7-Phase Creation Process
+
+### Phase 1: Health Check & Setup
+
+**OPTIONAL - Only call API when necessary:**
+
+```javascript
+agenticflow_health_check() // SKIP this unless you need to validate connection
+```
+
+**When to call:**
+- ✅ First time using the skill in a session (validate connection)
+- ✅ User explicitly asks to check connection
+- ✅ After errors to verify API is working
+- ❌ **NOT needed** for every workflow - all node data is LOCAL
+
+**Purpose (when called):**
+- Verify API connectivity
+- Check available features
+- Confirm workspace access
+- Validate MCP tools availability
+
+**IMPORTANT:** All node type data (139 nodes) is available locally in:
+- `references/official_node_types.json` - Complete node data
+- `references/node_types.md` - Categorized reference
+- `references/complete_node_types.md` - Full schemas
+
+**Save API calls** - Use local files for node discovery!
+
+---
+
+### Phase 2: Discovery & Requirements Analysis
+
+**Goal:** Understand what the user wants to automate and break it down into actionable components.
+
+**Steps:**
+
+1. **Deep Thinking:**
+   - Analyze the user's natural language request
+   - Identify the core automation goal
+   - Break down into logical workflow steps
+   - Consider data sources and destinations
+
+2. **Clarifying Questions:**
+   - Ask follow-up questions if requirements are unclear
+   - Confirm assumptions about data formats
+   - Verify external service access
+   - Understand expected outputs
+
+3. **Node Discovery (USE LOCAL FILES FIRST):**
+   - **PRIMARY:** Load `references/node_types.md` - Browse 139 nodes by category
+   - **PRIMARY:** Check `references/examples/workflows/` - 78 real workflow patterns
+   - **PRIMARY:** Reference `guides/02_node_selection_strategy.md` - Node selection guide
+   - **FALLBACK:** Only use API if absolutely needed:
+     - `agenticflow_search_node_types({name: 'keyword'})` - Specific search
+     - `agenticflow_list_node_types({limit: 200})` - Need latest data
+   - **TIP:** Local files have ALL 139 nodes with complete details!
+
+4. **Service Identification:**
+   - List all external services mentioned (Gmail, Slack, Shopify, etc.)
+   - Determine if standard nodes or MCP integrations are needed
+   - Check for 2,500+ MCP integration options
+
+**Example:**
+
+```
+User: "I need to monitor competitor prices and update my team via Slack"
+
+Discovery:
+✓ Data Source: Competitor websites (web scraping needed)
+✓ Processing: Price extraction and analysis (LLM + data extraction)
+✓ Destination: Slack notifications (MCP integration)
+✓ Frequency: Scheduled or manual trigger
+✓ Nodes needed: web_scraping, llm, mcp_run_action
+```
+
+---
+
+### Phase 3: MCP Integration Analysis
+
+**When to use MCP:**
+- User mentions external services (Gmail, Slack, HubSpot, etc.)
+- Need CRM, communication, e-commerce, or productivity tools
+- Standard nodes don't provide required functionality
+
+**MCP Planning Process:**
+
+1. **Identify MCP Services:**
+   - CRM: HubSpot, Salesforce, Pipedrive
+   - Communication: Gmail, Slack, Teams, WhatsApp
+   - E-commerce: Shopify, WooCommerce, Stripe
+   - Productivity: Google Sheets, Notion, Airtable
+   - Marketing: Mailchimp, Facebook, LinkedIn
+   - And 2,500+ more!
+
+2. **Plan MCP Actions:**
+   - Action naming pattern: `SERVICE-ACTION-NAME` (all caps with hyphens)
+   - Examples:
+     - `GMAIL-SEND-EMAIL`
+     - `GOOGLE_SHEETS-APPEND-ROW`
+     - `SLACK-SEND-MESSAGE`
+     - `HUBSPOT-CREATE-CONTACT`
+
+3. **Design Instructions:**
+   - Write clear, specific instruction for AI to execute
+   - Include template variables from previous nodes
+   - Specify exact operations and formatting
+
+4. **Note Connection Requirements:**
+   - Document which MCP connections user needs
+   - Each service requires its own connection
+   - User sets up at agenticflow.ai/app/mcp
+
+**MCP Node Structure:**
+```javascript
+{
+  "name": "descriptive_action_name",
+  "title": "Descriptive Action Title",
+  "node_type_name": "mcp_run_action",
+  "input_config": {
+    "action": "SERVICE-ACTION-NAME",
+    "input_params": {
+      "instruction": "Detailed instruction with {{template_variables}}"
+    }
+  },
+  "output_mapping": {},
+  "connection": "{{__app_connections__['connection-uuid']}}"
+}
+```
+
+---
+
+### Phase 4: Configuration Planning
+
+**Goal:** Design the complete workflow architecture with proper data flow.
+
+**Steps:**
+
+1. **Node Selection:**
+   - Choose appropriate node types for each step
+   - Reference `references/node_types.md` for categories
+   - Check `references/complete_node_types.md` for field details
+
+2. **Data Flow Design:**
+   - Map how data flows between nodes
+   - Use template variables: `{{node_name.field}}`
+   - Common output fields:
+     - LLM nodes: `.content`
+     - Perplexity/search: `.response`
+     - Web scraping: `.scraped_content`
+     - MCP actions: `.output`
+     - Structured extraction: `.extracted_data`
+
+3. **Input Schema Design:**
+   - Define workflow input parameters
+   - Add proper UI metadata for user-friendly forms
+   - Include descriptions and placeholders
+
+4. **Execution Order:**
+   - Plan sequential vs parallel execution
+   - Use `prevNodeName` for dependencies
+   - Optimize for performance
+
+**Visual Representation:**
+Always show the user a workflow diagram like:
+```
+User Input → Web Scraping → AI Analysis → External Service → Output
+```
+
+---
+
+### Phase 5: Pre-Building & Validation
+
+**Goal:** Structure the complete workflow before creation.
+
+**Components to prepare:**
+
+1. **Workflow Metadata:**
+```javascript
+{
+  "name": "Clear Workflow Name",
+  "description": "What this workflow does and why"
+}
+```
+
+2. **Input Schema:**
+```javascript
+{
+  "input_schema": {
+    "type": "object",
+    "title": "User inputs",
+    "required": ["essential_field"],
+    "properties": {
+      "field_name": {
+        "type": "string",
+        "title": "Display Label",
+        "description": "Help text for users",
+        "ui_metadata": {
+          "type": "short_text", // or long_text, dropdown, multi_select
+          "order": 0,
+          "placeholder": "Example value",
+          "value": "default_value"
+        }
+      }
+    }
+  }
+}
+```
+
+3. **Nodes Array:**
+- Each node with complete configuration
+- Proper field requirements met
+- Template variables correctly referenced
+
+4. **Output Mapping:**
+```javascript
+{
+  "output_mapping": {
+    "result": "{{final_node.content}}",
+    "metadata": "{{extraction_node.data}}"
+  }
+}
+```
+
+5. **Connection Documentation:**
+- List all MCP connections needed
+- Provide setup instructions
+- Note connection categories
+
+---
+
+### Phase 6: Building the Workflow
+
+**Goal:** Create the actual workflow using AgenticFlow MCP tools.
+
+**Build Steps:**
+
+1. **Prepare Complete JSON:**
+   - Validate all required fields
+   - Check node type names are exact
+   - Ensure proper data types
+
+2. **REQUIRED: Validate First:**
+```javascript
+// ALWAYS validate before creating
+const validationResult = agenticflow_validate_workflow({
+  name: "Workflow Name",
+  description: "Workflow description",
+  nodes: [...],
+  input_schema: {...},
+  output_mapping: {...}
+})
+```
+
+**Check Validation Results:**
+- ✅ If validation passes → Proceed to creation
+- ❌ If validation fails → Fix errors and validate again
+- ⚠️ If warnings → Review and decide whether to fix
+
+**Never skip validation!** This prevents creating broken workflows that clutter the user's workspace.
+
+3. **Node Structure Requirements:**
+```javascript
+{
+  "name": "node_name",           // Required: string
+  "title": "Display Title",      // Required: string (optional for some nodes)
+  "description": "What it does",  // Required: string (optional for some nodes)
+  "node_type_name": "node_type",  // Required: exact from API
+  "input_config": {},             // Required: object (can be empty {})
+  "output_mapping": {},           // Required: object (use {} not null)
+  "connection": ""                // Required: string (use "" not null)
+}
+```
+
+4. **Critical Fixes:**
+   - Never use `null` for `output_mapping` → use `{}`
+   - Never use `null` for `connection` → use `""`
+   - Always include all required fields
+   - Use exact node type names
+
+5. **Only After Validation Passes - Create Workflow:**
+```javascript
+// Only call this after agenticflow_validate_workflow() succeeds
+agenticflow_create_workflow({
+  name: "Workflow Name",
+  description: "Workflow description",
+  nodes: [...],
+  input_schema: {...},
+  output_mapping: {...}
+})
+```
+
+**CRITICAL:** Never create without validating first!
+
+6. **Provide Direct Link:**
+```
+https://agenticflow.ai/app/workspaces/{workspace_id}/workflows/{workflow_id}/build
+```
+
+---
+
+### Phase 7: Post-Creation Documentation
+
+**Goal:** Provide user with complete setup and usage information.
+
+**Note:** Validation is done in Phase 6 BEFORE creation, not after!
+
+**Documentation Steps:**
+
+1. **Workflow Summary:**
+   - Confirm workflow was created successfully
+   - Provide direct link to workflow
+   - Explain what the workflow does
+   - Share validation results (already completed)
+
+2. **Validation Confirmation (Already Done):**
+   - Workflow structure validated ✓
+   - All fields properly configured ✓
+   - Data flow verified ✓
+   - Template variables correct ✓
+
+3. **MCP Connection Check:**
+   - All MCP actions have connections specified
+   - Connection UUIDs format correct
+   - Services properly identified
+
+**Documentation to Provide:**
+
+1. **Workflow Summary:**
+   - What the workflow does
+   - Input requirements
+   - Expected outputs
+
+2. **MCP Setup Instructions:**
+```markdown
+## Required MCP Connections
+
+1. **Gmail Connection**
+   - Go to agenticflow.ai/app/mcp
+   - Add Gmail provider
+   - Authorize your Google account
+   - Copy connection ID to workflow
+
+2. **Slack Connection**
+   - Add Slack provider
+   - Connect workspace
+   - Select channels for access
+```
+
+3. **Usage Guide:**
+   - How to run the workflow
+   - What inputs to provide
+   - How to interpret outputs
+
+4. **Limitations & Notes:**
+   - Rate limits
+   - Cost estimates
+   - Best practices
+   - Error handling
+
+---
+
+## 🎨 Workflow Design Patterns
+
+### Pattern 1: Data Collection → AI Processing → Distribution
+
+```
+Web Scraping → LLM Analysis → Multi-Channel Output
+   ↓                ↓                 ↓
+Research      Extract Insights   Email + Slack + Sheets
+```
+
+### Pattern 2: External Service Integration
+
+```
+MCP Data Source → AI Processing → MCP Action
+      ↓                  ↓              ↓
+  HubSpot CRM    Analyze & Segment  Send Campaigns
+```
+
+### Pattern 3: Parallel Processing
+
+```
+                  ┌─ Research Source 1 ─┐
+Input → Split →   ├─ Research Source 2 ─┤ → Combine → Output
+                  └─ Research Source 3 ─┘
+```
+
+---
+
+## 📋 Quick Reference Checklist
+
+**Before Building:**
+- [ ] Health check completed
+- [ ] Requirements fully understood
+- [ ] Node types identified
+- [ ] MCP services planned
+- [ ] Data flow mapped
+- [ ] Input schema designed
+
+**During Building:**
+- [ ] All required fields included
+- [ ] Template variables correct
+- [ ] Connection fields proper format
+- [ ] No null values for objects
+- [ ] Node names unique and descriptive
+
+**After Building:**
+- [ ] Workflow created successfully
+- [ ] Direct link provided
+- [ ] MCP setup documented
+- [ ] Usage instructions clear
+- [ ] Limitations noted
+
+---
+
+## 💡 Pro Tips
+
+1. **Think Hybrid:** Always consider both standard nodes AND MCP integrations
+2. **Start Simple:** Build core functionality first, then add enhancements
+3. **Use Examples:** Reference `references/examples/workflows/` for patterns
+4. **Validate Early:** Check field requirements before building
+5. **Document Well:** Clear MCP setup instructions prevent user confusion
+
+---
+
+**Next Steps:**
+- Review `references/node_types.md` for node selection
+- Check `references/workflow_guide.md` for patterns
+- See `references/examples/workflows/` for real examples
+# Node Selection Strategy Guide
+
+Complete guide for selecting the right node types for any workflow requirement.
+
+## 🎯 Selection Philosophy
+
+**Key Principle:** Choose the simplest, most appropriate node that fulfills the requirement while considering:
+- Connection requirements (some nodes need external connections)
+- Cost efficiency (credits per execution)
+- Feature capabilities
+- Output format compatibility with downstream nodes
+
+---
+
+## 📊 Node Categories & When to Use
+
+### 1. AI & LLM Nodes (20 nodes)
+
+**Use for:** Intelligent processing, text generation, analysis, decision-making
+
+#### Primary Choices
+
+**`llm` - General Purpose AI** ⭐ MOST VERSATILE
+- **Best for:** Any AI processing task
+- **Connection:** None required
+- **Models:** DeepSeek V3, Claude 3.5 Sonnet, GPT-4o-mini, GPT-4o
+- **Cost:** Varies by model
+- **Output field:** `.content`
+- **Use when:** You need flexible AI processing without service lock-in
+
+```javascript
+{
+  "node_type_name": "llm",
+  "input_config": {
+    "model": "DeepSeek V3",  // Cost-effective
+    "temperature": 0.3,
+    "max_tokens": 4000,
+    "human_message": "Process this: {{input_data}}",
+    "system_message": "You are an expert..."
+  }
+}
+```
+
+**`claude_ask` - Claude-Specific**
+- **Best for:** Tasks requiring Claude's specific capabilities
+- **Connection:** Claude Connection required
+- **Cost:** 4 credits + PML $0.01
+- **Output field:** `.answer`
+- **Use when:** User specifically wants Claude or needs citations
+
+**`openai_ask_chat_gpt` - ChatGPT-Specific**
+- **Best for:** ChatGPT-specific features
+- **Connection:** OpenAI Connection required
+- **Output field:** `.response`
+- **Use when:** User prefers OpenAI ecosystem
+
+**`openai_ask_assistant` - GPT Assistants**
+- **Best for:** Using pre-configured GPT assistants
+- **Connection:** OpenAI Connection required
+- **Use when:** Leveraging existing assistant configurations
+
+#### Model Selection Guide
+
+**DeepSeek V3:**
+- Best for: Simple tasks, cost-effective processing
+- Speed: Fast
+- Quality: Good for straightforward tasks
+
+**Claude 3.5 Sonnet:**
+- Best for: Complex analysis, nuanced understanding
+- Speed: Medium
+- Quality: Excellent for complex reasoning
+
+**GPT-4o-mini:**
+- Best for: General tasks, good balance
+- Speed: Fast
+- Quality: Very good for most use cases
+
+**GPT-4o:**
+- Best for: Most complex reasoning tasks
+- Speed: Medium
+- Quality: Best available
+
+---
+
+### 2. Web Research & Search Nodes (6 nodes)
+
+**Use for:** Gathering information from the internet
+
+**`perplexity_search` - AI-Powered Research** ⭐ RECOMMENDED
+- **Best for:** Comprehensive research with citations
+- **Connection:** Perplexity required
+- **Output:** Structured results with sources
+- **Output field:** `.response`
+- **Use when:** Need accurate, cited research
+
+**`google_search` - Google Results**
+- **Best for:** Simple web searches
+- **Connection:** PixelML required
+- **Output:** Organic and paid results
+- **Use when:** Need Google-specific results
+
+**`tavily_search` - Fast Web Search**
+- **Best for:** Quick comprehensive searches
+- **Output:** Results with direct answers
+- **Use when:** Speed is priority
+
+**`research_deep_research` - In-Depth Analysis**
+- **Best for:** Thorough research projects
+- **Use when:** Need comprehensive analysis
+
+---
+
+### 3. Web Scraping Nodes (9 nodes)
+
+**Use for:** Extracting data from specific websites
+
+**`web_scraping` - Simple Scraping** ⭐ START HERE
+- **Best for:** Basic content extraction
+- **Connection:** None required
+- **Output field:** `.scraped_content`
+- **Max tokens:** Configurable
+- **Use when:** Simple page content needed
+
+```javascript
+{
+  "node_type_name": "web_scraping",
+  "input_config": {
+    "web_url": "{{target_url}}",
+    "max_tokens": 10000,
+    "include_images": false,
+    "include_links": false
+  }
+}
+```
+
+**`firecrawl_scrape` - Advanced Scraping**
+- **Best for:** JavaScript-heavy sites, complex pages
+- **Features:** JS rendering, screenshots
+- **Use when:** Simple scraping fails
+
+**`firecrawl_crawl` - Multi-Page Scraping**
+- **Best for:** Scraping entire website sections
+- **Use when:** Need multiple related pages
+
+**`linkedin_scrape_profile` / `linkedin_scrape_company`**
+- **Best for:** LinkedIn data extraction
+- **Use when:** Specifically targeting LinkedIn
+
+**`web_scraping_apify` - Advanced Features**
+- **Connection:** PixelML required
+- **Use when:** Need advanced scraping capabilities
+
+---
+
+### 4. Data Extraction & Processing Nodes (4 nodes)
+
+**Use for:** Converting unstructured data to structured formats
+
+**`openai_extract_structured_data` - JSON Extraction** ⭐ RECOMMENDED
+- **Best for:** Reliable JSON schema extraction
+- **Connection:** OpenAI recommended
+- **Provides:** Guaranteed JSON structure
+- **Use when:** Need structured data output
+
+```javascript
+{
+  "node_type_name": "openai_extract_structured_data",
+  "input_config": {
+    "model": "gpt-4o-mini",
+    "input_text": "{{unstructured_text}}",
+    "json_schema": {
+      "type": "object",
+      "properties": {
+        "name": {"type": "string"},
+        "email": {"type": "string"},
+        "price": {"type": "number"}
+      },
+      "required": ["name", "email"]
+    }
+  }
+}
+```
+
+**`claude_extract_structured_data` - Alternative**
+- **Best for:** Claude-based extraction
+- **Use when:** Prefer Claude or OpenAI unavailable
+
+**`string_to_json` - Simple Conversion**
+- **Best for:** Converting string representations to JSON
+- **Use when:** Data already in JSON-like format
+
+**`optical_character_recognition` - OCR**
+- **Best for:** Extracting text from images
+- **Use when:** Processing scanned documents, images with text
+
+---
+
+### 5. Image Generation & Processing Nodes (13 nodes)
+
+**Use for:** Creating and manipulating images
+
+**`generate_image` - General Image Creation** ⭐ START HERE
+- **Best for:** Creating images from prompts
+- **Models:** DALL-E 3, Midjourney, Stable Diffusion
+- **Output field:** `.image_url`
+
+```javascript
+{
+  "node_type_name": "generate_image",
+  "input_config": {
+    "prompt": "{{image_description}}",
+    "model": "dall-e-3",
+    "size": "1024x1024",
+    "quality": "standard"
+  }
+}
+```
+
+**`generate_image_v2` - Advanced Generation**
+- **Best for:** More control over image parameters
+- **Use when:** Need specific models or settings
+
+**`describe_image` - Image Analysis**
+- **Best for:** Understanding image content
+- **Output:** Detailed descriptions, objects, text
+- **Use when:** Need to analyze existing images
+
+**`pml_edit_image` - Image Editing**
+- **Best for:** Modifying existing images
+- **Use when:** Need to edit rather than create
+
+**`enhance_image_v2` - Image Enhancement**
+- **Best for:** Upscaling, improving quality
+- **Use when:** Need to improve image quality
+
+---
+
+### 6. Video Processing Nodes (14 nodes)
+
+**Use for:** Creating and editing video content
+
+**`text_to_video` - Text to Video**
+- **Best for:** Creating videos from text prompts
+- **Use when:** Need video content from descriptions
+
+**`image_to_video` - Image Animation**
+- **Best for:** Animating static images
+- **Use when:** Have images to animate
+
+**`render_video` - Video Rendering**
+- **Best for:** Creating videos from templates
+- **Use when:** Need structured video creation
+
+**`google_gen_ai_generate_veo_video` - Google Veo**
+- **Best for:** Advanced video generation
+- **Connection:** Google Gen AI required
+
+---
+
+### 7. Audio & Speech Nodes (5 nodes)
+
+**Use for:** Voice synthesis and transcription
+
+**`text_to_speech` - TTS** ⭐ RECOMMENDED
+- **Best for:** Converting text to speech
+- **Use when:** Need voice output
+
+**`speech_to_text` - Transcription**
+- **Best for:** Converting audio to text
+- **Use when:** Processing voice input
+
+**`openai_text_to_speech` - OpenAI TTS**
+- **Connection:** OpenAI required
+- **Best for:** High-quality OpenAI voices
+
+**`text_to_music` - Music Generation**
+- **Best for:** Creating background music
+- **Use when:** Need audio content
+
+---
+
+### 8. Document Processing Nodes (2 nodes)
+
+**Use for:** Working with documents and text formats
+
+**`url_to_markdown` - Web to Markdown**
+- **Best for:** Converting web pages to clean markdown
+- **Use when:** Need formatted text extraction
+
+---
+
+### 9. Email & Communication Nodes (5 nodes)
+
+**Use for:** Sending emails (for advanced needs, use MCP)
+
+**`send_email` - Basic Email**
+- **Best for:** Simple email sending
+- **Use when:** Basic email needs
+
+**For advanced email:**
+- Use MCP: `GMAIL-SEND-EMAIL`, `SENDGRID-SEND-BULK-EMAIL`
+
+---
+
+### 10. File Storage & Management Nodes (12 nodes)
+
+**Use for:** File operations and storage
+
+**`drive_*` nodes - OneDrive Integration**
+- `drive_create_folder`
+- `drive_upload_file`
+- `drive_get_item`
+- `drive_list_items`
+- `drive_delete_item`
+
+**`export_data_to_file` - Export Data**
+- **Best for:** Saving workflow results to files
+- **Formats:** JSON, CSV, TXT, XML
+
+---
+
+### 11. API & Integration Nodes (3 nodes)
+
+**Use for:** Connecting to external services
+
+**`api_call` - Custom HTTP Requests** ⭐ VERSATILE
+- **Best for:** Any REST API integration
+- **Methods:** GET, POST, PUT, DELETE, PATCH
+- **Use when:** Need custom API integration
+
+```javascript
+{
+  "node_type_name": "api_call",
+  "input_config": {
+    "url": "{{api_endpoint}}",
+    "method": "GET",
+    "headers": {
+      "Content-Type": "application/json",
+      "Authorization": "Bearer {{api_token}}"
+    },
+    "body": {},
+    "response_type": "json"
+  }
+}
+```
+
+**`mcp_run_action` - MCP Integration** ⭐ POWERFUL
+- **Best for:** 2,500+ service integrations
+- **Use when:** Integrating Gmail, Slack, HubSpot, Shopify, etc.
+- **See:** `references/mcp_integrations.md`
+
+```javascript
+{
+  "node_type_name": "mcp_run_action",
+  "input_config": {
+    "action": "GMAIL-SEND-EMAIL",
+    "input_params": {
+      "instruction": "Send email to {{recipient}} with content: {{content}}"
+    }
+  },
+  "connection": "{{__app_connections__['gmail-connection-id']}}"
+}
+```
+
+---
+
+## 🔄 Decision Flow Charts
+
+### Choosing AI/LLM Nodes
+
+```
+Need AI processing?
+  ↓
+Do you need a specific provider?
+  ├─ Yes: Use provider-specific node (claude_ask, openai_ask_chat_gpt)
+  └─ No: Use llm node (most flexible)
+       ↓
+  Choose model based on task:
+    ├─ Simple/Cost-effective: DeepSeek V3
+    ├─ Balanced: GPT-4o-mini
+    ├─ Complex reasoning: Claude 3.5 Sonnet
+    └─ Most advanced: GPT-4o
+```
+
+### Choosing Research Nodes
+
+```
+Need web information?
+  ↓
+What type?
+  ├─ Specific website content: web_scraping
+  ├─ General research: perplexity_search
+  ├─ Google results: google_search
+  └─ Fast comprehensive: tavily_search
+```
+
+### Choosing Integration Approach
+
+```
+Need external service?
+  ↓
+Is it a standard service (Gmail, Slack, HubSpot, etc.)?
+  ├─ Yes: Use mcp_run_action
+  └─ No: Does it have a REST API?
+       ├─ Yes: Use api_call
+       └─ No: May not be possible
+```
+
+---
+
+## 💡 Pro Tips
+
+### Connection vs No Connection
+
+**No Connection Required (Easier):**
+- `llm` (most AI tasks)
+- `web_scraping` (basic scraping)
+- `string_to_json`
+- Most utility nodes
+
+**Connection Required (More Setup):**
+- `claude_ask`, `openai_ask_chat_gpt` (provider-specific)
+- `perplexity_search` (Perplexity)
+- `mcp_run_action` (each service)
+- Provider-specific nodes
+
+**Recommendation:** Start with no-connection nodes when possible
+
+### Cost Considerations
+
+**Low Cost:**
+- `llm` with DeepSeek V3
+- `web_scraping`
+- Basic utility nodes
+
+**Medium Cost:**
+- `llm` with GPT-4o-mini
+- Search nodes
+- Basic AI nodes
+
+**Higher Cost:**
+- `llm` with Claude 3.5 Sonnet or GPT-4o
+- Advanced AI processing
+- Image/video generation
+
+### Output Field Reference
+
+| Node Type | Output Field |
+|-----------|--------------|
+| `llm` | `.content` |
+| `claude_ask` | `.answer` |
+| `openai_ask_chat_gpt` | `.response` |
+| `perplexity_search` | `.response` |
+| `web_scraping` | `.scraped_content` |
+| `openai_extract_structured_data` | `.extracted_data` |
+| `generate_image` | `.image_url` |
+| `mcp_run_action` | `.output` |
+| `api_call` | `.response` |
+
+---
+
+## 📚 Quick Reference by Use Case
+
+**Content Creation:**
+- Text: `llm`
+- Images: `generate_image`
+- Videos: `text_to_video`
+- Audio: `text_to_speech`
+
+**Data Collection:**
+- Web research: `perplexity_search`
+- Specific sites: `web_scraping`
+- APIs: `api_call` or `mcp_run_action`
+
+**Data Processing:**
+- Analysis: `llm`
+- Extraction: `openai_extract_structured_data`
+- Transformation: `llm` with specific prompts
+
+**External Services:**
+- Standard services: `mcp_run_action`
+- Custom APIs: `api_call`
+- Email: `send_email` or MCP
+
+**File Operations:**
+- Export: `export_data_to_file`
+- Storage: `drive_*` nodes
+
+---
+
+**Next Steps:**
+- Check `references/node_types.md` for complete node list
+- See `references/complete_node_types.md` for detailed schemas
+- Review `references/examples/workflows/` for real usage
+# MCP Integration Guide
+
+Complete guide for integrating 2,500+ external services into AgenticFlow workflows using Model Context Protocol (MCP).
+
+## 🌐 What is MCP?
+
+**Model Context Protocol (MCP)** enables AgenticFlow to connect to virtually any external service through AI-powered actions. Instead of configuring complex APIs, you write natural language instructions that the AI executes.
+
+**Key Benefits:**
+- Access 2,500+ services without coding
+- AI interprets your instructions
+- Handles authentication automatically
+- Simplifies complex API interactions
+
+---
+
+## 🎯 When to Use MCP
+
+### Use MCP Integration When:
+
+✅ User mentions external services:
+- CRM (HubSpot, Salesforce, Pipedrive)
+- Communication (Gmail, Slack, Teams, WhatsApp)
+- E-commerce (Shopify, WooCommerce, Stripe)
+- Productivity (Google Sheets, Notion, Airtable)
+- Marketing (Mailchimp, Facebook, LinkedIn)
+- Project Management (Asana, Trello, Jira)
+
+✅ Standard nodes don't provide the functionality
+
+✅ Need advanced features from specific platforms
+
+✅ Want to chain multiple service operations
+
+### Don't Use MCP When:
+
+❌ Simple operations available in standard nodes
+❌ No external service integration needed
+❌ User doesn't have access to required service
+❌ Cost-sensitive and standard nodes work
+
+---
+
+## 📋 MCP Action Structure
+
+### Basic MCP Node Format
+
+```javascript
+{
+  "name": "descriptive_action_name",
+  "title": "Human-Readable Action Title",
+  "description": "What this action does",
+  "node_type_name": "mcp_run_action",
+  "input_config": {
+    "action": "SERVICE-ACTION-NAME",
+    "input_params": {
+      "instruction": "Natural language instruction with {{template_variables}}"
+    }
+  },
+  "output_mapping": {},
+  "connection": "{{__app_connections__['connection-uuid']}}"
+}
+```
+
+### Key Components
+
+**1. Action Name**
+- Pattern: `SERVICE-ACTION-NAME` (all uppercase with hyphens)
+- Examples:
+  - `GMAIL-SEND-EMAIL`
+  - `GOOGLE_SHEETS-APPEND-ROW`
+  - `HUBSPOT-CREATE-CONTACT`
+  - `SLACK-SEND-MESSAGE`
+
+**2. Instruction**
+- Natural language describing what to do
+- Include template variables for dynamic data
+- Be specific about format and requirements
+- Example: `"Send email to {{recipient}} with subject '{{subject}}' and body: {{email_content}}"`
+
+**3. Connection**
+- Reference format: `{{__app_connections__['connection-uuid']}}`
+- Each service needs its own connection
+- User sets up at agenticflow.ai/app/mcp
+
+---
+
+## 🔧 Popular MCP Actions by Category
+
+### CRM & Sales
+
+**HubSpot**
+```javascript
+// Create Contact
+{
+  "action": "HUBSPOT-CREATE-CONTACT",
+  "input_params": {
+    "instruction": "Create contact with email {{email}}, name {{name}}, and company {{company}}"
+  }
+}
+
+// Update Deal
+{
+  "action": "HUBSPOT-UPDATE-DEAL",
+  "input_params": {
+    "instruction": "Update deal {{deal_id}} with amount {{amount}} and stage {{stage}}"
+  }
+}
+
+// Get Contacts
+{
+  "action": "HUBSPOT-GET-CONTACTS",
+  "input_params": {
+    "instruction": "Get all contacts created in the last 7 days with engagement scores"
+  }
+}
+```
+
+**Salesforce**
+```javascript
+// Create Lead
+{
+  "action": "SALESFORCE-CREATE-LEAD",
+  "input_params": {
+    "instruction": "Create lead from {{lead_data}} with company {{company_name}}"
+  }
+}
+
+// Update Opportunity
+{
+  "action": "SALESFORCE-UPDATE-OPPORTUNITY",
+  "input_params": {
+    "instruction": "Update opportunity {{opp_id}} status to {{status}}"
+  }
+}
+```
+
+**Pipedrive**
+```javascript
+// Add Person
+{
+  "action": "PIPEDRIVE-ADD-PERSON",
+  "input_params": {
+    "instruction": "Add person with name {{name}}, email {{email}}, and phone {{phone}}"
+  }
+}
+
+// Create Deal
+{
+  "action": "PIPEDRIVE-CREATE-DEAL",
+  "input_params": {
+    "instruction": "Create deal for {{person}} with value {{value}} in stage {{stage}}"
+  }
+}
+```
+
+---
+
+### Communication
+
+**Gmail**
+```javascript
+// Send Email
+{
+  "action": "GMAIL-SEND-EMAIL",
+  "input_params": {
+    "instruction": "Send email to {{recipient}} with subject '{{subject}}' and body: {{email_content}}"
+  }
+}
+
+// Search Emails
+{
+  "action": "GMAIL-SEARCH-EMAILS",
+  "input_params": {
+    "instruction": "Search for emails from {{sender}} in the last 7 days about {{topic}}"
+  }
+}
+
+// Create Draft
+{
+  "action": "GMAIL-CREATE-DRAFT",
+  "input_params": {
+    "instruction": "Create draft email to {{recipient}} with content: {{draft_content}}"
+  }
+}
+```
+
+**Slack**
+```javascript
+// Send Message
+{
+  "action": "SLACK-SEND-MESSAGE",
+  "input_params": {
+    "instruction": "Send message to {{channel}} with text: {{message_text}}"
+  }
+}
+
+// Create Channel
+{
+  "action": "SLACK-CREATE-CHANNEL",
+  "input_params": {
+    "instruction": "Create channel named {{channel_name}} with description {{description}}"
+  }
+}
+
+// Upload File
+{
+  "action": "SLACK-UPLOAD-FILE",
+  "input_params": {
+    "instruction": "Upload file {{file_url}} to channel {{channel}} with comment {{comment}}"
+  }
+}
+```
+
+**Microsoft Teams**
+```javascript
+// Create Meeting
+{
+  "action": "TEAMS-CREATE-MEETING",
+  "input_params": {
+    "instruction": "Create meeting on {{date}} at {{time}} with attendees {{attendees}}"
+  }
+}
+
+// Send Message
+{
+  "action": "TEAMS-SEND-MESSAGE",
+  "input_params": {
+    "instruction": "Send message to {{team_channel}} with content: {{message}}"
+  }
+}
+```
+
+---
+
+### E-commerce
+
+**Shopify**
+```javascript
+// Get Orders
+{
+  "action": "SHOPIFY-GET-ORDERS",
+  "input_params": {
+    "instruction": "Get all orders from the last 24 hours with total value over $100"
+  }
+}
+
+// Update Inventory
+{
+  "action": "SHOPIFY-UPDATE-INVENTORY",
+  "input_params": {
+    "instruction": "Update inventory for product {{product_id}} to {{quantity}} units"
+  }
+}
+
+// Create Product
+{
+  "action": "SHOPIFY-CREATE-PRODUCT",
+  "input_params": {
+    "instruction": "Create product with title {{title}}, price {{price}}, and description: {{description}}"
+  }
+}
+```
+
+**Stripe**
+```javascript
+// Create Charge
+{
+  "action": "STRIPE-CREATE-CHARGE",
+  "input_params": {
+    "instruction": "Charge {{amount}} to customer {{customer_id}} for {{description}}"
+  }
+}
+
+// Get Customer
+{
+  "action": "STRIPE-GET-CUSTOMER",
+  "input_params": {
+    "instruction": "Get customer details for {{customer_id}}"
+  }
+}
+
+// Create Subscription
+{
+  "action": "STRIPE-CREATE-SUBSCRIPTION",
+  "input_params": {
+    "instruction": "Create subscription for customer {{customer_id}} with plan {{plan_id}}"
+  }
+}
+```
+
+**WooCommerce**
+```javascript
+// Update Order
+{
+  "action": "WOOCOMMERCE-UPDATE-ORDER",
+  "input_params": {
+    "instruction": "Update order {{order_id}} status to {{status}}"
+  }
+}
+
+// Get Products
+{
+  "action": "WOOCOMMERCE-GET-PRODUCTS",
+  "input_params": {
+    "instruction": "Get all products in category {{category}} with stock status {{status}}"
+  }
+}
+```
+
+---
+
+### Productivity
+
+**Google Sheets**
+```javascript
+// Append Row
+{
+  "action": "GOOGLE_SHEETS-APPEND-ROW",
+  "input_params": {
+    "instruction": "Append row to sheet {{sheet_name}} with data: {{row_data}}"
+  }
+}
+
+// Update Cell
+{
+  "action": "GOOGLE_SHEETS-UPDATE-CELL",
+  "input_params": {
+    "instruction": "Update cell {{cell_reference}} in sheet {{sheet_name}} with value {{value}}"
+  }
+}
+
+// Get Data
+{
+  "action": "GOOGLE_SHEETS-GET-DATA",
+  "input_params": {
+    "instruction": "Get all data from range {{range}} in sheet {{sheet_name}}"
+  }
+}
+
+// Update Range
+{
+  "action": "GOOGLE_SHEETS-UPDATE-RANGE",
+  "input_params": {
+    "instruction": "Update range {{range}} with values: {{values}}"
+  }
+}
+```
+
+**Notion**
+```javascript
+// Create Page
+{
+  "action": "NOTION-CREATE-PAGE",
+  "input_params": {
+    "instruction": "Create page in database {{database_id}} with title {{title}} and content: {{content}}"
+  }
+}
+
+// Update Database
+{
+  "action": "NOTION-UPDATE-DATABASE",
+  "input_params": {
+    "instruction": "Update database entry {{entry_id}} with properties: {{properties}}"
+  }
+}
+
+// Search
+{
+  "action": "NOTION-SEARCH",
+  "input_params": {
+    "instruction": "Search for pages containing {{keyword}} in workspace"
+  }
+}
+```
+
+**Airtable**
+```javascript
+// Create Record
+{
+  "action": "AIRTABLE-CREATE-RECORD",
+  "input_params": {
+    "instruction": "Create record in table {{table_name}} with fields: {{fields}}"
+  }
+}
+
+// Find Records
+{
+  "action": "AIRTABLE-FIND-RECORDS",
+  "input_params": {
+    "instruction": "Find records in {{table_name}} where {{field}} equals {{value}}"
+  }
+}
+```
+
+---
+
+### Marketing
+
+**Mailchimp**
+```javascript
+// Add Subscriber
+{
+  "action": "MAILCHIMP-ADD-SUBSCRIBER",
+  "input_params": {
+    "instruction": "Add {{email}} to list {{list_id}} with tags {{tags}}"
+  }
+}
+
+// Create Campaign
+{
+  "action": "MAILCHIMP-CREATE-CAMPAIGN",
+  "input_params": {
+    "instruction": "Create campaign with subject {{subject}} for list {{list_id}} and content: {{content}}"
+  }
+}
+```
+
+**SendGrid**
+```javascript
+// Send Bulk Email
+{
+  "action": "SENDGRID-SEND-BULK-EMAIL",
+  "input_params": {
+    "instruction": "Send emails to {{recipients}} with template {{template_id}} and data: {{personalization}}"
+  }
+}
+```
+
+**Facebook**
+```javascript
+// Create Ad
+{
+  "action": "FACEBOOK-CREATE-AD",
+  "input_params": {
+    "instruction": "Create ad with creative {{creative_id}} targeting {{audience}} with budget {{budget}}"
+  }
+}
+
+// Get Insights
+{
+  "action": "FACEBOOK-GET-INSIGHTS",
+  "input_params": {
+    "instruction": "Get ad insights for campaign {{campaign_id}} from {{start_date}} to {{end_date}}"
+  }
+}
+```
+
+**LinkedIn**
+```javascript
+// Create Post
+{
+  "action": "LINKEDIN-CREATE-POST",
+  "input_params": {
+    "instruction": "Create post with text: {{content}} and image {{image_url}}"
+  }
+}
+
+// Get Profile
+{
+  "action": "LINKEDIN-GET-PROFILE",
+  "input_params": {
+    "instruction": "Get profile information for user {{user_id}}"
+  }
+}
+```
+
+---
+
+## 🔄 Hybrid Workflow Patterns
+
+### Pattern 1: Data Collection + AI Processing + Multi-Channel Distribution
+
+```javascript
+{
+  "nodes": [
+    // 1. Collect data from CRM
+    {
+      "name": "get_crm_contacts",
+      "node_type_name": "mcp_run_action",
+      "input_config": {
+        "action": "HUBSPOT-GET-CONTACTS",
+        "input_params": {
+          "instruction": "Get contacts created in last 7 days with engagement scores"
+        }
+      },
+      "connection": "{{__app_connections__['hubspot-conn']}}"
+    },
+
+    // 2. AI Analysis
+    {
+      "name": "analyze_contacts",
+      "node_type_name": "llm",
+      "input_config": {
+        "model": "DeepSeek V3",
+        "human_message": "Analyze these contacts and segment into high/medium/low priority: {{get_crm_contacts.output}}"
+      }
+    },
+
+    // 3. Send to Google Sheets
+    {
+      "name": "update_sheet",
+      "node_type_name": "mcp_run_action",
+      "input_config": {
+        "action": "GOOGLE_SHEETS-APPEND-ROW",
+        "input_params": {
+          "instruction": "Append analysis to sheet 'Contact Analysis' with data: {{analyze_contacts.content}}"
+        }
+      },
+      "connection": "{{__app_connections__['sheets-conn']}}"
+    },
+
+    // 4. Notify team via Slack
+    {
+      "name": "notify_team",
+      "node_type_name": "mcp_run_action",
+      "input_config": {
+        "action": "SLACK-SEND-MESSAGE",
+        "input_params": {
+          "instruction": "Send to #sales channel: New contact analysis complete with {{analyze_contacts.content}}"
+        }
+      },
+      "connection": "{{__app_connections__['slack-conn']}}"
+    }
+  ]
+}
+```
+
+### Pattern 2: Web Research + CRM Update + Email Campaign
+
+```javascript
+{
+  "nodes": [
+    // 1. Research company
+    {
+      "name": "research_company",
+      "node_type_name": "perplexity_search",
+      "input_config": {
+        "query": "{{company_name}} latest news and funding rounds"
+      }
+    },
+
+    // 2. Extract insights
+    {
+      "name": "extract_insights",
+      "node_type_name": "llm",
+      "input_config": {
+        "model": "Claude 3.5 Sonnet",
+        "human_message": "Extract key insights from: {{research_company.response}}"
+      }
+    },
+
+    // 3. Update CRM
+    {
+      "name": "update_crm",
+      "node_type_name": "mcp_run_action",
+      "input_config": {
+        "action": "SALESFORCE-UPDATE-OPPORTUNITY",
+        "input_params": {
+          "instruction": "Update opportunity notes with research: {{extract_insights.content}}"
+        }
+      },
+      "connection": "{{__app_connections__['salesforce-conn']}}"
+    },
+
+    // 4. Generate personalized email
+    {
+      "name": "generate_email",
+      "node_type_name": "llm",
+      "input_config": {
+        "model": "GPT-4o-mini",
+        "human_message": "Write personalized email based on insights: {{extract_insights.content}}"
+      }
+    },
+
+    // 5. Send via Gmail
+    {
+      "name": "send_email",
+      "node_type_name": "mcp_run_action",
+      "input_config": {
+        "action": "GMAIL-SEND-EMAIL",
+        "input_params": {
+          "instruction": "Send email generated in {{generate_email.content}} to {{recipient_email}}"
+        }
+      },
+      "connection": "{{__app_connections__['gmail-conn']}}"
+    }
+  ]
+}
+```
+
+---
+
+## 🔐 Connection Management
+
+### Setting Up MCP Connections
+
+**User Instructions:**
+
+1. **Navigate to MCP Settings:**
+   ```
+   Go to: https://agenticflow.ai/app/mcp
+   ```
+
+2. **Add Provider:**
+   - Click "Add Provider"
+   - Select service (Gmail, Slack, HubSpot, etc.)
+   - Click "Connect"
+
+3. **Authorize:**
+   - Follow OAuth flow
+   - Grant required permissions
+   - Confirm access
+
+4. **Copy Connection ID:**
+   - Connection will be created with UUID
+   - Copy for use in workflows
+
+5. **Use in Workflow:**
+   ```javascript
+   "connection": "{{__app_connections__['copied-uuid-here']}}"
+   ```
+
+### Connection Requirements by Service
+
+| Service | Auth Type | Permissions Needed |
+|---------|-----------|-------------------|
+| Gmail | OAuth | Send, Read emails |
+| Google Sheets | OAuth | Edit spreadsheets |
+| Slack | OAuth | Post messages, Manage channels |
+| HubSpot | API Key | CRM access |
+| Salesforce | OAuth | CRM read/write |
+| Shopify | API Key | Store management |
+| Stripe | API Key | Payment processing |
+
+---
+
+## 💡 Best Practices
+
+### 1. Instruction Design
+
+**Good Instructions:**
+✅ Clear and specific
+✅ Include all necessary data
+✅ Specify format when needed
+✅ Use template variables
+
+```javascript
+"Send email to {{recipient}} with subject 'Order Confirmation #{{order_id}}' and body: Thank you for your order of {{product_name}}. Total: ${{total}}."
+```
+
+**Bad Instructions:**
+❌ Vague
+❌ Missing data
+❌ Unclear format
+
+```javascript
+"Send an email about the order"
+```
+
+### 2. Error Handling
+
+Always plan for:
+- Connection failures
+- Rate limits
+- Invalid data
+- Service outages
+
+### 3. Cost Optimization
+
+- Use MCP only when needed
+- Batch operations when possible
+- Cache results to avoid redundant calls
+
+### 4. Security
+
+- Never hardcode credentials
+- Use connections for auth
+- Validate data before sending
+- Follow service best practices
+
+---
+
+## 🚀 Quick Start Template
+
+```javascript
+{
+  "name": "mcp_action_name",
+  "title": "Action Title",
+  "description": "What this does",
+  "node_type_name": "mcp_run_action",
+  "input_config": {
+    "action": "SERVICE-ACTION-NAME",
+    "input_params": {
+      "instruction": "Clear instruction with {{variables}}"
+    }
+  },
+  "output_mapping": {},
+  "connection": "{{__app_connections__['connection-uuid']}}"
+}
+```
+
+---
+
+**Next Steps:**
+- Check `references/mcp_integrations.md` for full list
+- See `references/examples/workflows/` for MCP usage examples
+- Review workflow patterns in `references/workflow_guide.md`
+# Technical Requirements & Common Fixes
+
+Complete technical reference for creating valid AgenticFlow workflows with proper field formats and structures.
+
+## 🔧 Node Structure Requirements
+
+### Complete Node Template
+
+Every node in a workflow must have these fields:
+
+```javascript
+{
+  "name": "unique_node_name",           // Required: string, unique within workflow
+  "title": "Display Title",              // Optional but recommended: string
+  "description": "What this node does",  // Optional but recommended: string
+  "node_type_name": "exact_node_type",  // Required: exact match from API
+  "input_config": {},                    // Required: object (can be empty {})
+  "output_mapping": {},                  // Required: object (NEVER null, use {})
+  "connection": ""                       // Required: string (NEVER null, use "")
+}
+```
+
+### Field-by-Field Breakdown
+
+#### 1. `name` (REQUIRED)
+- **Type:** string
+- **Rules:**
+  - Must be unique within workflow
+  - Use snake_case: `get_customer_data`, `send_notification`
+  - Descriptive and meaningful
+  - No spaces or special characters except underscore
+- **Examples:**
+  ```javascript
+  "name": "scrape_competitor_prices"
+  "name": "analyze_with_llm"
+  "name": "send_slack_alert"
+  ```
+
+#### 2. `title` (OPTIONAL but recommended)
+- **Type:** string
+- **Purpose:** Human-readable display name
+- **Examples:**
+  ```javascript
+  "title": "Scrape Competitor Prices"
+  "title": "Analyze with AI"
+  "title": "Send Slack Alert"
+  ```
+
+#### 3. `description` (OPTIONAL but recommended)
+- **Type:** string
+- **Purpose:** Explain what this node does
+- **Examples:**
+  ```javascript
+  "description": "Scrapes pricing data from competitor websites"
+  "description": "Uses LLM to analyze pricing trends"
+  "description": "Notifies team in Slack channel"
+  ```
+
+#### 4. `node_type_name` (REQUIRED)
+- **Type:** string
+- **Rules:**
+  - MUST be exact match from `agenticflow_list_node_types()`
+  - Case-sensitive
+  - Check spelling carefully
+- **How to verify:**
+  ```javascript
+  // Search for the node type
+  agenticflow_search_node_types({name: 'llm'})
+
+  // Or list all to find exact name
+  agenticflow_list_node_types({limit: 200})
+  ```
+- **Common node types:**
+  ```javascript
+  "node_type_name": "llm"
+  "node_type_name": "web_scraping"
+  "node_type_name": "perplexity_search"
+  "node_type_name": "mcp_run_action"
+  "node_type_name": "openai_extract_structured_data"
+  "node_type_name": "generate_image"
+  ```
+
+#### 5. `input_config` (REQUIRED)
+- **Type:** object
+- **Rules:**
+  - NEVER null
+  - Can be empty `{}`
+  - Must match node type's input schema
+  - Check `references/complete_node_types.md` for required fields
+- **Examples:**
+  ```javascript
+  // LLM node
+  "input_config": {
+    "model": "DeepSeek V3",
+    "temperature": 0.3,
+    "max_tokens": 4000,
+    "human_message": "Analyze this data: {{previous_node.output}}",
+    "system_message": "You are an expert analyst"
+  }
+
+  // Web scraping node
+  "input_config": {
+    "web_url": "{{target_url}}",
+    "max_tokens": 10000,
+    "include_images": false
+  }
+
+  // MCP action node
+  "input_config": {
+    "action": "GMAIL-SEND-EMAIL",
+    "input_params": {
+      "instruction": "Send email to {{recipient}} with content: {{content}}"
+    }
+  }
+  ```
+
+#### 6. `output_mapping` (REQUIRED)
+- **Type:** object
+- **Rules:**
+  - NEVER null (use `{}` instead)
+  - Maps node outputs to custom names
+  - Usually empty `{}` unless custom mapping needed
+- **Examples:**
+  ```javascript
+  // Usually empty
+  "output_mapping": {}
+
+  // Custom mapping (rare)
+  "output_mapping": {
+    "custom_name": "{{node_name.field}}"
+  }
+  ```
+
+#### 7. `connection` (REQUIRED)
+- **Type:** string
+- **Rules:**
+  - NEVER null (use `""` instead)
+  - Empty string `""` if no connection needed
+  - MCP connection reference: `{{__app_connections__['uuid']}}`
+- **Examples:**
+  ```javascript
+  // No connection needed
+  "connection": ""
+
+  // MCP connection
+  "connection": "{{__app_connections__['gmail-connection-id']}}"
+  ```
+
+---
+
+## ⚠️ Common Errors & Fixes
+
+### Error 1: Null Values
+
+❌ **WRONG:**
+```javascript
+{
+  "output_mapping": null,
+  "connection": null
+}
+```
+
+✅ **CORRECT:**
+```javascript
+{
+  "output_mapping": {},
+  "connection": ""
+}
+```
+
+### Error 2: Missing Required Fields
+
+❌ **WRONG:**
+```javascript
+{
+  "name": "my_node",
+  "node_type_name": "llm"
+  // Missing input_config, output_mapping, connection
+}
+```
+
+✅ **CORRECT:**
+```javascript
+{
+  "name": "my_node",
+  "node_type_name": "llm",
+  "input_config": {
+    "model": "DeepSeek V3",
+    "human_message": "Process this data"
+  },
+  "output_mapping": {},
+  "connection": ""
+}
+```
+
+### Error 3: Wrong Node Type Name
+
+❌ **WRONG:**
+```javascript
+{
+  "node_type_name": "LLM"  // Wrong case
+}
+```
+
+```javascript
+{
+  "node_type_name": "llm_node"  // Wrong name
+}
+```
+
+✅ **CORRECT:**
+```javascript
+{
+  "node_type_name": "llm"  // Exact match from API
+}
+```
+
+### Error 4: Invalid Template Variables
+
+❌ **WRONG:**
+```javascript
+{
+  "human_message": "Process ${previous_node.output}"  // Wrong syntax
+}
+```
+
+```javascript
+{
+  "human_message": "Process {{nonexistent_node.data}}"  // Node doesn't exist
+}
+```
+
+✅ **CORRECT:**
+```javascript
+{
+  "human_message": "Process {{previous_node.output}}"  // Correct syntax and existing node
+}
+```
+
+### Error 5: Missing Input Config Fields
+
+❌ **WRONG:**
+```javascript
+{
+  "node_type_name": "llm",
+  "input_config": {
+    "human_message": "Process this"
+    // Missing required 'model' field
+  }
+}
+```
+
+✅ **CORRECT:**
+```javascript
+{
+  "node_type_name": "llm",
+  "input_config": {
+    "model": "DeepSeek V3",
+    "human_message": "Process this"
+  }
+}
+```
+
+---
+
+## 🔗 Template Variables
+
+### Syntax Rules
+
+**Correct Format:**
+```javascript
+{{node_name.field}}
+{{input_parameter}}
+{{__app_connections__['connection-id']}}
+```
+
+**Common Mistakes:**
+```javascript
+${node_name.field}        // Wrong - not JavaScript template literal
+{node_name.field}         // Wrong - single braces
+{{ node_name.field }}     // Wrong - spaces inside braces
+{{node_name}}            // Incomplete - needs field
+```
+
+### Output Field Reference
+
+| Node Type | Primary Output Field |
+|-----------|---------------------|
+| `llm` | `.content` |
+| `claude_ask` | `.answer` |
+| `openai_ask_chat_gpt` | `.response` |
+| `perplexity_search` | `.response` |
+| `google_search` | `.organic_results` |
+| `web_scraping` | `.scraped_content` |
+| `openai_extract_structured_data` | `.extracted_data` |
+| `generate_image` | `.image_url` |
+| `describe_image` | `.description` |
+| `mcp_run_action` | `.output` |
+| `api_call` | `.response` |
+
+### Accessing Nested Fields
+
+```javascript
+// Simple field
+{{node_name.content}}
+
+// Nested object
+{{node_name.response.data.items}}
+
+// Array element
+{{node_name.results[0].title}}
+
+// Deep nesting
+{{node_name.response.data.items[0].properties.name}}
+```
+
+### Input Parameters
+
+```javascript
+// Direct input variable
+{{company_name}}
+{{user_email}}
+{{search_query}}
+
+// In input_schema
+{
+  "input_schema": {
+    "properties": {
+      "company_name": {
+        "type": "string"
+      }
+    }
+  }
+}
+
+// Use in node
+{
+  "input_config": {
+    "human_message": "Research company: {{company_name}}"
+  }
+}
+```
+
+---
+
+## 📝 Workflow-Level Requirements
+
+### Complete Workflow Structure
+
+```javascript
+{
+  "name": "Workflow Name",
+  "description": "What this workflow does",
+  "nodes": [
+    // Array of node objects
+    {
+      "name": "node1",
+      "node_type_name": "llm",
+      "input_config": {},
+      "output_mapping": {},
+      "connection": ""
+    },
+    {
+      "name": "node2",
+      "node_type_name": "web_scraping",
+      "input_config": {},
+      "output_mapping": {},
+      "connection": ""
+    }
+  ],
+  "input_schema": {
+    "type": "object",
+    "title": "User inputs",
+    "required": [],
+    "properties": {
+      // Input field definitions
+    }
+  },
+  "output_mapping": {
+    // Final workflow outputs
+  }
+}
+```
+
+### Input Schema Structure
+
+```javascript
+{
+  "input_schema": {
+    "type": "object",
+    "title": "User inputs",
+    "description": "Inputs for the workflow",
+    "required": ["required_field"],
+    "properties": {
+      "field_name": {
+        "type": "string",              // string, number, boolean, array, object
+        "title": "Display Label",
+        "description": "Help text",
+        "ui_metadata": {
+          "type": "short_text",        // short_text, long_text, dropdown, multi_select
+          "order": 0,
+          "placeholder": "Example...",
+          "value": "default_value"
+        }
+      }
+    }
+  }
+}
+```
+
+### UI Metadata Field Types
+
+**`short_text`** - Single line text input
+```javascript
+{
+  "type": "string",
+  "ui_metadata": {
+    "type": "short_text",
+    "placeholder": "Enter company name"
+  }
+}
+```
+
+**`long_text`** - Multi-line text area
+```javascript
+{
+  "type": "string",
+  "ui_metadata": {
+    "type": "long_text",
+    "placeholder": "Enter detailed description..."
+  }
+}
+```
+
+**`dropdown`** - Single selection dropdown
+```javascript
+{
+  "type": "string",
+  "ui_metadata": {
+    "type": "dropdown",
+    "options": ["Option 1", "Option 2", "Option 3"],
+    "value": "Option 1"
+  }
+}
+```
+
+**`multi_select`** - Multiple selection
+```javascript
+{
+  "type": "array",
+  "items": {"type": "string"},
+  "ui_metadata": {
+    "type": "multi_select",
+    "options": ["Tag1", "Tag2", "Tag3"],
+    "value": ["Tag1"]
+  }
+}
+```
+
+---
+
+## 🔄 Execution Order & Dependencies
+
+### Sequential Execution
+
+Nodes execute in array order by default:
+
+```javascript
+{
+  "nodes": [
+    {"name": "step1", ...},   // Executes first
+    {"name": "step2", ...},   // Executes second
+    {"name": "step3", ...}    // Executes third
+  ]
+}
+```
+
+### Parallel Execution with `prevNodeName`
+
+**For workflow building only** (not for `agenticflow_create_workflow`):
+
+```javascript
+{
+  "nodes": [
+    {
+      "name": "start",
+      "prevNodeName": null  // First node
+    },
+    {
+      "name": "parallel1",
+      "prevNodeName": "start"  // Waits for start
+    },
+    {
+      "name": "parallel2",
+      "prevNodeName": "start"  // Also waits for start, runs parallel to parallel1
+    },
+    {
+      "name": "final",
+      "prevNodeName": "parallel2"  // Waits for both parallel nodes
+    }
+  ]
+}
+```
+
+---
+
+## ✅ Pre-Flight Checklist
+
+Before creating a workflow, verify:
+
+**Node Level:**
+- [ ] All nodes have unique names
+- [ ] `node_type_name` exactly matches API
+- [ ] `input_config` has all required fields
+- [ ] `output_mapping` is `{}` not `null`
+- [ ] `connection` is `""` not `null` (or proper UUID if needed)
+- [ ] Template variables reference existing nodes
+- [ ] Template variables use correct output fields
+
+**Workflow Level:**
+- [ ] `name` is descriptive and clear
+- [ ] `description` explains purpose
+- [ ] `nodes` array is not empty
+- [ ] `input_schema` properly structured
+- [ ] `input_schema` has `ui_metadata` for user experience
+- [ ] `output_mapping` configured for final results
+- [ ] All MCP connections documented
+
+**Data Flow:**
+- [ ] Each node has the data it needs from previous nodes
+- [ ] No circular dependencies
+- [ ] Output fields correctly referenced
+- [ ] Input parameters defined in schema
+
+---
+
+## 🚀 Quick Validation
+
+### Minimal Valid Node
+
+```javascript
+{
+  "name": "test_node",
+  "node_type_name": "llm",
+  "input_config": {
+    "model": "DeepSeek V3",
+    "human_message": "Test"
+  },
+  "output_mapping": {},
+  "connection": ""
+}
+```
+
+### Minimal Valid Workflow
+
+```javascript
+{
+  "name": "Test Workflow",
+  "description": "Simple test",
+  "nodes": [
+    {
+      "name": "test_node",
+      "node_type_name": "llm",
+      "input_config": {
+        "model": "DeepSeek V3",
+        "human_message": "{{user_input}}"
+      },
+      "output_mapping": {},
+      "connection": ""
+    }
+  ],
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "user_input": {
+        "type": "string",
+        "title": "Your Input"
+      }
+    }
+  },
+  "output_mapping": {}
+}
+```
+
+---
+
+### Phase 8: Building the AI Agent (The Master Layer)
+
+**Goal:** Create a specialized AI entity that uses your workflows as tools to interact with users.
+
+**Build Steps:**
+
+1. **Define Identity:**
+   - **Name**: Clear role-based name (e.g., "Customer Support Agent").
+   - **Instructions**: Detailed system prompt defining personality, constraints, and how to use tools.
+
+2. **Select Tools (Workflows):**
+   - Identify which `workflow_id`s this agent should be able to trigger.
+   - Map user intents to specific workflows.
+
+3. **Creation Call:**
+```javascript
+// Call after creating the necessary workflows
+agenticflow_create_agent({
+  name: "Price Monitor Agent",
+  instructions: "You are a price monitoring expert. Use the 'scr_price_wf' tool to check prices when users ask...",
+  data: {
+    tools: ["workflow-uuid-1", "workflow-uuid-2"],
+    knowledge_sets: []
+  },
+  email: "user@example.com"
+})
+```
+
+---
+
+## 📚 Reference Priority
+
+When building solutions, check references in this order:
+
+1. **`references/node_types.md`** - Choose right node type & field overview
+2. **`references/mcp_integrations.md`** - Find external service actions
+3. **`references/workflow_guide.md`** - Real world patterns & examples
+4. **This guide (`GUIDES.md`)** - Creation process & technical requirements
+5. **`OPTIMIZATION.md`** - System philosophy & architecture
+
+---
+
+**Next Steps:**
+- Validate workflows before creation using `agenticflow_validate_workflow()`
+- Call `agenticflow_create_agent()` after creating tools (workflows)
+- Test your solution in the AgenticFlow dashboard