diff --git a/apps/docs/content/docs/en/blocks/agent.mdx b/apps/docs/content/docs/en/blocks/agent.mdx index f9f95c563a..6936ce4807 100644 --- a/apps/docs/content/docs/en/blocks/agent.mdx +++ b/apps/docs/content/docs/en/blocks/agent.mdx @@ -175,33 +175,7 @@ Use a `Memory` block with a consistent `id` (for example, `chat`) to persist mes - Read the conversation history for context - Append the Agent's reply after it runs -```yaml -# 1) Add latest user message -- Memory (operation: add) - id: chat - role: user - content: {{input}} - -# 2) Load conversation history -- Memory (operation: get) - id: chat - -# 3) Run the agent with prior messages available -- Agent - System Prompt: ... - User Prompt: | - Use the conversation so far: - {{memory_get.memories}} - Current user message: {{input}} - -# 4) Store the agent reply -- Memory (operation: add) - id: chat - role: assistant - content: {{agent.content}} -``` - -See the `Memory` block reference for details: [/tools/memory](/tools/memory). +See the [`Memory`](/tools/memory) block reference for details. ## Inputs and Outputs diff --git a/apps/docs/content/docs/en/triggers/api.mdx b/apps/docs/content/docs/en/triggers/api.mdx index a6adc3f46d..98dad08694 100644 --- a/apps/docs/content/docs/en/triggers/api.mdx +++ b/apps/docs/content/docs/en/triggers/api.mdx @@ -24,14 +24,6 @@ The API trigger exposes your workflow as a secure HTTP endpoint. Send JSON data Add an **Input Format** field for each parameter. Runtime output keys mirror the schema and are also available under ``. -```yaml -- type: string - name: userId - value: demo-user # optional manual test value -- type: number - name: maxTokens -``` - Manual runs in the editor use the `value` column so you can test without sending a request. During execution the resolver populates both `` and ``. ## Request Example diff --git a/apps/docs/content/docs/en/yaml/block-reference.mdx b/apps/docs/content/docs/en/yaml/block-reference.mdx deleted file mode 100644 index 37f9d75957..0000000000 --- a/apps/docs/content/docs/en/yaml/block-reference.mdx +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Block Reference Syntax -description: How to reference data between blocks in YAML workflows ---- - -import { Callout } from 'fumadocs-ui/components/callout' -import { Tab, Tabs } from 'fumadocs-ui/components/tabs' - -Block references are the foundation of data flow in Sim workflows. Understanding how to correctly reference outputs from one block as inputs to another is essential for building functional workflows. - -## Basic Reference Rules - -### 1. Use Block Names, Not Block IDs - - - - ```yaml - # Block definition - email-sender: - type: agent - name: "Email Generator" - # ... configuration - - # Reference the block - next-block: - inputs: - userPrompt: "Process this: " - ``` - - - ```yaml - # Block definition - email-sender: - type: agent - name: "Email Generator" - # ... configuration - - # ❌ Don't reference by block ID - next-block: - inputs: - userPrompt: "Process this: " - ``` - - - -### 2. Convert Names to Reference Format - -To create a block reference: - -1. **Take the block name**: "Email Generator" -2. **Convert to lowercase**: "email generator" -3. **Remove spaces and special characters**: "emailgenerator" -4. **Add property**: `` - -### 3. Use Correct Properties - -Different block types expose different properties: - -- **Agent blocks**: `.content` (the AI response) -- **Function blocks**: `.output` (the return value) -- **API blocks**: `.output` (the response data) -- **Tool blocks**: `.output` (the tool result) - -## Reference Examples - -### Common Block References - -```yaml -# Agent block outputs - # Primary AI response - # Token usage information - # Estimated cost - # Tool execution details - -# Function block outputs - # Function return value - # Error information (if any) - -# API block outputs - # Response data - # HTTP status code - # Response headers - -# Tool block outputs - # Tool execution result -``` - -### Multi-Word Block Names - -```yaml -# Block name: "Data Processor 2" - - -# Block name: "Email Validation Service" - - -# Block name: "Customer Info Agent" - -``` - -## Special Reference Cases - -### Starter Block - - - The starter block is always referenced as `` regardless of its actual name. - - -```yaml -# Starter block definition -my-custom-start: - type: starter - name: "Custom Workflow Start" - # ... configuration - -# Always reference as 'start' -agent-1: - inputs: - userPrompt: # ✅ Correct - # userPrompt: # ❌ Wrong -``` - -### Loop Variables - -Inside loop blocks, special variables are available: - -```yaml -# Available in loop child blocks - # Current iteration (0-based) - # Current item being processed (forEach loops) - # Full collection (forEach loops) -``` - -### Parallel Variables - -Inside parallel blocks, special variables are available: - -```yaml -# Available in parallel child blocks - # Instance number (0-based) - # Item for this instance - # Full collection -``` - -## Complex Reference Examples - -### Nested Data Access - -When referencing complex objects, use dot notation: - -```yaml -# If an agent returns structured data -data-analyzer: - type: agent - name: "Data Analyzer" - inputs: - responseFormat: | - { - "schema": { - "type": "object", - "properties": { - "analysis": {"type": "object"}, - "summary": {"type": "string"}, - "metrics": {"type": "object"} - } - } - } - -# Reference nested properties -next-step: - inputs: - userPrompt: | - Summary: - Score: - Full data: -``` - -### Multiple References in Text - -```yaml -email-composer: - type: agent - inputs: - userPrompt: | - Create an email with the following information: - - Customer: - Order Details: - Support Ticket: - - Original request: -``` - -### References in Code Blocks - -When using references in function blocks, they're replaced as JavaScript values: - -```yaml -data-processor: - type: function - inputs: - code: | - // References are replaced with actual values - const customerData = ; - const orderInfo = ; - const originalInput = ; - - // Process the data - return { - customer: customerData.name, - orderId: orderInfo.id, - processed: true - }; -``` - -## Reference Validation - -Sim validates all references when importing YAML: - -### Valid References -- Block exists in the workflow -- Property is appropriate for block type -- No circular dependencies -- Proper syntax formatting - -### Common Errors -- **Block not found**: Referenced block doesn't exist -- **Wrong property**: Using `.content` on a function block -- **Typos**: Misspelled block names or properties -- **Circular references**: Block references itself directly or indirectly - -## Best Practices - -1. **Use descriptive block names**: Makes references more readable -2. **Be consistent**: Use the same naming convention throughout -3. **Check references**: Ensure all referenced blocks exist -4. **Avoid deep nesting**: Keep reference chains manageable -5. **Document complex flows**: Add comments to explain reference relationships \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/agent.mdx b/apps/docs/content/docs/en/yaml/blocks/agent.mdx deleted file mode 100644 index e93e16c168..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/agent.mdx +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Agent Block YAML Schema -description: YAML configuration reference for Agent blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name -properties: - type: - type: string - enum: [agent] - description: Block type identifier - name: - type: string - description: Display name for this agent block - inputs: - type: object - properties: - systemPrompt: - type: string - description: Instructions that define the agent's role and behavior - userPrompt: - type: string - description: Input content to process (can reference other blocks) - model: - type: string - description: AI model identifier (e.g., gpt-4o, gemini-2.5-pro, deepseek-chat) - temperature: - type: number - minimum: 0 - maximum: 2 - description: Response creativity level (varies by model) - apiKey: - type: string - description: API key for the model provider (use {{ENV_VAR}} format) - azureEndpoint: - type: string - description: Azure OpenAI endpoint URL (required for Azure models) - azureApiVersion: - type: string - description: Azure API version (required for Azure models) - memories: - type: string - description: Memory context from memory blocks - tools: - type: array - description: List of external tools the agent can use - items: - type: object - required: [type, title, toolId, operation, usageControl] - properties: - type: - type: string - description: Tool type identifier - title: - type: string - description: Human-readable display name - toolId: - type: string - description: Internal tool identifier - operation: - type: string - description: Tool operation/method name - usageControl: - type: string - enum: [auto, required, none] - description: When AI can use the tool - params: - type: object - description: Tool-specific configuration parameters - isExpanded: - type: boolean - description: UI state - default: false - responseFormat: - type: object - description: JSON Schema to enforce structured output - required: - - model - - apiKey - connections: - type: object - properties: - success: - type: string - description: Target block ID for successful execution - error: - type: string - description: Target block ID for error handling -``` - -## Tool Configuration - -Tools are defined as an array where each tool has this structure: - -```yaml -tools: - - type: # Tool type identifier (exa, gmail, slack, etc.) - title: # Human-readable display name - toolId: # Internal tool identifier - operation: # Tool operation/method name - usageControl: # When AI can use it (auto | required | none) - params: # Tool-specific configuration parameters - isExpanded: # UI state (optional, default: false) -``` - -## Connection Configuration - -Connections define where the workflow goes based on execution results: - -```yaml -connections: - success: # Target block ID for successful execution - error: # Target block ID for error handling (optional) -``` - -## Examples - -### Basic Agent - -```yaml -content-agent: - type: agent - name: "Content Analyzer 1" - inputs: - systemPrompt: "You are a helpful content analyzer. Be concise and clear." - userPrompt: - model: gpt-4o - temperature: 0.3 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: summary-block - -summary-block: - type: agent - name: "Summary Generator" - inputs: - systemPrompt: "Create a brief summary of the analysis." - userPrompt: "Analyze this: " - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: final-step -``` - -### Agent with Tools - -```yaml -research-agent: - type: agent - name: "Research Assistant" - inputs: - systemPrompt: "Research the topic and provide detailed information." - userPrompt: - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - tools: - - type: exa - title: "Web Search" - toolId: exa_search - operation: exa_search - usageControl: auto - params: - apiKey: '{{EXA_API_KEY}}' - connections: - success: summary-block -``` - -### Structured Output - -```yaml -data-extractor: - type: agent - name: "Extract Contact Info" - inputs: - systemPrompt: "Extract contact information from the text." - userPrompt: - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - responseFormat: | - { - "name": "contact_extraction", - "schema": { - "type": "object", - "properties": { - "name": {"type": "string"}, - "email": {"type": "string"}, - "phone": {"type": "string"} - }, - "required": ["name"] - }, - "strict": true - } - connections: - success: save-contact -``` - -### Azure OpenAI - -```yaml -azure-agent: - type: agent - name: "Azure AI Assistant" - inputs: - systemPrompt: "You are a helpful assistant." - userPrompt: - model: gpt-4o - apiKey: '{{AZURE_OPENAI_API_KEY}}' - azureEndpoint: '{{AZURE_OPENAI_ENDPOINT}}' - azureApiVersion: "2024-07-01-preview" - connections: - success: response-block -``` \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/api.mdx b/apps/docs/content/docs/en/yaml/blocks/api.mdx deleted file mode 100644 index b349b8fc69..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/api.mdx +++ /dev/null @@ -1,431 +0,0 @@ ---- -title: API Block YAML Schema -description: YAML configuration reference for API blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name - - inputs -properties: - type: - type: string - enum: [api] - description: Block type identifier - name: - type: string - description: Display name for this API block - inputs: - type: object - required: - - url - - method - properties: - url: - type: string - description: The endpoint URL to send the request to - method: - type: string - enum: [GET, POST, PUT, DELETE, PATCH] - description: HTTP method for the request - default: GET - params: - type: array - description: Query parameters as table entries - items: - type: object - required: - - id - - cells - properties: - id: - type: string - description: Unique identifier for the parameter entry - cells: - type: object - required: - - Key - - Value - properties: - Key: - type: string - description: Parameter name - Value: - type: string - description: Parameter value - headers: - type: array - description: HTTP headers as table entries - items: - type: object - required: - - id - - cells - properties: - id: - type: string - description: Unique identifier for the header entry - cells: - type: object - required: - - Key - - Value - properties: - Key: - type: string - description: Header name - Value: - type: string - description: Header value - body: - type: string - description: Request body for POST/PUT/PATCH methods - timeout: - type: number - description: Request timeout in milliseconds - default: 30000 - minimum: 1000 - maximum: 300000 - connections: - type: object - properties: - success: - type: string - description: Target block ID for successful requests - error: - type: string - description: Target block ID for error handling -``` - -## Connection Configuration - -Connections define where the workflow goes based on request results: - -```yaml -connections: - success: # Target block ID for successful requests - error: # Target block ID for error handling (optional) -``` - -## Examples - -### Simple GET Request - -```yaml -user-api: - type: api - name: "Fetch User Data" - inputs: - url: "https://api.example.com/users/123" - method: GET - headers: - - id: header-1-uuid-here - cells: - Key: "Authorization" - Value: "Bearer {{API_TOKEN}}" - - id: header-2-uuid-here - cells: - Key: "Content-Type" - Value: "application/json" - connections: - success: process-user-data - error: handle-api-error -``` - - - -### POST Request with Body - -```yaml -create-ticket: - type: api - name: "Create Support Ticket" - inputs: - url: "https://api.support.com/tickets" - method: POST - headers: - - id: auth-header-uuid - cells: - Key: "Authorization" - Value: "Bearer {{SUPPORT_API_KEY}}" - - id: content-type-uuid - cells: - Key: "Content-Type" - Value: "application/json" - body: | - { - "title": "", - "description": "", - "priority": "high" - } - connections: - success: ticket-created - error: ticket-error -``` - -### Dynamic URL with Query Parameters - -```yaml -search-api: - type: api - name: "Search Products" - inputs: - url: "https://api.store.com/products" - method: GET - params: - - id: search-param-uuid - cells: - Key: "q" - Value: - - id: limit-param-uuid - cells: - Key: "limit" - Value: "10" - - id: category-param-uuid - cells: - Key: "category" - Value: - headers: - - id: auth-header-uuid - cells: - Key: "Authorization" - Value: "Bearer {{STORE_API_KEY}}" - connections: - success: display-results -``` - -## Parameter Format - -Headers and params (query parameters) use the table format with the following structure: - -```yaml -headers: - - id: unique-identifier-here - cells: - Key: "Content-Type" - Value: "application/json" - - id: another-unique-identifier - cells: - Key: "Authorization" - Value: "Bearer {{API_TOKEN}}" - -params: - - id: param-identifier-here - cells: - Key: "limit" - Value: "10" -``` - -**Structure Details:** -- `id`: Unique identifier for tracking the table row -- `cells.Key`: The parameter/header name -- `cells.Value`: The parameter/header value -- This format allows for proper table management and UI state preservation - -## Output References - -After an API block executes, you can reference its outputs in subsequent blocks. The API block provides three main outputs: - -### Available Outputs - -| Output | Type | Description | -|--------|------|-------------| -| `data` | any | The response body/payload from the API | -| `status` | number | HTTP status code (200, 404, 500, etc.) | -| `headers` | object | Response headers returned by the server | - -### Usage Examples - -```yaml -# Reference API response data -process-data: - type: function - name: "Process API Data" - inputs: - code: | - const responseData = ; - const statusCode = ; - const responseHeaders = ; - - if (statusCode === 200) { - return { - success: true, - user: responseData, - contentType: responseHeaders['content-type'] - }; - } else { - return { - success: false, - error: `API call failed with status ${statusCode}` - }; - } - -# Use API data in an agent block -analyze-response: - type: agent - name: "Analyze Response" - inputs: - userPrompt: | - Analyze this API response: - - Status: - Data: - - Provide insights about the response. - -# Conditional logic based on status -check-status: - type: condition - name: "Check API Status" - inputs: - condition: === 200 - connections: - true: success-handler - false: error-handler -``` - -### Practical Example - -```yaml -user-api: - type: api - name: "Fetch User Data" - inputs: - url: "https://api.example.com/users/123" - method: GET - connections: - success: process-response - -process-response: - type: function - name: "Process Response" - inputs: - code: | - const user = ; - const status = ; - - console.log(`API returned status: ${status}`); - console.log(`User data:`, user); - - return { - userId: user.id, - email: user.email, - isActive: status === 200 - }; -``` - -### Error Handling - -```yaml -api-with-error-handling: - type: api - name: "API Call" - inputs: - url: "https://api.example.com/data" - method: GET - connections: - success: check-response - error: handle-error - -check-response: - type: condition - name: "Check Response Status" - inputs: - condition: >= 200 && < 300 - connections: - true: process-success - false: handle-api-error - -process-success: - type: function - name: "Process Success" - inputs: - code: | - return { - success: true, - data: , - message: "API call successful" - }; - -handle-api-error: - type: function - name: "Handle API Error" - inputs: - code: | - return { - success: false, - status: , - error: "API call failed", - data: - }; -``` - -## YAML String Escaping - -When writing YAML, certain strings must be quoted to be properly parsed: - -### Strings That Must Be Quoted - -```yaml -# URLs with hyphens, colons, special characters -url: "https://api.example.com/users/123" -url: "https://my-api.example.com/data" - -# Header values with hyphens or special characters -headers: - - id: header-uuid - cells: - Key: "User-Agent" - Value: "My-Application/1.0" - - id: auth-uuid - cells: - Key: "Authorization" - Value: "Bearer my-token-123" - -# Parameter values with hyphens -params: - - id: param-uuid - cells: - Key: "sort-by" - Value: "created-at" -``` - -### When to Use Quotes - -- ✅ **Always quote**: URLs, tokens, values with hyphens, colons, or special characters -- ✅ **Always quote**: Values that start with numbers but should be strings -- ✅ **Always quote**: Boolean-looking strings that should remain as strings -- ❌ **Don't quote**: Simple alphanumeric strings without special characters - -### Examples - -```yaml -# ✅ Correct -url: "https://api.stripe.com/v1/charges" -headers: - - id: auth-header - cells: - Key: "Authorization" - Value: "Bearer sk-test-123456789" - -# ❌ Incorrect (may cause parsing errors) -url: https://api.stripe.com/v1/charges -headers: - - id: auth-header - cells: - Key: Authorization - Value: Bearer sk-test-123456789 -``` - -## Best Practices - -- Use environment variables for API keys: `{{API_KEY_NAME}}` -- Include error handling with error connections -- Set appropriate timeouts for your use case -- Validate response status codes in subsequent blocks -- Use meaningful block names for easier reference -- **Always quote strings with special characters, URLs, and tokens** \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/condition.mdx b/apps/docs/content/docs/en/yaml/blocks/condition.mdx deleted file mode 100644 index 37836ecf6e..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/condition.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Condition Block YAML Schema -description: YAML configuration reference for Condition blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name - - inputs - - connections -properties: - type: - type: string - enum: [condition] - description: Block type identifier - name: - type: string - description: Display name for this condition block - inputs: - type: object - required: - - conditions - properties: - conditions: - type: object - description: Conditional expressions and their logic - properties: - if: - type: string - description: Primary condition expression (boolean) - else-if: - type: string - description: Secondary condition expression (optional) - else-if-2: - type: string - description: Third condition expression (optional) - else-if-3: - type: string - description: Fourth condition expression (optional) - # Additional else-if-N conditions can be added as needed - else: - type: boolean - description: Default fallback condition (optional) - default: true - connections: - type: object - required: - - conditions - properties: - conditions: - type: object - description: Target blocks for each condition outcome - properties: - if: - type: string - description: Target block ID when 'if' condition is true - else-if: - type: string - description: Target block ID when 'else-if' condition is true - else-if-2: - type: string - description: Target block ID when 'else-if-2' condition is true - else-if-3: - type: string - description: Target block ID when 'else-if-3' condition is true - # Additional else-if-N connections can be added as needed - else: - type: string - description: Target block ID when no conditions match -``` - -## Connection Configuration - -Unlike other blocks, conditions use branching connections based on condition outcomes: - -```yaml -connections: - conditions: - if: # Target block ID when primary condition is true - else-if: # Target block ID when secondary condition is true (optional) - else-if-2: # Target block ID when third condition is true (optional) - else-if-3: # Target block ID when fourth condition is true (optional) - # Additional else-if-N connections can be added as needed - else: # Target block ID when no conditions match (optional) -``` - -## Examples - -### Simple If-Else - -```yaml -status-check: - type: condition - name: "Status Check" - inputs: - conditions: - if: === "approved" - else: true - connections: - conditions: - if: send-approval-email - else: send-rejection-email -``` - -### Multiple Conditions - -```yaml -user-routing: - type: condition - name: "User Type Router" - inputs: - conditions: - if: === "admin" - else-if: === "premium" - else-if-2: === "basic" - else: true - connections: - conditions: - if: admin-dashboard - else-if: premium-features - else-if-2: basic-features - else: registration-flow -``` - -### Numeric Comparisons - -```yaml -score-evaluation: - type: condition - name: "Score Evaluation" - inputs: - conditions: - if: >= 90 - else-if: >= 70 - else-if-2: >= 50 - else: true - connections: - conditions: - if: excellent-response - else-if: good-response - else-if-2: average-response - else: poor-response -``` - -### Complex Logic - -```yaml -eligibility-check: - type: condition - name: "Eligibility Check" - inputs: - conditions: - if: >= 18 && === true - else-if: >= 16 && === true - else: true - connections: - conditions: - if: full-access - else-if: limited-access - else: access-denied -``` \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/evaluator.mdx b/apps/docs/content/docs/en/yaml/blocks/evaluator.mdx deleted file mode 100644 index 9d51de3896..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/evaluator.mdx +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Evaluator Block YAML Schema -description: YAML configuration reference for Evaluator blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name - - inputs -properties: - type: - type: string - enum: [evaluator] - description: Block type identifier - name: - type: string - description: Display name for this evaluator block - inputs: - type: object - required: - - content - - metrics - - model - - apiKey - properties: - content: - type: string - description: Content to evaluate (can reference other blocks) - metrics: - type: array - description: Evaluation criteria and scoring ranges - items: - type: object - properties: - name: - type: string - description: Metric identifier - description: - type: string - description: Detailed explanation of what the metric measures - range: - type: object - properties: - min: - type: number - description: Minimum score value - max: - type: number - description: Maximum score value - required: [min, max] - description: Scoring range with numeric bounds - model: - type: string - description: AI model identifier (e.g., gpt-4o, claude-3-5-sonnet-20241022) - apiKey: - type: string - description: API key for the model provider (use {{ENV_VAR}} format) - temperature: - type: number - minimum: 0 - maximum: 2 - description: Model temperature for evaluation - default: 0.3 - azureEndpoint: - type: string - description: Azure OpenAI endpoint URL (required for Azure models) - azureApiVersion: - type: string - description: Azure API version (required for Azure models) - connections: - type: object - properties: - success: - type: string - description: Target block ID for successful evaluation - error: - type: string - description: Target block ID for error handling -``` - -## Connection Configuration - -Connections define where the workflow goes based on evaluation results: - -```yaml -connections: - success: # Target block ID for successful evaluation - error: # Target block ID for error handling (optional) -``` - -## Examples - -### Content Quality Evaluation - -```yaml -content-evaluator: - type: evaluator - name: "Content Quality Evaluator" - inputs: - content: - metrics: - - name: "accuracy" - description: "How factually accurate is the content?" - range: - min: 1 - max: 5 - - name: "clarity" - description: "How clear and understandable is the content?" - range: - min: 1 - max: 5 - - name: "relevance" - description: "How relevant is the content to the original query?" - range: - min: 1 - max: 5 - - name: "completeness" - description: "How complete and comprehensive is the content?" - range: - min: 1 - max: 5 - model: gpt-4o - temperature: 0.2 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: quality-report - error: evaluation-error -``` - -### Customer Response Evaluation - -```yaml -response-evaluator: - type: evaluator - name: "Customer Response Evaluator" - inputs: - content: - metrics: - - name: "helpfulness" - description: "How helpful is the response in addressing the customer's needs?" - range: - min: 1 - max: 10 - - name: "tone" - description: "How appropriate and professional is the tone?" - range: - min: 1 - max: 10 - - name: "completeness" - description: "Does the response fully address all aspects of the inquiry?" - range: - min: 1 - max: 10 - model: claude-3-5-sonnet-20241022 - apiKey: '{{ANTHROPIC_API_KEY}}' - connections: - success: response-processor -``` - -### A/B Testing Evaluation - -```yaml -ab-test-evaluator: - type: evaluator - name: "A/B Test Evaluator" - inputs: - content: | - Version A: - Version B: - - Compare these two versions for the following criteria. - metrics: - - name: "engagement" - description: "Which version is more likely to engage users?" - range: "A, B, or Tie" - - name: "clarity" - description: "Which version communicates more clearly?" - range: "A, B, or Tie" - - name: "persuasiveness" - description: "Which version is more persuasive?" - range: "A, B, or Tie" - model: gpt-4o - temperature: 0.1 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: test-results -``` - -### Multi-Dimensional Content Scoring - -```yaml -comprehensive-evaluator: - type: evaluator - name: "Comprehensive Content Evaluator" - inputs: - content: - metrics: - - name: "technical_accuracy" - description: "How technically accurate and correct is the information?" - range: - min: 0 - max: 100 - - name: "readability" - description: "How easy is the content to read and understand?" - range: - min: 0 - max: 100 - - name: "seo_optimization" - description: "How well optimized is the content for search engines?" - range: - min: 0 - max: 100 - - name: "user_engagement" - description: "How likely is this content to engage and retain readers?" - range: - min: 0 - max: 100 - - name: "brand_alignment" - description: "How well does the content align with brand voice and values?" - range: - min: 0 - max: 100 - model: gpt-4o - temperature: 0.3 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: content-optimization -``` - -## Output References - -After an evaluator block executes, you can reference its outputs: - -```yaml -# In subsequent blocks -next-block: - inputs: - evaluation: # Evaluation summary - scores: # Individual metric scores - overall: # Overall assessment -``` - -## Best Practices - -- Define clear, specific evaluation criteria -- Use appropriate scoring ranges for your use case -- Choose models with strong reasoning capabilities -- Use lower temperature for consistent scoring -- Include detailed metric descriptions -- Test with diverse content types -- Consider multiple evaluators for complex assessments \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/function.mdx b/apps/docs/content/docs/en/yaml/blocks/function.mdx deleted file mode 100644 index 951f91b50a..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/function.mdx +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Function Block YAML Schema -description: YAML configuration reference for Function blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name - - inputs -properties: - type: - type: string - enum: [function] - description: Block type identifier - name: - type: string - description: Display name for this function block - inputs: - type: object - required: - - code - properties: - code: - type: string - description: JavaScript/TypeScript code to execute (multiline string) - timeout: - type: number - description: Maximum execution time in milliseconds - default: 30000 - minimum: 1000 - maximum: 300000 - connections: - type: object - properties: - success: - type: string - description: Target block ID for successful execution - error: - type: string - description: Target block ID for error handling -``` - -## Connection Configuration - -Connections define where the workflow goes based on execution results: - -```yaml -connections: - success: # Target block ID for successful execution - error: # Target block ID for error handling (optional) -``` - -## Examples - -### Simple Validation - -```yaml -input-validator: - type: function - name: "Input Validator" - inputs: - code: |- - // Check if input number is greater than 5 - const inputValue = parseInt(, 10); - - if (inputValue > 5) { - return { - valid: true, - value: inputValue, - message: "Input is valid" - }; - } else { - return { - valid: false, - value: inputValue, - message: "Input must be greater than 5" - }; - } - connections: - success: next-step - error: handle-error -``` - -### Data Processing - -```yaml -data-processor: - type: function - name: "Data Transformer" - inputs: - code: | - // Transform the input data - const rawData = ; - - // Process and clean the data - const processed = rawData - .filter(item => item.status === 'active') - .map(item => ({ - id: item.id, - name: item.name.trim(), - date: new Date(item.created).toISOString() - })); - - return processed; - connections: - success: api-save - error: error-handler -``` - -### API Integration - -```yaml -api-formatter: - type: function - name: "Format API Request" - inputs: - code: | - // Prepare data for API submission - const userData = ; - - const apiPayload = { - timestamp: new Date().toISOString(), - data: userData, - source: "workflow-automation", - version: "1.0" - }; - - return apiPayload; - connections: - success: api-call -``` - -### Calculations - -```yaml -calculator: - type: function - name: "Calculate Results" - inputs: - code: | - // Perform calculations on input data - const numbers = ; - - const sum = numbers.reduce((a, b) => a + b, 0); - const average = sum / numbers.length; - const max = Math.max(...numbers); - const min = Math.min(...numbers); - - return { - sum, - average, - max, - min, - count: numbers.length - }; - connections: - success: results-display -``` \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/index.mdx b/apps/docs/content/docs/en/yaml/blocks/index.mdx deleted file mode 100644 index e3ee959fae..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/index.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Block Schemas -description: Complete YAML schema reference for all Sim blocks ---- - -import { Card, Cards } from "fumadocs-ui/components/card"; - -This section contains the complete YAML schema definitions for all available block types in Sim. Each block type has specific configuration requirements and output formats. - -## Core Blocks - -These are the essential building blocks for creating workflows: - - - - Workflow entry point supporting manual triggers, webhooks, and schedules - - - AI-powered processing with LLM integration and tool support - - - Custom JavaScript/TypeScript code execution environment - - - Format and return final workflow results - - - -## Logic & Control Flow - -Blocks for implementing conditional logic and control flow: - - - - Conditional branching based on boolean expressions - - - AI-powered intelligent routing to multiple paths - - - Iterative processing with for and forEach loops - - - Concurrent execution across multiple instances - - - -## Integration Blocks - -Blocks for connecting to external services and systems: - - - - HTTP requests to external REST APIs - - - Webhook triggers for external integrations - - - -## Advanced Blocks - -Specialized blocks for complex workflow patterns: - - - - Validate outputs against defined criteria and metrics - - - Execute other workflows as reusable components - - - -## Common Schema Elements - -All blocks share these common elements: - -### Basic Structure - -```yaml -block-id: - type: - name: - inputs: - # Block-specific configuration - connections: - # Connection definitions -``` - -### Connection Types - -- **success**: Target block for successful execution -- **error**: Target block for error handling (optional) -- **conditions**: Multiple paths for conditional blocks - -### Environment Variables - -Use double curly braces for environment variables: - -```yaml -inputs: - apiKey: '{{API_KEY_NAME}}' - endpoint: '{{SERVICE_ENDPOINT}}' -``` - -### Block References - -Reference other block outputs using the block name in lowercase: - -```yaml -inputs: - userPrompt: - data: - originalInput: -``` - -## Validation Rules - -All YAML blocks are validated against their schemas: - -1. **Required fields**: Must be present -2. **Type validation**: Values must match expected types -3. **Enum validation**: String values must be from allowed lists -4. **Range validation**: Numbers must be within specified ranges -5. **Pattern validation**: Strings must match regex patterns (where applicable) - -## Quick Reference - -### Block Types and Properties - -| Block Type | Primary Output | Common Use Cases | -|------------|----------------|------------------| -| starter | `.input` | Workflow entry point | -| agent | `.content` | AI processing, text generation | -| function | `.output` | Data transformation, calculations | -| api | `.output` | External service integration | -| condition | N/A (branching) | Conditional logic | -| router | N/A (branching) | Intelligent routing | -| response | N/A (terminal) | Final output formatting | -| loop | `.results` | Iterative processing | -| parallel | `.results` | Concurrent processing | -| webhook | `.payload` | External triggers | -| evaluator | `.score` | Output validation, quality assessment | -| workflow | `.output` | Sub-workflow execution, modularity | - -### Required vs Optional - -- **Always required**: `type`, `name` -- **Usually required**: `inputs`, `connections` -- **Context dependent**: Specific input fields vary by block type -- **Always optional**: `error` connections, UI-specific fields \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/parallel.mdx b/apps/docs/content/docs/en/yaml/blocks/parallel.mdx deleted file mode 100644 index 1a7dacf632..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/parallel.mdx +++ /dev/null @@ -1,312 +0,0 @@ ---- -title: Parallel Block YAML Schema -description: YAML configuration reference for Parallel blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name - - inputs - - connections -properties: - type: - type: string - enum: [parallel] - description: Block type identifier - name: - type: string - description: Display name for this parallel block - inputs: - type: object - required: - - parallelType - properties: - parallelType: - type: string - enum: [count, collection] - description: Type of parallel execution - count: - type: number - description: Number of parallel instances (for 'count' type) - minimum: 1 - maximum: 100 - collection: - type: string - description: Collection to distribute across instances (for 'collection' type) - maxConcurrency: - type: number - description: Maximum concurrent executions - default: 10 - minimum: 1 - maximum: 50 - connections: - type: object - required: - - parallel - properties: - parallel: - type: object - required: - - start - properties: - start: - type: string - description: Target block ID to execute inside each parallel instance - end: - type: string - description: Target block ID after all parallel instances complete (optional) - error: - type: string - description: Target block ID for error handling -``` - -## Connection Configuration - -Parallel blocks use a special connection format with a `parallel` section: - -```yaml -connections: - parallel: - start: # Target block ID to execute inside each parallel instance - end: # Target block ID after all instances complete (optional) - error: # Target block ID for error handling (optional) -``` - -## Child Block Configuration - -Blocks inside a parallel block must have their `parentId` set to the parallel block ID: - -```yaml -parallel-1: - type: parallel - name: "Process Items" - inputs: - parallelType: collection - collection: - connections: - parallel: - start: process-item - end: aggregate-results - -# Child block inside the parallel -process-item: - type: agent - name: "Process Item" - parentId: parallel-1 # References the parallel block - inputs: - systemPrompt: "Process this item" - userPrompt: - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' -``` - -## Examples - -### Count-Based Parallel Processing - -```yaml -worker-parallel: - type: parallel - name: "Worker Parallel" - inputs: - parallelType: count - count: 5 - maxConcurrency: 3 - connections: - parallel: - start: worker-task - end: collect-worker-results - -worker-task: - type: api - name: "Worker Task" - parentId: worker-parallel - inputs: - url: "https://api.worker.com/process" - method: POST - headers: - - key: "Authorization" - value: "Bearer {{WORKER_API_KEY}}" - body: | - { - "instanceId": , - "timestamp": "{{new Date().toISOString()}}" - } - connections: - success: worker-complete -``` - -### Collection-Based Parallel Processing - -```yaml -api-parallel: - type: parallel - name: "API Parallel" - inputs: - parallelType: collection - collection: - maxConcurrency: 10 - connections: - parallel: - start: call-api - end: merge-api-results - -call-api: - type: api - name: "Call API" - parentId: api-parallel - inputs: - url: - method: - headers: - - key: "Authorization" - value: "Bearer {{API_TOKEN}}" - connections: - success: api-complete -``` - -### Complex Parallel Processing Pipeline - -```yaml -data-processing-parallel: - type: parallel - name: "Data Processing Parallel" - inputs: - parallelType: collection - collection: - maxConcurrency: 8 - connections: - parallel: - start: validate-data - end: final-aggregation - error: parallel-error-handler - -validate-data: - type: function - name: "Validate Data" - parentId: data-processing-parallel - inputs: - code: | - const record = ; - const index = ; - - // Validate record structure - if (!record.id || !record.content) { - throw new Error(`Invalid record at index ${index}`); - } - - return { - valid: true, - recordId: record.id, - validatedAt: new Date().toISOString() - }; - connections: - success: process-data - error: validation-error - -process-data: - type: agent - name: "Process Data" - parentId: data-processing-parallel - inputs: - systemPrompt: "Process and analyze this data record" - userPrompt: | - Record ID: - Content: - Instance: - model: gpt-4o - temperature: 0.3 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: store-result - -store-result: - type: function - name: "Store Result" - parentId: data-processing-parallel - inputs: - code: | - const processed = ; - const recordId = ; - - return { - recordId, - processed, - completedAt: new Date().toISOString(), - instanceIndex: - }; -``` - -### Concurrent AI Analysis - -```yaml -multi-model-parallel: - type: parallel - name: "Multi-Model Analysis" - inputs: - parallelType: collection - collection: | - [ - {"model": "gpt-4o", "focus": "technical accuracy"}, - {"model": "claude-3-5-sonnet-20241022", "focus": "creative quality"}, - {"model": "gemini-2.0-flash-exp", "focus": "factual verification"} - ] - maxConcurrency: 3 - connections: - parallel: - start: analyze-content - end: combine-analyses - -analyze-content: - type: agent - name: "Analyze Content" - parentId: multi-model-parallel - inputs: - systemPrompt: | - You are analyzing content with a focus on . - Provide detailed analysis from this perspective. - userPrompt: | - Content to analyze: - Analysis focus: - model: - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: analysis-complete -``` - -## Parallel Variables - -Inside parallel child blocks, these special variables are available: - -```yaml -# Available in all child blocks of the parallel - # Instance number (0-based) - # Item for this instance (collection type) - # Full collection (collection type) -``` - -## Output References - -After a parallel block completes, you can reference its aggregated results: - -```yaml -# In blocks after the parallel -final-processor: - inputs: - all-results: # Array of all instance results - total-count: # Number of instances completed -``` - -## Best Practices - -- Use appropriate maxConcurrency to avoid overwhelming APIs -- Ensure operations are independent and don't rely on each other -- Include error handling for robust parallel execution -- Test with small collections first -- Monitor rate limits for external APIs -- Use collection type for distributing work, count type for fixed instances -- Consider memory usage with large collections \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/response.mdx b/apps/docs/content/docs/en/yaml/blocks/response.mdx deleted file mode 100644 index 069ad35f57..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/response.mdx +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Response Block YAML Schema -description: YAML configuration reference for Response blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name -properties: - type: - type: string - enum: [response] - description: Block type identifier - name: - type: string - description: Display name for this response block - inputs: - type: object - properties: - dataMode: - type: string - enum: [structured, json] - description: Mode for defining response data structure - default: structured - builderData: - type: object - description: Structured response data (when dataMode is 'structured') - data: - type: object - description: JSON response data (when dataMode is 'json') - status: - type: number - description: HTTP status code - default: 200 - minimum: 100 - maximum: 599 - headers: - type: array - description: Response headers as table entries - items: - type: object - properties: - id: - type: string - description: Unique identifier for the header entry - key: - type: string - description: Header name - value: - type: string - description: Header value - cells: - type: object - description: Cell display values for the table interface - properties: - Key: - type: string - description: Display value for the key column - Value: - type: string - description: Display value for the value column -``` - -## Connection Configuration - -Response blocks are terminal blocks (no outgoing connections) and define the final output: - -```yaml -# No connections object needed - Response blocks are always terminal -``` - -## Examples - -### Simple Response - -```yaml -simple-response: - type: response - name: "Simple Response" - inputs: - data: - message: "Hello World" - timestamp: - status: 200 -``` - -### Success Response - -```yaml -success-response: - type: response - name: "Success Response" - inputs: - data: - success: true - user: - id: - name: - email: - created_at: - status: 201 - headers: - - key: "Location" - value: "/api/users/" - - key: "X-Created-By" - value: "workflow-engine" -``` - -### Response with Complete Table Header Format - -When headers are created through the UI table interface, the YAML includes additional metadata: - -```yaml -api-response: - type: response - name: "API Response" - inputs: - data: - message: "Request processed successfully" - id: - status: 200 - headers: - - id: header-1-uuid-here - key: "Content-Type" - value: "application/json" - cells: - Key: "Content-Type" - Value: "application/json" - - id: header-2-uuid-here - key: "Cache-Control" - value: "no-cache" - cells: - Key: "Cache-Control" - Value: "no-cache" - - id: header-3-uuid-here - key: "X-API-Version" - value: "2.1" - cells: - Key: "X-API-Version" - Value: "2.1" -``` - -### Error Response - -```yaml -error-response: - type: response - name: "Error Response" - inputs: - data: - error: true - message: - code: "VALIDATION_FAILED" - details: - status: 400 - headers: - - key: "X-Error-Code" - value: "VALIDATION_FAILED" -``` - -### Paginated Response - -```yaml -paginated-response: - type: response - name: "Paginated Response" - inputs: - data: - data: - pagination: - page: - per_page: - total: - total_pages: - status: 200 - headers: - - key: "X-Total-Count" - value: - - key: "Cache-Control" - value: "public, max-age=300" - - key: "Content-Type" - value: "application/json" -``` - -## Table Parameter Formats - -The Response block supports two formats for headers: - -### Simplified Format (Manual YAML) - -When writing YAML manually, you can use the simplified format: - -```yaml -headers: - - key: "Content-Type" - value: "application/json" - - key: "Cache-Control" - value: "no-cache" -``` - -### Complete Table Format (UI Generated) - -When headers are created through the UI table interface, the YAML includes additional metadata: - -```yaml -headers: - - id: unique-identifier-here - key: "Content-Type" - value: "application/json" - cells: - Key: "Content-Type" - Value: "application/json" -``` - -**Key Differences:** -- `id`: Unique identifier for tracking the table row -- `cells`: Display values used by the UI table interface -- Both formats are functionally equivalent for workflow execution -- The complete format preserves UI state when importing/exporting workflows - -**Important:** Always quote header names and values that contain special characters: - -```yaml -headers: - - id: content-type-uuid - cells: - Key: "Content-Type" - Value: "application/json" - - id: cache-control-uuid - cells: - Key: "Cache-Control" - Value: "no-cache" -``` -``` \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/router.mdx b/apps/docs/content/docs/en/yaml/blocks/router.mdx deleted file mode 100644 index 2c225d4299..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/router.mdx +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Router Block YAML Schema -description: YAML configuration reference for Router blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name - - inputs -properties: - type: - type: string - enum: [router] - description: Block type identifier - name: - type: string - description: Display name for this router block - inputs: - type: object - required: - - prompt - - model - - apiKey - properties: - prompt: - type: string - description: Instructions for routing decisions and criteria - model: - type: string - description: AI model identifier (e.g., gpt-4o, gemini-2.5-pro, deepseek-chat) - apiKey: - type: string - description: API key for the model provider (use {{ENV_VAR}} format) - temperature: - type: number - minimum: 0 - maximum: 2 - description: Model temperature for routing decisions - default: 0.3 - azureEndpoint: - type: string - description: Azure OpenAI endpoint URL (required for Azure models) - azureApiVersion: - type: string - description: Azure API version (required for Azure models) - connections: - type: object - description: Multiple connection paths for different routing outcomes - properties: - success: - type: array - items: - type: string - description: Array of target block IDs for routing destinations -``` - -## Connection Configuration - -Router blocks use a success array containing all possible routing destinations: - -```yaml -connections: - success: - - # Target block ID option 1 - - # Target block ID option 2 - - # Target block ID option 3 - # Additional target block IDs as needed -``` - -## Examples - -### Content Type Router - -```yaml -content-router: - type: router - name: "Content Type Router" - inputs: - prompt: | - Route this content based on its type: - - If it's a question, route to question-handler - - If it's a complaint, route to complaint-handler - - If it's feedback, route to feedback-handler - - If it's a request, route to request-handler - - Content: - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: - - question-handler - - complaint-handler - - feedback-handler - - request-handler -``` - -### Priority Router - -```yaml -priority-router: - type: router - name: "Priority Router" - inputs: - prompt: | - Analyze the urgency and route accordingly: - - urgent-queue: High priority, needs immediate attention - - standard-queue: Normal priority, standard processing - - low-queue: Low priority, can be delayed - - Email content: - - Route based on urgency indicators, deadlines, and tone. - model: gpt-4o - temperature: 0.2 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: - - urgent-queue - - standard-queue - - low-queue -``` - -### Department Router - -```yaml -department-router: - type: router - name: "Department Router" - inputs: - prompt: | - Route this customer inquiry to the appropriate department: - - - sales-team: Sales questions, pricing, demos - - support-team: Technical issues, bug reports, how-to questions - - billing-team: Payment issues, subscription changes, invoices - - general-team: General inquiries, feedback, other topics - - Customer message: - Customer type: - model: claude-3-5-sonnet-20241022 - apiKey: '{{ANTHROPIC_API_KEY}}' - connections: - success: - - sales-team - - support-team - - billing-team - - general-team -``` - -## Advanced Configuration - -### Multiple Models Router - -```yaml -model-selector-router: - type: router - name: "Model Selection Router" - inputs: - prompt: | - Based on the task complexity, route to the appropriate model: - - simple-gpt35: Simple questions, basic tasks - - advanced-gpt4: Complex analysis, detailed reasoning - - specialized-claude: Creative writing, nuanced analysis - - Task: - Complexity indicators: - model: gpt-4o-mini - temperature: 0.1 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: - - simple-gpt35 - - advanced-gpt4 - - specialized-claude -``` - -## Output References - -Router blocks don't produce direct outputs but control workflow path: - -```yaml -# Router decisions affect which subsequent blocks execute -# Access the routed block's outputs normally: -final-step: - inputs: - routed-result: -``` - -## Best Practices - -- Provide clear routing criteria in the prompt -- Use specific, descriptive target block names -- Include examples of content for each routing path -- Use lower temperature values for consistent routing -- Test with diverse input types to ensure accurate routing -- Consider fallback paths for edge cases \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/starter.mdx b/apps/docs/content/docs/en/yaml/blocks/starter.mdx deleted file mode 100644 index 101cf9c3be..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/starter.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Starter Block YAML Schema -description: YAML configuration reference for Starter blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name -properties: - type: - type: string - enum: [starter] - description: Block type identifier - name: - type: string - description: Display name for this starter block - inputs: - type: object - properties: - startWorkflow: - type: string - enum: [manual, webhook, schedule] - description: How the workflow should be triggered - default: manual - inputFormat: - type: array - description: Expected input structure for API calls (manual workflows) - items: - type: object - properties: - name: - type: string - description: Field name - type: - type: string - enum: [string, number, boolean, object, array] - description: Field type - scheduleType: - type: string - enum: [hourly, daily, weekly, monthly] - description: Schedule frequency (schedule workflows only) - hourlyMinute: - type: number - minimum: 0 - maximum: 59 - description: Minute of the hour to run (hourly schedules) - dailyTime: - type: string - pattern: "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" - description: Time of day to run in HH:MM format (daily schedules) - weeklyDay: - type: string - enum: [MON, TUE, WED, THU, FRI, SAT, SUN] - description: Day of week to run (weekly schedules) - weeklyTime: - type: string - pattern: "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" - description: Time of day to run in HH:MM format (weekly schedules) - monthlyDay: - type: number - minimum: 1 - maximum: 28 - description: Day of month to run (monthly schedules) - monthlyTime: - type: string - pattern: "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" - description: Time of day to run in HH:MM format (monthly schedules) - timezone: - type: string - description: Timezone for scheduled workflows - default: UTC - webhookProvider: - type: string - enum: [slack, gmail, airtable, telegram, generic, whatsapp, github, discord, stripe] - description: Provider for webhook integration (webhook workflows only) - webhookConfig: - type: object - description: Provider-specific webhook configuration - connections: - type: object - properties: - success: - type: string - description: Target block ID to execute when workflow starts -``` - -## Connection Configuration - -The starter block only has a success connection since it's the entry point: - -```yaml -connections: - success: # Target block ID to execute when workflow starts -``` - -## Examples - -### Manual Start - -```yaml -start: - type: starter - name: Start - inputs: - startWorkflow: manual - connections: - success: next-block -``` - -### Manual Start with Input Format - -```yaml -start: - type: starter - name: Start - inputs: - startWorkflow: manual - inputFormat: - - name: query - type: string - - name: email - type: string - - name: age - type: number - - name: isActive - type: boolean - - name: preferences - type: object - - name: tags - type: array - connections: - success: agent-1 -``` - -### Daily Schedule - -```yaml -start: - type: starter - name: Start - inputs: - startWorkflow: schedule - scheduleType: daily - dailyTime: "09:00" - timezone: "America/New_York" - connections: - success: daily-task -``` - -### Weekly Schedule - -```yaml -start: - type: starter - name: Start - inputs: - startWorkflow: schedule - scheduleType: weekly - weeklyDay: MON - weeklyTime: "08:30" - timezone: UTC - connections: - success: weekly-report -``` - -### Webhook Trigger - -```yaml -start: - type: starter - name: Start - inputs: - startWorkflow: webhook - webhookProvider: slack - webhookConfig: - # Provider-specific configuration - connections: - success: process-webhook -``` \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/webhook.mdx b/apps/docs/content/docs/en/yaml/blocks/webhook.mdx deleted file mode 100644 index 83408a6032..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/webhook.mdx +++ /dev/null @@ -1,403 +0,0 @@ ---- -title: Webhook Block YAML Schema -description: YAML configuration reference for Webhook blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name -properties: - type: - type: string - enum: [webhook] - description: Block type identifier - name: - type: string - description: Display name for this webhook block - inputs: - type: object - properties: - webhookConfig: - type: object - description: Webhook configuration settings - properties: - enabled: - type: boolean - description: Whether the webhook is active - default: true - secret: - type: string - description: Secret key for webhook verification - headers: - type: array - description: Expected headers for validation as table entries - items: - type: object - properties: - id: - type: string - description: Unique identifier for the header entry - key: - type: string - description: Header name - value: - type: string - description: Expected header value - cells: - type: object - description: Cell display values for the table interface - properties: - Key: - type: string - description: Display value for the key column - Value: - type: string - description: Display value for the value column - methods: - type: array - description: Allowed HTTP methods - items: - type: string - enum: [GET, POST, PUT, DELETE, PATCH] - default: [POST] - responseConfig: - type: object - description: Response configuration for the webhook - properties: - status: - type: number - description: HTTP status code to return - default: 200 - minimum: 100 - maximum: 599 - headers: - type: array - description: Response headers as table entries - items: - type: object - properties: - id: - type: string - description: Unique identifier for the header entry - key: - type: string - description: Header name - value: - type: string - description: Header value - cells: - type: object - description: Cell display values for the table interface - properties: - Key: - type: string - description: Display value for the key column - Value: - type: string - description: Display value for the value column - body: - type: string - description: Response body content - connections: - type: object - properties: - success: - type: string - description: Target block ID for successful webhook processing - error: - type: string - description: Target block ID for error handling -``` - -## Connection Configuration - -Connections define where the workflow goes based on webhook processing: - -```yaml -connections: - success: # Target block ID for successful processing - error: # Target block ID for error handling (optional) -``` - -## Examples - -### Basic Webhook Trigger - -```yaml -github-webhook: - type: webhook - name: "GitHub Webhook" - inputs: - webhookConfig: - enabled: true - secret: "{{GITHUB_WEBHOOK_SECRET}}" - methods: [POST] - headers: - - key: "X-GitHub-Event" - value: "push" - responseConfig: - status: 200 - body: | - { - "message": "Webhook received successfully", - "timestamp": "{{new Date().toISOString()}}" - } - connections: - success: process-github-event - error: webhook-error-handler -``` - -### Slack Event Webhook - -```yaml -slack-events: - type: webhook - name: "Slack Events" - inputs: - webhookConfig: - enabled: true - secret: "{{SLACK_SIGNING_SECRET}}" - methods: [POST] - headers: - - key: "Content-Type" - value: "application/json" - responseConfig: - status: 200 - headers: - - key: "Content-Type" - value: "application/json" - body: | - { - "challenge": "" - } - connections: - success: handle-slack-event -``` - -### Payment Webhook (Stripe) - -```yaml -stripe-webhook: - type: webhook - name: "Stripe Payment Webhook" - inputs: - webhookConfig: - enabled: true - secret: "{{STRIPE_WEBHOOK_SECRET}}" - methods: [POST] - headers: - - key: "Stripe-Signature" - value: "*" - responseConfig: - status: 200 - headers: - - key: "Content-Type" - value: "application/json" - body: | - { - "received": true - } - connections: - success: process-payment-event - error: payment-webhook-error -``` - -### Webhook with Complete Table Header Format - -When headers are created through the UI table interface, the YAML includes additional metadata: - -```yaml -api-webhook-complete: - type: webhook - name: "API Webhook with Table Headers" - inputs: - webhookConfig: - enabled: true - methods: [POST] - headers: - - id: header-1-uuid-here - key: "Authorization" - value: "Bearer {{WEBHOOK_API_KEY}}" - cells: - Key: "Authorization" - Value: "Bearer {{WEBHOOK_API_KEY}}" - - id: header-2-uuid-here - key: "Content-Type" - value: "application/json" - cells: - Key: "Content-Type" - Value: "application/json" - responseConfig: - status: 200 - headers: - - id: response-header-1-uuid - key: "Content-Type" - value: "application/json" - cells: - Key: "Content-Type" - Value: "application/json" - - id: response-header-2-uuid - key: "X-Webhook-Response" - value: "processed" - cells: - Key: "X-Webhook-Response" - Value: "processed" - body: | - { - "status": "received", - "timestamp": "{{new Date().toISOString()}}" - } - connections: - success: process-webhook-complete -``` - -### Generic API Webhook - -```yaml -api-webhook: - type: webhook - name: "API Webhook" - inputs: - webhookConfig: - enabled: true - methods: [POST, PUT] - headers: - - key: "Authorization" - value: "Bearer {{WEBHOOK_API_KEY}}" - - key: "Content-Type" - value: "application/json" - responseConfig: - status: 202 - headers: - - key: "Content-Type" - value: "application/json" - - key: "X-Processed-By" - value: "Sim" - body: | - { - "status": "accepted", - "id": "{{Math.random().toString(36).substr(2, 9)}}", - "received_at": "{{new Date().toISOString()}}" - } - connections: - success: process-webhook-data -``` - -### Multi-Method Webhook - -```yaml -crud-webhook: - type: webhook - name: "CRUD Webhook" - inputs: - webhookConfig: - enabled: true - methods: [GET, POST, PUT, DELETE] - headers: - - key: "X-API-Key" - value: "{{CRUD_API_KEY}}" - responseConfig: - status: 200 - headers: - - key: "Content-Type" - value: "application/json" - body: | - { - "method": "", - "processed": true, - "timestamp": "{{new Date().toISOString()}}" - } - connections: - success: route-by-method -``` - -## Table Parameter Formats - -The Webhook block supports two formats for headers (both validation headers and response headers): - -### Simplified Format (Manual YAML) - -When writing YAML manually, you can use the simplified format: - -```yaml -headers: - - key: "Authorization" - value: "Bearer {{API_TOKEN}}" - - key: "Content-Type" - value: "application/json" -``` - -### Complete Table Format (UI Generated) - -When headers are created through the UI table interface, the YAML includes additional metadata: - -```yaml -headers: - - id: unique-identifier-here - key: "Authorization" - value: "Bearer {{API_TOKEN}}" - cells: - Key: "Authorization" - Value: "Bearer {{API_TOKEN}}" -``` - -**Key Differences:** -- `id`: Unique identifier for tracking the table row -- `cells`: Display values used by the UI table interface -- Both formats are functionally equivalent for webhook processing -- The complete format preserves UI state when importing/exporting workflows - -**Important:** Always quote header names and values that contain special characters: - -```yaml -headers: - - id: auth-header-uuid - cells: - Key: "Authorization" - Value: "Bearer {{WEBHOOK_API_KEY}}" - - id: content-type-uuid - cells: - Key: "Content-Type" - Value: "application/json" -``` - -## Webhook Variables - -Inside webhook-triggered workflows, these special variables are available: - -```yaml -# Available in blocks after the webhook - # Full request payload/body - # Request headers - # HTTP method used - # Query parameters - # Request path - # Challenge parameter (for verification) -``` - -## Output References - -After a webhook processes a request, you can reference its data: - -```yaml -# In subsequent blocks -process-webhook: - inputs: - payload: # Request payload - headers: # Request headers - method: # HTTP method -``` - -## Security Best Practices - -- Always use webhook secrets for verification -- Validate expected headers and methods -- Implement proper error handling -- Use HTTPS endpoints in production -- Monitor webhook activity and failures -- Set appropriate response timeouts -- Validate payload structure before processing \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/blocks/workflow.mdx b/apps/docs/content/docs/en/yaml/blocks/workflow.mdx deleted file mode 100644 index bfdfbbc1c3..0000000000 --- a/apps/docs/content/docs/en/yaml/blocks/workflow.mdx +++ /dev/null @@ -1,299 +0,0 @@ ---- -title: Workflow Block YAML Schema -description: YAML configuration reference for Workflow blocks ---- - -## Schema Definition - -```yaml -type: object -required: - - type - - name - - inputs -properties: - type: - type: string - enum: [workflow] - description: Block type identifier - name: - type: string - description: Display name for this workflow block - inputs: - type: object - required: - - workflowId - properties: - workflowId: - type: string - description: ID of the workflow to execute - inputMapping: - type: object - description: Map current workflow data to sub-workflow inputs - additionalProperties: - type: string - description: Input value or reference to parent workflow data - environmentVariables: - type: object - description: Environment variables to pass to sub-workflow - additionalProperties: - type: string - description: Environment variable value - timeout: - type: number - description: Maximum execution time in milliseconds - default: 300000 - minimum: 1000 - maximum: 1800000 - connections: - type: object - properties: - success: - type: string - description: Target block ID for successful workflow completion - error: - type: string - description: Target block ID for error handling -``` - -## Connection Configuration - -Connections define where the workflow goes based on sub-workflow results: - -```yaml -connections: - success: # Target block ID for successful completion - error: # Target block ID for error handling (optional) -``` - -## Examples - -### Simple Workflow Execution - -```yaml -data-processor: - type: workflow - name: "Data Processing Workflow" - inputs: - workflowId: "data-processing-v2" - inputMapping: - rawData: - userId: - environmentVariables: - PROCESSING_MODE: "production" - LOG_LEVEL: "info" - connections: - success: process-results - error: workflow-error-handler -``` - -### Content Generation Pipeline - -```yaml -content-generator: - type: workflow - name: "Content Generation Pipeline" - inputs: - workflowId: "content-generation-v3" - inputMapping: - topic: - style: - targetAudience: - brandGuidelines: - environmentVariables: - CONTENT_API_KEY: "{{CONTENT_API_KEY}}" - QUALITY_THRESHOLD: "high" - timeout: 120000 - connections: - success: review-content - error: content-generation-failed -``` - -### Multi-Step Analysis Workflow - -```yaml -analysis-workflow: - type: workflow - name: "Analysis Workflow" - inputs: - workflowId: "comprehensive-analysis" - inputMapping: - document: - analysisType: "comprehensive" - includeMetrics: true - outputFormat: "structured" - environmentVariables: - ANALYSIS_MODEL: "gpt-4o" - OPENAI_API_KEY: "{{OPENAI_API_KEY}}" - CLAUDE_API_KEY: "{{CLAUDE_API_KEY}}" - connections: - success: compile-analysis-report - error: analysis-workflow-error -``` - -### Conditional Workflow Execution - -```yaml -customer-workflow-router: - type: condition - name: "Customer Workflow Router" - inputs: - conditions: - if: === "enterprise" - else-if: === "premium" - else: true - connections: - conditions: - if: enterprise-workflow - else-if: premium-workflow - else: standard-workflow - -enterprise-workflow: - type: workflow - name: "Enterprise Customer Workflow" - inputs: - workflowId: "enterprise-customer-processing" - inputMapping: - customerData: - accountManager: - tier: "enterprise" - environmentVariables: - PRIORITY_LEVEL: "high" - SLA_REQUIREMENTS: "strict" - connections: - success: enterprise-complete - -premium-workflow: - type: workflow - name: "Premium Customer Workflow" - inputs: - workflowId: "premium-customer-processing" - inputMapping: - customerData: - supportLevel: "premium" - environmentVariables: - PRIORITY_LEVEL: "medium" - connections: - success: premium-complete - -standard-workflow: - type: workflow - name: "Standard Customer Workflow" - inputs: - workflowId: "standard-customer-processing" - inputMapping: - customerData: - environmentVariables: - PRIORITY_LEVEL: "standard" - connections: - success: standard-complete -``` - -### Parallel Workflow Execution - -```yaml -parallel-workflows: - type: parallel - name: "Parallel Workflow Processing" - inputs: - parallelType: collection - collection: | - [ - {"workflowId": "sentiment-analysis", "focus": "sentiment"}, - {"workflowId": "topic-extraction", "focus": "topics"}, - {"workflowId": "entity-recognition", "focus": "entities"} - ] - connections: - success: merge-workflow-results - -execute-analysis-workflow: - type: workflow - name: "Execute Analysis Workflow" - parentId: parallel-workflows - inputs: - workflowId: - inputMapping: - content: - analysisType: - environmentVariables: - ANALYSIS_API_KEY: "{{ANALYSIS_API_KEY}}" - connections: - success: workflow-complete -``` - -### Error Handling Workflow - -```yaml -main-workflow: - type: workflow - name: "Main Processing Workflow" - inputs: - workflowId: "main-processing-v1" - inputMapping: - data: - timeout: 180000 - connections: - success: main-complete - error: error-recovery-workflow - -error-recovery-workflow: - type: workflow - name: "Error Recovery Workflow" - inputs: - workflowId: "error-recovery-v1" - inputMapping: - originalInput: - errorDetails: - failureTimestamp: "{{new Date().toISOString()}}" - environmentVariables: - RECOVERY_MODE: "automatic" - FALLBACK_ENABLED: "true" - connections: - success: recovery-complete - error: manual-intervention-required -``` - -## Input Mapping - -Map data from the parent workflow to the sub-workflow: - -```yaml -inputMapping: - # Static values - mode: "production" - version: "1.0" - - # References to parent workflow data - userData: - settings: - - # Complex object mapping - requestData: - id: - timestamp: "{{new Date().toISOString()}}" - source: "parent-workflow" -``` - -## Output References - -After a workflow block completes, you can reference its outputs: - -```yaml -# In subsequent blocks -next-block: - inputs: - workflowResult: # Sub-workflow output - executionTime: # Execution duration - status: # Execution status -``` - -## Best Practices - -- Use descriptive workflow IDs for clarity -- Map only necessary data to sub-workflows -- Set appropriate timeouts for workflow complexity -- Include error handling for robust execution -- Pass environment variables securely -- Test sub-workflows independently first -- Monitor nested workflow performance -- Use versioned workflow IDs for stability \ No newline at end of file diff --git a/apps/docs/content/docs/en/yaml/examples.mdx b/apps/docs/content/docs/en/yaml/examples.mdx deleted file mode 100644 index b807185219..0000000000 --- a/apps/docs/content/docs/en/yaml/examples.mdx +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: YAML Workflow Examples -description: Examples of complete YAML workflows ---- - -import { Tab, Tabs } from 'fumadocs-ui/components/tabs' - -## Multi-Agent Chain Workflow - -A workflow where multiple AI agents process information sequentially: - -```yaml -version: '1.0' -blocks: - start: - type: starter - name: Start - inputs: - startWorkflow: manual - connections: - success: agent-1-initiator - - agent-1-initiator: - type: agent - name: Agent 1 Initiator - inputs: - systemPrompt: You are the first agent in a chain. Your role is to analyze the input and create an initial response that will be passed to the next agent. - userPrompt: |- - Welcome! I'm the first agent in our chain. - - Input to process: - - Please create an initial analysis or greeting that the next agent can build upon. Be creative and set a positive tone for the chain! - model: gpt-4o - temperature: 0.7 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: agent-2-enhancer - - agent-2-enhancer: - type: agent - name: Agent 2 Enhancer - inputs: - systemPrompt: You are the second agent in a chain. Take the output from Agent 1 and enhance it with additional insights or improvements. - userPrompt: |- - I'm the second agent! Here's what Agent 1 provided: - - - - Now I'll enhance this with additional details, insights, or improvements. Let me build upon their work! - model: gpt-4o - temperature: 0.7 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: agent-3-refiner - - agent-3-refiner: - type: agent - name: Agent 3 Refiner - inputs: - systemPrompt: You are the third agent in a chain. Take the enhanced output from Agent 2 and refine it further, adding structure or organization. - userPrompt: |- - I'm the third agent in our chain! Here's the enhanced work from Agent 2: - - - - My job is to refine and organize this content. I'll add structure, clarity, and polish to make it even better! - model: gpt-4o - temperature: 0.6 - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: agent-4-finalizer - - agent-4-finalizer: - type: agent - name: Agent 4 Finalizer - inputs: - systemPrompt: You are the final agent in a chain of 4. Create a comprehensive summary and conclusion based on all the previous agents' work. - userPrompt: |- - I'm the final agent! Here's the refined work from Agent 3: - - - - As the last agent in our chain, I'll create a final, polished summary that brings together all the work from our team of 4 agents. Let me conclude this beautifully! - model: gpt-4o - temperature: 0.5 - apiKey: '{{OPENAI_API_KEY}}' -``` - -## Router-Based Conditional Workflow - -A workflow that uses routing logic to send data to different agents based on conditions: - -```yaml -version: '1.0' -blocks: - start: - type: starter - name: Start - inputs: - startWorkflow: manual - connections: - success: router-1 - - router-1: - type: router - name: Router 1 - inputs: - prompt: go to agent 1 if is greater than 5. else agent 2 if greater than 10. else agent 3 - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: - - agent-1 - - agent-2 - - agent-3 - - agent-1: - type: agent - name: Agent 1 - inputs: - systemPrompt: say 1 - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - - agent-2: - type: agent - name: Agent 2 - inputs: - systemPrompt: say 2 - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - - agent-3: - type: agent - name: Agent 3 - inputs: - systemPrompt: say 3 - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' -``` - -## Web Search with Structured Output - -A workflow that searches the web using tools and returns structured data: - -```yaml -version: '1.0' -blocks: - 59eb07c1-1411-4b28-a274-fa78f55daf72: - type: starter - name: Start - inputs: - startWorkflow: manual - connections: - success: d77c2c98-56c4-432d-9338-9bac54a2d42f - d77c2c98-56c4-432d-9338-9bac54a2d42f: - type: agent - name: Agent 1 - inputs: - systemPrompt: look up the user input. use structured output - userPrompt: - model: claude-sonnet-4-0 - apiKey: '{{ANTHROPIC_API_KEY}}' - tools: - - type: exa - title: Exa - params: - type: auto - apiKey: '{{EXA_API_KEY}}' - numResults: '' - toolId: exa_search - operation: exa_search - isExpanded: true - usageControl: auto - responseFormat: |- - { - "name": "output_schema", - "description": "Defines the structure for an output object.", - "strict": true, - "schema": { - "type": "object", - "properties": { - "output": { - "type": "string", - "description": "The output value" - } - }, - "additionalProperties": false, - "required": ["output"] - } - } -``` - -## Loop Processing with Collection - -A workflow that processes each item in a collection using a loop: - -```yaml -version: '1.0' -blocks: - start: - type: starter - name: Start - inputs: - startWorkflow: manual - connections: - success: food-analysis-loop - food-analysis-loop: - type: loop - name: Food Analysis Loop - inputs: - count: 5 - loopType: forEach - collection: '["apple", "banana", "carrot"]' - connections: - loop: - start: calorie-agent - calorie-agent: - type: agent - name: Calorie Analyzer - inputs: - systemPrompt: Return the number of calories in the food - userPrompt: - model: claude-sonnet-4-0 - apiKey: '{{ANTHROPIC_API_KEY}}' - parentId: food-analysis-loop -``` - -## Email Classification and Response - -A workflow that classifies emails and generates appropriate responses: - -```yaml -version: '1.0' -blocks: - start: - type: starter - name: Start - inputs: - startWorkflow: manual - connections: - success: email-classifier - - email-classifier: - type: agent - name: Email Classifier - inputs: - systemPrompt: Classify emails into categories and extract key information. - userPrompt: | - Classify this email: - - Categories: support, billing, sales, feedback - Extract: urgency level, customer sentiment, main request - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' - connections: - success: response-generator - - response-generator: - type: agent - name: Response Generator - inputs: - systemPrompt: Generate appropriate responses based on email classification. - userPrompt: | - Email classification: - Original email: - - Generate a professional, helpful response addressing the customer's needs. - model: gpt-4o - temperature: 0.7 - apiKey: '{{OPENAI_API_KEY}}' -``` diff --git a/apps/docs/content/docs/en/yaml/index.mdx b/apps/docs/content/docs/en/yaml/index.mdx deleted file mode 100644 index 8318537324..0000000000 --- a/apps/docs/content/docs/en/yaml/index.mdx +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: YAML Workflow Reference -description: Complete guide to writing YAML workflows in Sim ---- - -import { Card, Cards } from "fumadocs-ui/components/card"; -import { Step, Steps } from "fumadocs-ui/components/steps"; -import { Tab, Tabs } from "fumadocs-ui/components/tabs"; - -YAML workflows provide a powerful way to define, version, and share workflow configurations in Sim. This reference guide covers the complete YAML syntax, block schemas, and best practices for creating robust workflows. - -## Quick Start - -Every Sim workflow follows this basic structure: - -```yaml -version: '1.0' -blocks: - start: - type: starter - name: Start - inputs: - startWorkflow: manual - connections: - success: agent-1 - - agent-1: - type: agent - name: "AI Assistant" - inputs: - systemPrompt: "You are a helpful assistant." - userPrompt: 'Hi' - model: gpt-4o - apiKey: '{{OPENAI_API_KEY}}' -``` - -## Core Concepts - - - - Version Declaration: Must be exactly `version: '1.0'` (with quotes) - - - Blocks Structure: All workflow blocks are defined under the `blocks` key - - - Block References: Use block names in lowercase with spaces removed (e.g., ``) - - - Environment Variables: Reference with double curly braces `{{VARIABLE_NAME}}` - - - -## Block Types - -Sim supports several core block types, each with specific YAML schemas: - - - - Workflow entry point with support for manual, webhook, and scheduled triggers - - - AI-powered processing with support for tools and structured output - - - Custom JavaScript/TypeScript code execution - - - HTTP requests to external services - - - Conditional branching based on boolean expressions - - - AI-powered intelligent routing to multiple paths - - - Iterative processing with for and forEach loops - - - Concurrent execution across multiple instances - - - Webhook triggers for external integrations - - - Validate outputs against defined criteria and metrics - - - Execute other workflows as reusable components - - - Final workflow output formatting - - - -## Block Reference Syntax - -The most critical aspect of YAML workflows is understanding how to reference data between blocks: - -### Basic Rules - -1. **Use the block name** (not the block ID) converted to lowercase with spaces removed -2. **Add the appropriate property** (.content for agents, .output for tools) -3. **When using chat, reference the starter block** as `` - -### Examples - -```yaml -# Block definitions -email-processor: - type: agent - name: "Email Agent" - # ... configuration - -data-formatter: - type: function - name: "Data Agent" - # ... configuration - -# Referencing their outputs -next-block: - type: agent - name: "Next Step" - inputs: - userPrompt: | - Process this email: - Use this formatted data: - Original input: -``` - -### Special Cases - -- **Loop Variables**: ``, ``, `` -- **Parallel Variables**: ``, `` - -## Environment Variables - -Use environment variables for sensitive data like API keys: - -```yaml -inputs: - apiKey: '{{OPENAI_API_KEY}}' - database: '{{DATABASE_URL}}' - token: '{{SLACK_BOT_TOKEN}}' -``` - -## Best Practices - -- **Keep block names human-readable**: "Email Processor" for UI display -- **Reference environment variables**: Never hardcode API keys -- **Structure for readability**: Group related blocks logically -- **Test incrementally**: Build workflows step by step - -## Next Steps - -- [Block Reference Syntax](/yaml/block-reference) - Detailed reference rules -- [Complete Block Schemas](/yaml/blocks) - All available block types -- [Workflow Examples](/yaml/examples) - Real-world workflow patterns \ No newline at end of file