github/sim
1
0
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-01-09 15:07:55 -05:00
Code Issues Packages Projects Releases Wiki Activity

feat(copilot-v1): Copilot v1 (#662)

Browse Source 
* Fix docs agent

* Doc agent fixes

* Refactor copilot

* Lint

* Update yaml editor

* Lint

* Fix block tool

* Lint

* Get block metadata tool

* Lint

* Yaml changes

* Lint

* Fixes?

* Lint

* Better yaml language

* Lint

* UPdate

* Lint

* Fix condition blocks

* lint

* Fix start block

* Fix starter block stuff

* Lint

* Fix yaml ui

* Lint

* get yaml tool

* Lint

* hi

* Lint

* Agnet

* Copilot UI

* Lint

* Better workflow builder

* Lint

* REHYDRATION

* Lint

* Auto layout

* Lint

* Fixes

* Lint

* Chatbar sizing

* Lint

* Initial chat fixes

* Lint

* Dropdown overflow

* Lint

* UI text

* Lint

* Sample question pills

* Lint

* Ui button

* Fix dropdown appearance

* Lint

* Modal fixes

* UI Updates

* Lint

* Initial ask vs agent mode

* Lint

* Ask vs agent

* Lint

* Ask udpate

* Ui fixes

* Lint

* User message width

* Chat leak fix

* Lint

* Agent ui

* Checkpointing

* Lint

* Checkpoints

* Lint

* Tweaks

* Sample questions

* Lint

* Modal full screen mode

* Lint

* Prompt updates

* Cleaning

* Lint

* Prompt update

* Streaming v1

* Lint

* Tool call inline

* Lint

* Checkpoint

* Lint

* Fix lint

* Sizing

* Lint

* Copilot ui tool call fixes

* Remove output from tool call ui

* Updates

* Lint

* Checkpoitn

* Loading icon

* Lint

* Pulse

* Lint

* Modal fixes

* Sidebar padding

* Checkpoint

* checkpoint

* feat(platform): new UI and templates (#639) (#693)

* improvement: control bar

* improvement: debug flow

* improvement: control bar hovers and skeleton loading

* improvement: completed control bar

* improvement: panel tab selector complete

* refactor: deleted notifications and history dropdown

* improvement: chat UI complete

* fix: tab change on control bar run

* improvement: finshed console (audio display not working)

* fix: text wrapping in console content

* improvement: audio UI

* improvement: image display

* feat: add input to console

* improvement: code input and showing input on errors

* feat: download chat and console

* improvement: expandable panel and console visibility

* improvement: empty state UI

* improvement: finished variables

* fix: image in console entry

* improvement: sidebar and templates ui

* feat: uploading and fetching templates

* improvement: sidebar and control bar

* improvement: templates

* feat: templates done

* fix(sockets): remove package-lock

* fix: sidebar scroll going over sidebar height (#709)

* Checkpoint

* Fix build error

* Checkpoitn

* Docs updates

* Checkpoint

* Streaming vs non streaming

* Clean up yaml save

* Fix revert checkpoitn yaml

* Doc fixes

* Small docs fix

* Clean up old yaml docs

* Doc updates

* Hide copilot

* Revert width

* Db migration fixes

* Add snapshot

* Remove space from mdx

* Add spaces

* Lint

* Address greptile comments

* lint fix

* Hide copilot

---------

Co-authored-by: Vikhyath Mondreti <vikhyathvikku@gmail.com>
Co-authored-by: Waleed Latif <walif6@gmail.com>
Co-authored-by: Emir Karabeg <78010029+emir-karabeg@users.noreply.github.com>
Co-authored-by: Siddharth Sim <sidstudio@SiddharthsMBP2.attlocal.net>
This commit is contained in:
Siddharth Ganesan
2025-07-22 13:02:24 -07:00
committed by GitHub
parent 31d909bb82
commit 5158a00b54
96 changed files with 19711 additions and 2681 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
apps/docs/content/docs/blocks/loop.mdx
View File

@@ -172,4 +172,4 @@ After a loop completes, you can access aggregated results:
- **Set reasonable limits**: Keep iteration counts reasonable to avoid long execution times
- **Use ForEach for collections**: When processing arrays or objects, use ForEach instead of For loops
- **Handle errors gracefully**: Consider adding error handling inside loops for robust workflows
- **Handle errors gracefully**: Consider adding error handling inside loops for robust workflows

2
apps/docs/content/docs/blocks/parallel.mdx
View File

@@ -207,4 +207,4 @@ Understanding when to use each:
- **Independent operations only**: Ensure operations don't depend on each other
- **Handle rate limits**: Add delays or throttling for API-heavy workflows
- **Error handling**: Each instance should handle its own errors gracefully
- **Error handling**: Each instance should handle its own errors gracefully

3
apps/docs/content/docs/blocks/response.mdx
View File

@@ -182,4 +182,5 @@ headers:
- **Structure your responses consistently**: Maintain a consistent JSON structure across all your API endpoints for better developer experience
- **Include relevant metadata**: Add timestamps and version information to help with debugging and monitoring
- **Handle errors gracefully**: Use conditional logic in your workflow to set appropriate error responses with descriptive messages
- **Validate variable references**: Ensure all referenced variables exist and contain the expected data types before the Response block executes
- **Validate variable references**: Ensure all referenced variables exist and contain the expected data types before the Response block executes

2
apps/docs/content/docs/blocks/workflow.mdx
View File

@@ -256,4 +256,4 @@ return {
- **Document dependencies**: Clearly document which workflows depend on others and maintain dependency maps
- **Test independently**: Ensure child workflows can be tested and validated independently from parent workflows
- **Monitor performance**: Be aware that nested workflows can impact overall execution time and resource usage
- **Use semantic naming**: Give workflows descriptive names that clearly indicate their purpose and functionality
- **Use semantic naming**: Give workflows descriptive names that clearly indicate their purpose and functionality

1
apps/docs/content/docs/meta.json
View File

@@ -14,6 +14,7 @@
"execution",
"---Advanced---",
"./variables/index",
"yaml",
"---SDKs---",
"./sdks/python",
"./sdks/typescript"

11
apps/docs/content/docs/tools/index.mdx
View File

@@ -64,3 +64,14 @@ Tools typically return structured data that can be processed by subsequent block
- Status information
Refer to each tool's specific documentation to understand its exact output format.
## YAML Configuration
For detailed YAML workflow configuration and syntax, see the [YAML Workflow Reference](/yaml) documentation. This includes comprehensive guides for:
- **Block Reference Syntax**: How to connect and reference data between blocks
- **Tool Configuration**: Using tools in both standalone blocks and agent configurations
- **Environment Variables**: Secure handling of API keys and credentials
- **Complete Examples**: Real-world workflow patterns and configurations
For specific tool parameters and configuration options, refer to each tool's individual documentation page.

238
apps/docs/content/docs/yaml/block-reference.mdx Normal file
View File

@@ -0,0 +1,238 @@
---
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 Studio 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
<Tabs items={['Correct', 'Incorrect']}>
<Tab>
```yaml
# Block definition
email-sender:
type: agent
name: "Email Generator"
# ... configuration
# Reference the block
next-block:
inputs:
userPrompt: "Process this: <emailgenerator.content>"
```
</Tab>
<Tab>
```yaml
# Block definition
email-sender:
type: agent
name: "Email Generator"
# ... configuration
# ❌ Don't reference by block ID
next-block:
inputs:
userPrompt: "Process this: <email-sender.content>"
```
</Tab>
</Tabs>
### 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**: `<emailgenerator.content>`
### 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
<agentname.content> # Primary AI response
<agentname.tokens> # Token usage information
<agentname.cost> # Estimated cost
<agentname.tool_calls> # Tool execution details
# Function block outputs
<functionname.output> # Function return value
<functionname.error> # Error information (if any)
# API block outputs
<apiname.output> # Response data
<apiname.status> # HTTP status code
<apiname.headers> # Response headers
# Tool block outputs
<toolname.output> # Tool execution result
```
### Multi-Word Block Names
```yaml
# Block name: "Data Processor 2"
<dataprocessor2.output>
# Block name: "Email Validation Service"
<emailvalidationservice.output>
# Block name: "Customer Info Agent"
<customerinfoagent.content>
```
## Special Reference Cases
### Starter Block
<Callout type="warning">
The starter block is always referenced as `<start.input>` regardless of its actual name.
</Callout>
```yaml
# Starter block definition
my-custom-start:
type: starter
name: "Custom Workflow Start"
# ... configuration
# Always reference as 'start'
agent-1:
inputs:
userPrompt: <start.input> # ✅ Correct
# userPrompt: <customworkflowstart.input> # ❌ Wrong
```
### Loop Variables
Inside loop blocks, special variables are available:
```yaml
# Available in loop child blocks
<loop.index> # Current iteration (0-based)
<loop.currentItem> # Current item being processed (forEach loops)
<loop.items> # Full collection (forEach loops)
```
### Parallel Variables
Inside parallel blocks, special variables are available:
```yaml
# Available in parallel child blocks
<parallel.index> # Instance number (0-based)
<parallel.currentItem> # Item for this instance
<parallel.items> # 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: <dataanalyzer.analysis.summary>
Score: <dataanalyzer.metrics.score>
Full data: <dataanalyzer.content>
```
### Multiple References in Text
```yaml
email-composer:
type: agent
inputs:
userPrompt: |
Create an email with the following information:
Customer: <customeragent.content>
Order Details: <orderprocessor.output>
Support Ticket: <ticketanalyzer.content>
Original request: <start.input>
```
### 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 = <customeragent.content>;
const orderInfo = <orderprocessor.output>;
const originalInput = <start.input>;
// Process the data
return {
customer: customerData.name,
orderId: orderInfo.id,
processed: true
};
```
## Reference Validation
Sim Studio 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

218
apps/docs/content/docs/yaml/blocks/agent.mdx Normal file
View File

@@ -0,0 +1,218 @@
---
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: <string> # Tool type identifier (exa, gmail, slack, etc.)
title: <string> # Human-readable display name
toolId: <string> # Internal tool identifier
operation: <string> # Tool operation/method name
usageControl: <string> # When AI can use it (auto | required | none)
params: <object> # Tool-specific configuration parameters
isExpanded: <boolean> # UI state (optional, default: false)
```
## Connection Configuration
Connections define where the workflow goes based on execution results:
```yaml
connections:
success: <string> # Target block ID for successful execution
error: <string> # 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: <start.input>
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: <contentanalyzer1.content>"
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: <start.input>
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: <start.input>
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: <start.input>
model: gpt-4o
apiKey: '{{AZURE_OPENAI_API_KEY}}'
azureEndpoint: '{{AZURE_OPENAI_ENDPOINT}}'
azureApiVersion: "2024-07-01-preview"
connections:
success: response-block
```

179
apps/docs/content/docs/yaml/blocks/api.mdx Normal file
View File

@@ -0,0 +1,179 @@
---
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
queryParams:
type: array
description: Query parameters as key-value pairs
items:
type: object
properties:
key:
type: string
description: Parameter name
value:
type: string
description: Parameter value
headers:
type: array
description: HTTP headers as key-value pairs
items:
type: object
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: <string> # Target block ID for successful requests
error: <string> # 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:
- key: "Authorization"
value: "Bearer {{API_TOKEN}}"
- 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:
- key: "Authorization"
value: "Bearer {{SUPPORT_API_KEY}}"
- key: "Content-Type"
value: "application/json"
body: |
{
"title": "<agent.title>",
"description": "<agent.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
queryParams:
- key: "q"
value: <start.searchTerm>
- key: "limit"
value: "10"
- key: "category"
value: <filter.category>
headers:
- key: "Authorization"
value: "Bearer {{STORE_API_KEY}}"
connections:
success: display-results
```
## Output References
After an API block executes, you can reference its outputs:
```yaml
# In subsequent blocks
next-block:
inputs:
data: <api-block-name.output> # Response data
status: <api-block-name.status> # HTTP status code
headers: <api-block-name.headers> # Response headers
error: <api-block-name.error> # Error details (if any)
```
## 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

165
apps/docs/content/docs/yaml/blocks/condition.mdx Normal file
View File

@@ -0,0 +1,165 @@
---
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: <string> # Target block ID when primary condition is true
else-if: <string> # Target block ID when secondary condition is true (optional)
else-if-2: <string> # Target block ID when third condition is true (optional)
else-if-3: <string> # Target block ID when fourth condition is true (optional)
# Additional else-if-N connections can be added as needed
else: <string> # Target block ID when no conditions match (optional)
```
## Examples
### Simple If-Else
```yaml
status-check:
type: condition
name: "Status Check"
inputs:
conditions:
if: <start.status> === "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: <start.user_type> === "admin"
else-if: <start.user_type> === "premium"
else-if-2: <start.user_type> === "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: <agent.score> >= 90
else-if: <agent.score> >= 70
else-if-2: <agent.score> >= 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: <start.age> >= 18 && <start.verified> === true
else-if: <start.age> >= 16 && <start.parent_consent> === true
else: true
connections:
conditions:
if: full-access
else-if: limited-access
else: access-denied
```

255
apps/docs/content/docs/yaml/blocks/evaluator.mdx Normal file
View File

@@ -0,0 +1,255 @@
---
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: <string> # Target block ID for successful evaluation
error: <string> # Target block ID for error handling (optional)
```
## Examples
### Content Quality Evaluation
```yaml
content-evaluator:
type: evaluator
name: "Content Quality Evaluator"
inputs:
content: <content-generator.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: <customer-agent.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-a.content>
Version B: <version-b.content>
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: <ai-writer.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: <evaluator-name.content> # Evaluation summary
scores: <evaluator-name.scores> # Individual metric scores
overall: <evaluator-name.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

162
apps/docs/content/docs/yaml/blocks/function.mdx Normal file
View File

@@ -0,0 +1,162 @@
---
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: <string> # Target block ID for successful execution
error: <string> # 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(<start.input>, 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 = <start.input>;
// 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 = <agent.response>;
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 = <start.input>;
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
```

151
apps/docs/content/docs/yaml/blocks/index.mdx Normal file
View File

@@ -0,0 +1,151 @@
---
title: Block Schemas
description: Complete YAML schema reference for all Sim Studio blocks
---
import { Card, Cards } from "fumadocs-ui/components/card";
This section contains the complete YAML schema definitions for all available block types in Sim Studio. Each block type has specific configuration requirements and output formats.
## Core Blocks
These are the essential building blocks for creating workflows:
<Cards>
<Card title="Starter Block" href="/yaml/blocks/starter">
Workflow entry point supporting manual triggers, webhooks, and schedules
</Card>
<Card title="Agent Block" href="/yaml/blocks/agent">
AI-powered processing with LLM integration and tool support
</Card>
<Card title="Function Block" href="/yaml/blocks/function">
Custom JavaScript/TypeScript code execution environment
</Card>
<Card title="Response Block" href="/yaml/blocks/response">
Format and return final workflow results
</Card>
</Cards>
## Logic & Control Flow
Blocks for implementing conditional logic and control flow:
<Cards>
<Card title="Condition Block" href="/yaml/blocks/condition">
Conditional branching based on boolean expressions
</Card>
<Card title="Router Block" href="/yaml/blocks/router">
AI-powered intelligent routing to multiple paths
</Card>
<Card title="Loop Block" href="/yaml/blocks/loop">
Iterative processing with for and forEach loops
</Card>
<Card title="Parallel Block" href="/yaml/blocks/parallel">
Concurrent execution across multiple instances
</Card>
</Cards>
## Integration Blocks
Blocks for connecting to external services and systems:
<Cards>
<Card title="API Block" href="/yaml/blocks/api">
HTTP requests to external REST APIs
</Card>
<Card title="Webhook Block" href="/yaml/blocks/webhook">
Webhook triggers for external integrations
</Card>
</Cards>
## Advanced Blocks
Specialized blocks for complex workflow patterns:
<Cards>
<Card title="Evaluator Block" href="/yaml/blocks/evaluator">
Validate outputs against defined criteria and metrics
</Card>
<Card title="Workflow Block" href="/yaml/blocks/workflow">
Execute other workflows as reusable components
</Card>
</Cards>
## Common Schema Elements
All blocks share these common elements:
### Basic Structure
```yaml
block-id:
type: <block-type>
name: <display-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: <blockname.content>
data: <functionblock.output>
originalInput: <start.input>
```
## 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

305
apps/docs/content/docs/yaml/blocks/loop.mdx Normal file
View File

@@ -0,0 +1,305 @@
---
title: Loop Block YAML Schema
description: YAML configuration reference for Loop blocks
---
## Schema Definition
```yaml
type: object
required:
- type
- name
- inputs
- connections
properties:
type:
type: string
enum: [loop]
description: Block type identifier
name:
type: string
description: Display name for this loop block
inputs:
type: object
required:
- loopType
properties:
loopType:
type: string
enum: [for, forEach]
description: Type of loop to execute
iterations:
type: number
description: Number of iterations (for 'for' loops)
minimum: 1
maximum: 1000
collection:
type: string
description: Collection to iterate over (for 'forEach' loops)
maxConcurrency:
type: number
description: Maximum concurrent executions
default: 1
minimum: 1
maximum: 10
connections:
type: object
required:
- loop
properties:
loop:
type: object
required:
- start
properties:
start:
type: string
description: Target block ID to execute inside the loop
end:
type: string
description: Target block ID for loop completion (optional)
success:
type: string
description: Target block ID after loop completion (alternative format)
error:
type: string
description: Target block ID for error handling
```
## Connection Configuration
Loop blocks use a special connection format with a `loop` section:
```yaml
connections:
loop:
start: <string> # Target block ID to execute inside the loop
end: <string> # Target block ID after loop completion (optional)
error: <string> # Target block ID for error handling (optional)
```
Alternative format (legacy):
```yaml
connections:
success: <string> # Target block ID after loop completion
error: <string> # Target block ID for error handling (optional)
```
## Child Block Configuration
Blocks inside a loop must have their `parentId` set to the loop block ID:
```yaml
loop-1:
type: loop
name: "Process Items"
inputs:
loopType: forEach
collection: <start.items>
connections:
loop:
start: process-item
end: final-results
# Child block inside the loop
process-item:
type: agent
name: "Process Item"
parentId: loop-1 # References the loop block
inputs:
systemPrompt: "Process this item"
userPrompt: <loop.currentItem>
model: gpt-4o
apiKey: '{{OPENAI_API_KEY}}'
```
## Examples
### For Loop (Fixed Iterations)
```yaml
countdown-loop:
type: loop
name: "Countdown Loop"
inputs:
loopType: for
iterations: 5
connections:
loop:
start: countdown-agent
end: countdown-complete
countdown-agent:
type: agent
name: "Countdown Agent"
parentId: countdown-loop
inputs:
systemPrompt: "Generate a countdown message"
userPrompt: "Count down from 5. Current number: <loop.index>"
model: gpt-4o
apiKey: '{{OPENAI_API_KEY}}'
```
### ForEach Loop (Collection Processing)
```yaml
email-processor-loop:
type: loop
name: "Email Processor Loop"
inputs:
loopType: forEach
collection: <start.emails>
connections:
loop:
start: process-single-email
end: all-emails-processed
process-single-email:
type: agent
name: "Process Single Email"
parentId: email-processor-loop
inputs:
systemPrompt: "Classify and respond to this email"
userPrompt: "Email content: <loop.currentItem>"
model: gpt-4o
apiKey: '{{OPENAI_API_KEY}}'
```
### Complex Loop with Multiple Child Blocks
```yaml
data-analysis-loop:
type: loop
name: "Data Analysis Loop"
inputs:
loopType: forEach
collection: <data-fetcher.records>
maxConcurrency: 3
connections:
loop:
start: validate-record
end: generate-report
error: handle-loop-error
validate-record:
type: function
name: "Validate Record"
parentId: data-analysis-loop
inputs:
code: |
const record = <loop.currentItem>;
const index = <loop.index>;
// Validate the record
if (!record.id || !record.data) {
throw new Error(`Invalid record at index ${index}`);
}
return {
valid: true,
recordId: record.id,
processedAt: new Date().toISOString()
};
connections:
success: analyze-record
error: record-error
analyze-record:
type: agent
name: "Analyze Record"
parentId: data-analysis-loop
inputs:
systemPrompt: "Analyze this data record and extract insights"
userPrompt: |
Record ID: <validaterecord.recordId>
Data: <loop.currentItem.data>
Position in collection: <loop.index>
model: gpt-4o
apiKey: '{{OPENAI_API_KEY}}'
connections:
success: store-analysis
store-analysis:
type: function
name: "Store Analysis"
parentId: data-analysis-loop
inputs:
code: |
const analysis = <analyzerecord.content>;
const recordId = <validaterecord.recordId>;
// Store analysis result
return {
recordId,
analysis,
completedAt: new Date().toISOString()
};
```
### Concurrent Processing Loop
```yaml
parallel-processing-loop:
type: loop
name: "Parallel Processing Loop"
inputs:
loopType: forEach
collection: <start.tasks>
maxConcurrency: 5
connections:
loop:
start: process-task
end: aggregate-results
process-task:
type: api
name: "Process Task"
parentId: parallel-processing-loop
inputs:
url: "https://api.example.com/process"
method: POST
headers:
- key: "Authorization"
value: "Bearer {{API_TOKEN}}"
body: |
{
"taskId": "<loop.currentItem.id>",
"data": "<loop.currentItem.data>"
}
connections:
success: task-completed
```
## Loop Variables
Inside loop child blocks, these special variables are available:
```yaml
# Available in all child blocks of the loop
<loop.index> # Current iteration number (0-based)
<loop.currentItem> # Current item being processed (forEach loops)
<loop.items> # Full collection (forEach loops)
```
## Output References
After a loop completes, you can reference its aggregated results:
```yaml
# In blocks after the loop
final-processor:
inputs:
all-results: <loop-name.results> # Array of all iteration results
total-count: <loop-name.count> # Number of iterations completed
```
## Best Practices
- Set reasonable iteration limits to avoid long execution times
- Use forEach for collection processing, for loops for fixed iterations
- Consider using maxConcurrency for I/O bound operations
- Include error handling for robust loop execution
- Use descriptive names for loop child blocks
- Test with small collections first
- Monitor execution time for large collections

17
apps/docs/content/docs/yaml/blocks/meta.json Normal file
View File

@@ -0,0 +1,17 @@
{
"title": "Block Schemas",
"pages": [
"starter",
"agent",
"function",
"api",
"condition",
"router",
"evaluator",
"response",
"loop",
"parallel",
"webhook",
"workflow"
]
}

322
apps/docs/content/docs/yaml/blocks/parallel.mdx Normal file
View File

@@ -0,0 +1,322 @@
---
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)
success:
type: string
description: Target block ID after all instances complete (alternative format)
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: <string> # Target block ID to execute inside each parallel instance
end: <string> # Target block ID after all instances complete (optional)
error: <string> # Target block ID for error handling (optional)
```
Alternative format (legacy):
```yaml
connections:
success: <string> # Target block ID after all instances complete
error: <string> # 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: <start.items>
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: <parallel.currentItem>
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": <parallel.index>,
"timestamp": "{{new Date().toISOString()}}"
}
connections:
success: worker-complete
```
### Collection-Based Parallel Processing
```yaml
api-parallel:
type: parallel
name: "API Parallel"
inputs:
parallelType: collection
collection: <start.apiEndpoints>
maxConcurrency: 10
connections:
parallel:
start: call-api
end: merge-api-results
call-api:
type: api
name: "Call API"
parentId: api-parallel
inputs:
url: <parallel.currentItem.endpoint>
method: <parallel.currentItem.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: <data-loader.records>
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 = <parallel.currentItem>;
const index = <parallel.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: <validatedata.recordId>
Content: <parallel.currentItem.content>
Instance: <parallel.index>
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 = <processdata.content>;
const recordId = <validatedata.recordId>;
return {
recordId,
processed,
completedAt: new Date().toISOString(),
instanceIndex: <parallel.index>
};
```
### 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 <parallel.currentItem.focus>.
Provide detailed analysis from this perspective.
userPrompt: |
Content to analyze: <start.content>
Analysis focus: <parallel.currentItem.focus>
model: <parallel.currentItem.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
<parallel.index> # Instance number (0-based)
<parallel.currentItem> # Item for this instance (collection type)
<parallel.items> # 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: <parallel-name.results> # Array of all instance results
total-count: <parallel-name.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

140
apps/docs/content/docs/yaml/blocks/response.mdx Normal file
View File

@@ -0,0 +1,140 @@
---
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 key-value pairs
items:
type: object
properties:
key:
type: string
description: Header name
value:
type: string
description: Header value
```
## 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: <function.timestamp>
status: 200
```
### Success Response
```yaml
success-response:
type: response
name: "Success Response"
inputs:
data:
success: true
user:
id: <agent.user_id>
name: <agent.user_name>
email: <agent.user_email>
created_at: <function.timestamp>
status: 201
headers:
- key: "Location"
value: "/api/users/<agent.user_id>"
- key: "X-Created-By"
value: "workflow-engine"
```
### Error Response
```yaml
error-response:
type: response
name: "Error Response"
inputs:
data:
error: true
message: <agent.error_message>
code: "VALIDATION_FAILED"
details: <function.validation_errors>
status: 400
headers:
- key: "X-Error-Code"
value: "VALIDATION_FAILED"
```
### Paginated Response
```yaml
paginated-response:
type: response
name: "Paginated Response"
inputs:
data:
data: <agent.results>
pagination:
page: <start.page>
per_page: <start.per_page>
total: <function.total_count>
total_pages: <function.total_pages>
status: 200
headers:
- key: "X-Total-Count"
value: <function.total_count>
- key: "Cache-Control"
value: "public, max-age=300"
- key: "Content-Type"
value: "application/json"
```

200
apps/docs/content/docs/yaml/blocks/router.mdx Normal file
View File

@@ -0,0 +1,200 @@
---
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:
- <string> # Target block ID option 1
- <string> # Target block ID option 2
- <string> # 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: <start.input>
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: <email-analyzer.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: <start.input>
Customer type: <customer-analyzer.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: <start.task>
Complexity indicators: <analyzer.complexity>
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: <routed-block-name.content>
```
## 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

183
apps/docs/content/docs/yaml/blocks/starter.mdx Normal file
View File

@@ -0,0 +1,183 @@
---
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: <string> # 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
```

278
apps/docs/content/docs/yaml/blocks/webhook.mdx Normal file
View File

@@ -0,0 +1,278 @@
---
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
items:
type: object
properties:
key:
type: string
description: Header name
value:
type: string
description: Expected header value
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
items:
type: object
properties:
key:
type: string
description: Header name
value:
type: string
description: Header value
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: <string> # Target block ID for successful processing
error: <string> # 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": "<webhook.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
```
### 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 Studio"
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": "<webhook.method>",
"processed": true,
"timestamp": "{{new Date().toISOString()}}"
}
connections:
success: route-by-method
```
## Webhook Variables
Inside webhook-triggered workflows, these special variables are available:
```yaml
# Available in blocks after the webhook
<webhook.payload> # Full request payload/body
<webhook.headers> # Request headers
<webhook.method> # HTTP method used
<webhook.query> # Query parameters
<webhook.path> # Request path
<webhook.challenge> # 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: <webhook-name.payload> # Request payload
headers: <webhook-name.headers> # Request headers
method: <webhook-name.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

299
apps/docs/content/docs/yaml/blocks/workflow.mdx Normal file
View File

@@ -0,0 +1,299 @@
---
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: <string> # Target block ID for successful completion
error: <string> # 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: <start.input>
userId: <user-validator.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: <start.topic>
style: <style-analyzer.recommendedStyle>
targetAudience: <audience-detector.audience>
brandGuidelines: <brand-config.guidelines>
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: <document-processor.content>
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: <customer-type.type> === "enterprise"
else-if: <customer-type.type> === "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: <customer-data.profile>
accountManager: <account-assignment.manager>
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: <customer-data.profile>
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: <customer-data.profile>
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: <parallel.currentItem.workflowId>
inputMapping:
content: <start.content>
analysisType: <parallel.currentItem.focus>
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: <start.input>
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: <start.input>
errorDetails: <main-workflow.error>
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: <user-processor.profile>
settings: <config-loader.settings>
# Complex object mapping
requestData:
id: <start.requestId>
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: <workflow-name.output> # Sub-workflow output
executionTime: <workflow-name.duration> # Execution duration
status: <workflow-name.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

273
apps/docs/content/docs/yaml/examples.mdx Normal file
View File

@@ -0,0 +1,273 @@
---
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: <start.input>
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:
<agent1initiator.content>
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:
<agent2enhancer.content>
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:
<agent3refiner.content>
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 <start.input> 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: <start.input>
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: <loop.currentItem>
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: <start.input>
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: <emailclassifier.content>
Original email: <start.input>
Generate a professional, helpful response addressing the customer's needs.
model: gpt-4o
temperature: 0.7
apiKey: '{{OPENAI_API_KEY}}'
```

159
apps/docs/content/docs/yaml/index.mdx Normal file
View File

@@ -0,0 +1,159 @@
---
title: YAML Workflow Reference
description: Complete guide to writing YAML workflows in Sim Studio
---
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 Studio. This reference guide covers the complete YAML syntax, block schemas, and best practices for creating robust workflows.
## Quick Start
Every Sim Studio 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
<Steps>
<Step>
<strong>Version Declaration</strong>: Must be exactly `version: '1.0'` (with quotes)
</Step>
<Step>
<strong>Blocks Structure</strong>: All workflow blocks are defined under the `blocks` key
</Step>
<Step>
<strong>Block References</strong>: Use block names in lowercase with spaces removed (e.g., `<aiassistant.content>`)
</Step>
<Step>
<strong>Environment Variables</strong>: Reference with double curly braces `{{VARIABLE_NAME}}`
</Step>
</Steps>
## Block Types
Sim Studio supports several core block types, each with specific YAML schemas:
<Cards>
<Card title="Starter Block" href="/yaml/blocks/starter">
Workflow entry point with support for manual, webhook, and scheduled triggers
</Card>
<Card title="Agent Block" href="/yaml/blocks/agent">
AI-powered processing with support for tools and structured output
</Card>
<Card title="Function Block" href="/yaml/blocks/function">
Custom JavaScript/TypeScript code execution
</Card>
<Card title="API Block" href="/yaml/blocks/api">
HTTP requests to external services
</Card>
<Card title="Condition Block" href="/yaml/blocks/condition">
Conditional branching based on boolean expressions
</Card>
<Card title="Router Block" href="/yaml/blocks/router">
AI-powered intelligent routing to multiple paths
</Card>
<Card title="Loop Block" href="/yaml/blocks/loop">
Iterative processing with for and forEach loops
</Card>
<Card title="Parallel Block" href="/yaml/blocks/parallel">
Concurrent execution across multiple instances
</Card>
<Card title="Webhook Block" href="/yaml/blocks/webhook">
Webhook triggers for external integrations
</Card>
<Card title="Evaluator Block" href="/yaml/blocks/evaluator">
Validate outputs against defined criteria and metrics
</Card>
<Card title="Workflow Block" href="/yaml/blocks/workflow">
Execute other workflows as reusable components
</Card>
<Card title="Response Block" href="/yaml/blocks/response">
Final workflow output formatting
</Card>
</Cards>
## 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 `<start.input>`
### 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: <emailagent.content>
Use this formatted data: <dataagent.output>
Original input: <start.input>
```
### Special Cases
- **Loop Variables**: `<loop.index>`, `<loop.currentItem>`, `<loop.items>`
- **Parallel Variables**: `<parallel.index>`, `<parallel.currentItem>`
## 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

4
apps/docs/content/docs/yaml/meta.json Normal file
View File

@@ -0,0 +1,4 @@
{
"title": "YAML Reference",
"pages": ["index", "block-reference", "blocks", "examples"]
}