Loop Block YAML 架构

架构定义

type: object
required:
  - type
  - name
  - connections
properties:
  type:
    type: string
    enum: [loop]
    description: Block type identifier
  name:
    type: string
    description: Display name for this loop block
  inputs:
    type: object
    description: Optional. If omitted, defaults will be applied.
    properties:
      loopType:
        type: string
        enum: [for, forEach]
        description: Type of loop to execute
        default: for
      iterations:
        type: number
        description: Number of iterations (for 'for' loops)
        default: 5
        minimum: 1
        maximum: 1000
      collection:
        type: string
        description: Collection to iterate over (for 'forEach' loops)
        default: ""
      maxConcurrency:
        type: number
        description: Maximum concurrent executions
        default: 1
        minimum: 1
        maximum: 10
  connections:
    type: object
    properties:
      # Nested format (recommended)
      loop:
        type: object
        properties:
          start:
            type: string
            description: Target block ID to execute inside the loop
          end:
            type: string
            description: Target block ID for loop completion (optional)
      # Direct handle format (alternative)
      loop-start-source:
        type: string | string[]
        description: Target block ID to execute inside the loop (direct format)
      loop-end-source:
        type: string | string[]
        description: Target block ID for loop completion (direct format, optional)
      error:
        type: string
        description: Target block ID for error handling
    note: Use either the nested 'loop' format OR the direct 'loop-start-source' format, not both

连接配置

循环块支持两种连接格式：

直接句柄格式（替代方案）

connections:
  loop-start-source: <string>           # Target block ID to execute inside the loop
  loop-end-source: <string>             # Target block ID after loop completion (optional)
  error: <string>                       # Target block ID for error handling (optional)

两种格式的功能完全相同，可根据您的喜好选择使用。

子块配置

循环中的块必须将其 parentId 设置为循环块的 ID。extent 属性会自动设置为 'parent'，无需手动指定：

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

示例

For 循环（固定迭代次数）

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 循环（集合处理）

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

包含多个子块的循环

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

并发处理循环

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

直接句柄格式示例

同一个循环可以使用直接句柄格式编写：

my-loop:
  type: loop
  name: "Process Items"
  inputs:
    loopType: forEach
    collection: <start.items>
  connections:
    loop-start-source: process-item      # Direct handle format
    loop-end-source: final-results       # Direct handle format
    error: handle-error

process-item:
  type: agent
  name: "Process Item"
  parentId: my-loop
  inputs:
    systemPrompt: "Process this item"
    userPrompt: <loop.currentItem>
    model: gpt-4o
    apiKey: '{{OPENAI_API_KEY}}'

最小循环示例（使用默认值）

您可以完全省略 inputs 部分，系统将应用默认值：

simple-loop:
  type: loop
  name: "Simple Loop"
  # No inputs section - defaults to loopType: 'for', iterations: 5
  connections:
    loop-start-source: process-step
    loop-end-source: complete

process-step:
  type: agent
  name: "Process Step"
  parentId: simple-loop
  inputs:
    systemPrompt: "Execute step"
    userPrompt: "Step <loop.index>"
    model: gpt-4o
    apiKey: '{{OPENAI_API_KEY}}'

此循环默认将执行 5 次迭代。

循环变量

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

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

输出引用

循环完成后，您可以引用其聚合结果：

# 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

最佳实践

设置合理的迭代限制以避免长时间执行
使用 forEach 处理集合，使用 for 循环进行固定迭代
考虑对 I/O 密集型操作使用 maxConcurrency
包含错误处理以确保循环执行的健壮性
为循环子块使用描述性名称
先用小集合进行测试
对于大集合，监控执行时间

Loop Block YAML 架构

On this page