|
| 1 | +--- |
| 2 | +title: Block Reference Syntax |
| 3 | +description: How to reference data between blocks in YAML workflows |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 7 | +import { Tab, Tabs } from 'fumadocs-ui/components/tabs' |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +## Basic Reference Rules |
| 12 | + |
| 13 | +### 1. Use Block Names, Not Block IDs |
| 14 | + |
| 15 | +<Tabs items={['Correct', 'Incorrect']}> |
| 16 | + <Tab> |
| 17 | + ```yaml |
| 18 | + # Block definition |
| 19 | + email-sender: |
| 20 | + type: agent |
| 21 | + name: "Email Generator" |
| 22 | + # ... configuration |
| 23 | + |
| 24 | + # Reference the block |
| 25 | + next-block: |
| 26 | + inputs: |
| 27 | + userPrompt: "Process this: <emailgenerator.content>" |
| 28 | + ``` |
| 29 | + </Tab> |
| 30 | + <Tab> |
| 31 | + ```yaml |
| 32 | + # Block definition |
| 33 | + email-sender: |
| 34 | + type: agent |
| 35 | + name: "Email Generator" |
| 36 | + # ... configuration |
| 37 | + |
| 38 | + # ❌ Don't reference by block ID |
| 39 | + next-block: |
| 40 | + inputs: |
| 41 | + userPrompt: "Process this: <email-sender.content>" |
| 42 | + ``` |
| 43 | + </Tab> |
| 44 | +</Tabs> |
| 45 | +
|
| 46 | +### 2. Convert Names to Reference Format |
| 47 | +
|
| 48 | +To create a block reference: |
| 49 | +
|
| 50 | +1. **Take the block name**: "Email Generator" |
| 51 | +2. **Convert to lowercase**: "email generator" |
| 52 | +3. **Remove spaces and special characters**: "emailgenerator" |
| 53 | +4. **Add property**: `<emailgenerator.content>` |
| 54 | + |
| 55 | +### 3. Use Correct Properties |
| 56 | + |
| 57 | +Different block types expose different properties: |
| 58 | + |
| 59 | +- **Agent blocks**: `.content` (the AI response) |
| 60 | +- **Function blocks**: `.output` (the return value) |
| 61 | +- **API blocks**: `.output` (the response data) |
| 62 | +- **Tool blocks**: `.output` (the tool result) |
| 63 | + |
| 64 | +## Reference Examples |
| 65 | + |
| 66 | +### Common Block References |
| 67 | + |
| 68 | +```yaml |
| 69 | +# Agent block outputs |
| 70 | +<agentname.content> # Primary AI response |
| 71 | +<agentname.tokens> # Token usage information |
| 72 | +<agentname.cost> # Estimated cost |
| 73 | +<agentname.tool_calls> # Tool execution details |
| 74 | +
|
| 75 | +# Function block outputs |
| 76 | +<functionname.output> # Function return value |
| 77 | +<functionname.error> # Error information (if any) |
| 78 | +
|
| 79 | +# API block outputs |
| 80 | +<apiname.output> # Response data |
| 81 | +<apiname.status> # HTTP status code |
| 82 | +<apiname.headers> # Response headers |
| 83 | +
|
| 84 | +# Tool block outputs |
| 85 | +<toolname.output> # Tool execution result |
| 86 | +``` |
| 87 | + |
| 88 | +### Multi-Word Block Names |
| 89 | + |
| 90 | +```yaml |
| 91 | +# Block name: "Data Processor 2" |
| 92 | +<dataprocessor2.output> |
| 93 | +
|
| 94 | +# Block name: "Email Validation Service" |
| 95 | +<emailvalidationservice.output> |
| 96 | +
|
| 97 | +# Block name: "Customer Info Agent" |
| 98 | +<customerinfoagent.content> |
| 99 | +``` |
| 100 | + |
| 101 | +## Special Reference Cases |
| 102 | + |
| 103 | +### Starter Block |
| 104 | + |
| 105 | +<Callout type="warning"> |
| 106 | + The starter block is always referenced as `<start.input>` regardless of its actual name. |
| 107 | +</Callout> |
| 108 | + |
| 109 | +```yaml |
| 110 | +# Starter block definition |
| 111 | +my-custom-start: |
| 112 | + type: starter |
| 113 | + name: "Custom Workflow Start" |
| 114 | + # ... configuration |
| 115 | +
|
| 116 | +# Always reference as 'start' |
| 117 | +agent-1: |
| 118 | + inputs: |
| 119 | + userPrompt: <start.input> # ✅ Correct |
| 120 | + # userPrompt: <customworkflowstart.input> # ❌ Wrong |
| 121 | +``` |
| 122 | + |
| 123 | +### Loop Variables |
| 124 | + |
| 125 | +Inside loop blocks, special variables are available: |
| 126 | + |
| 127 | +```yaml |
| 128 | +# Available in loop child blocks |
| 129 | +<loop.index> # Current iteration (0-based) |
| 130 | +<loop.currentItem> # Current item being processed (forEach loops) |
| 131 | +<loop.items> # Full collection (forEach loops) |
| 132 | +``` |
| 133 | + |
| 134 | +### Parallel Variables |
| 135 | + |
| 136 | +Inside parallel blocks, special variables are available: |
| 137 | + |
| 138 | +```yaml |
| 139 | +# Available in parallel child blocks |
| 140 | +<parallel.index> # Instance number (0-based) |
| 141 | +<parallel.currentItem> # Item for this instance |
| 142 | +<parallel.items> # Full collection |
| 143 | +``` |
| 144 | + |
| 145 | +## Complex Reference Examples |
| 146 | + |
| 147 | +### Nested Data Access |
| 148 | + |
| 149 | +When referencing complex objects, use dot notation: |
| 150 | + |
| 151 | +```yaml |
| 152 | +# If an agent returns structured data |
| 153 | +data-analyzer: |
| 154 | + type: agent |
| 155 | + name: "Data Analyzer" |
| 156 | + inputs: |
| 157 | + responseFormat: | |
| 158 | + { |
| 159 | + "schema": { |
| 160 | + "type": "object", |
| 161 | + "properties": { |
| 162 | + "analysis": {"type": "object"}, |
| 163 | + "summary": {"type": "string"}, |
| 164 | + "metrics": {"type": "object"} |
| 165 | + } |
| 166 | + } |
| 167 | + } |
| 168 | +
|
| 169 | +# Reference nested properties |
| 170 | +next-step: |
| 171 | + inputs: |
| 172 | + userPrompt: | |
| 173 | + Summary: <dataanalyzer.analysis.summary> |
| 174 | + Score: <dataanalyzer.metrics.score> |
| 175 | + Full data: <dataanalyzer.content> |
| 176 | +``` |
| 177 | + |
| 178 | +### Multiple References in Text |
| 179 | + |
| 180 | +```yaml |
| 181 | +email-composer: |
| 182 | + type: agent |
| 183 | + inputs: |
| 184 | + userPrompt: | |
| 185 | + Create an email with the following information: |
| 186 | + |
| 187 | + Customer: <customeragent.content> |
| 188 | + Order Details: <orderprocessor.output> |
| 189 | + Support Ticket: <ticketanalyzer.content> |
| 190 | + |
| 191 | + Original request: <start.input> |
| 192 | +``` |
| 193 | + |
| 194 | +### References in Code Blocks |
| 195 | + |
| 196 | +When using references in function blocks, they're replaced as JavaScript values: |
| 197 | + |
| 198 | +```yaml |
| 199 | +data-processor: |
| 200 | + type: function |
| 201 | + inputs: |
| 202 | + code: | |
| 203 | + // References are replaced with actual values |
| 204 | + const customerData = <customeragent.content>; |
| 205 | + const orderInfo = <orderprocessor.output>; |
| 206 | + const originalInput = <start.input>; |
| 207 | + |
| 208 | + // Process the data |
| 209 | + return { |
| 210 | + customer: customerData.name, |
| 211 | + orderId: orderInfo.id, |
| 212 | + processed: true |
| 213 | + }; |
| 214 | +``` |
| 215 | + |
| 216 | +## Reference Validation |
| 217 | + |
| 218 | +Sim Studio validates all references when importing YAML: |
| 219 | + |
| 220 | +### Valid References |
| 221 | +- Block exists in the workflow |
| 222 | +- Property is appropriate for block type |
| 223 | +- No circular dependencies |
| 224 | +- Proper syntax formatting |
| 225 | + |
| 226 | +### Common Errors |
| 227 | +- **Block not found**: Referenced block doesn't exist |
| 228 | +- **Wrong property**: Using `.content` on a function block |
| 229 | +- **Typos**: Misspelled block names or properties |
| 230 | +- **Circular references**: Block references itself directly or indirectly |
| 231 | + |
| 232 | +## Best Practices |
| 233 | + |
| 234 | +1. **Use descriptive block names**: Makes references more readable |
| 235 | +2. **Be consistent**: Use the same naming convention throughout |
| 236 | +3. **Check references**: Ensure all referenced blocks exist |
| 237 | +4. **Avoid deep nesting**: Keep reference chains manageable |
| 238 | +5. **Document complex flows**: Add comments to explain reference relationships |
0 commit comments