块引用语法

块引用是 Sim 工作流中数据流的基础。了解如何正确地将一个块的输出作为另一个块的输入进行引用，对于构建功能性工作流至关重要。

基本引用规则

1. 使用块名称，而非块 ID

# 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. 将名称转换为引用格式

创建块引用的方法：

获取块名称："Email Generator"
转换为小写："email generator"
移除空格和特殊字符："emailgenerator"
添加属性：<emailgenerator.content>

3. 使用正确的属性

不同的块类型会暴露不同的属性：

Agent 块：.content（AI 响应）
Function 块：.output（返回值）
API 块：.output（响应数据）
Tool 块：.output（工具结果）

引用示例

常见块引用

# 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

多词块名称

# Block name: "Data Processor 2"
<dataprocessor2.output>

# Block name: "Email Validation Service"  
<emailvalidationservice.output>

# Block name: "Customer Info Agent"
<customerinfoagent.content>

特殊引用情况

起始块

起始块始终被引用为 <start.input>，无论其实际名称为何。

# 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

循环变量

在循环块中，可以使用特殊变量：

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

并行变量

在并行块中，可以使用特殊变量：

# Available in parallel child blocks
<parallel.index>          # Instance number (0-based)
<parallel.currentItem>    # Item for this instance
<parallel.items>          # Full collection

复杂引用示例

嵌套数据访问

引用复杂对象时，请使用点符号：

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

文本中的多个引用

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>

代码块中的引用

在函数块中使用引用时，它们会被替换为 JavaScript 值：

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
      };

引用验证

Sim 在导入 YAML 时会验证所有引用：

有效引用

工作流中存在块
属性适合块类型
无循环依赖
语法格式正确

常见错误

未找到块：引用的块不存在
错误的属性：在函数块中使用 .content
拼写错误：块名称或属性拼写错误
循环引用：块直接或间接引用自身

最佳实践

使用描述性块名称：使引用更易读
保持一致性：在整个过程中使用相同的命名约定
检查引用：确保所有引用的块都存在
避免深度嵌套：保持引用链可管理
记录复杂流程：添加注释以解释引用关系

块引用语法

On this page