Block Reference Syntax

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

# Block definition
email-sender:
  type: agent
  name: "Email Generator"
  # ... configuration

# Reference the block
next-block:
  inputs:
    userPrompt: "Process this: <emailgenerator.content>"

# 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>"

2. Convert Names to Reference Format

To create a block reference:

Take the block name: "Email Generator"
Convert to lowercase: "email generator"
Remove spaces and special characters: "emailgenerator"
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

# 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

# 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

The starter block is always referenced as <start.input> regardless of its actual name.

# 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:

# 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:

# 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:

# 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

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:

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

Use descriptive block names: Makes references more readable
Be consistent: Use the same naming convention throughout
Check references: Ensure all referenced blocks exist
Avoid deep nesting: Keep reference chains manageable
Document complex flows: Add comments to explain reference relationships

Block Reference Syntax

On this page