Back to Details

workflow-orchestrator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Workflow Orchestrator Skill

Workflow Orchestrator Skill

Execute declarative workflow files that orchestrate multiple PopeBot agent jobs. This skill brings OpenProse-style workflow orchestration to PopeBot's job-based architecture.
执行用于编排多个PopeBot Agent任务的声明式工作流文件。该Skill将OpenProse风格的工作流编排引入PopeBot的基于任务的架构中。

When to Activate

激活场景

Activate this skill when the user:
  • Wants to run multiple agent jobs in sequence or parallel
  • Needs to coordinate tasks with dependencies
  • Wants to create reusable automation pipelines
  • Asks to run a 
    .workflow
    file
  • Mentions "workflow orchestration" or "multi-agent workflow"
当用户有以下需求时激活该Skill：
  • 希望按顺序或并行运行多个Agent任务
  • 需要协调存在依赖关系的任务
  • 想要创建可复用的自动化流水线
  • 请求运行
    .workflow
    文件
  • 提到“工作流编排”或“多Agent工作流”

Workflow File Format

工作流文件格式

Workflows use YAML-like syntax with clear structure:
yaml
undefined
工作流采用类YAML的语法，结构清晰：
yaml
undefined

Example: Code review workflow

Example: Code review workflow

name: "PR Review Pipeline" description: "Review PR, check for bugs, suggest improvements"
inputs:
  • name: pr_number required: true description: "Pull request number to review"
agents: reviewer: personality: | You are a thorough code reviewer focused on security, best practices, and maintainability. tester: personality: | You are a QA engineer focused on edge cases and test coverage. documenter: personality: | You are a technical writer who creates clear documentation.
steps:

Sequential steps run one after another

  • name: review_code agent: reviewer prompt: | Review pull request #{{pr_number}} for:
    • Security issues
    • Code quality
    • Best practices output: review_report

Parallel steps run concurrently

  • name: parallel_tests parallel:
    • name: unit_tests agent: tester prompt: "Check test coverage for PR #{{pr_number}}" output: test_report
    • name: integration_tests agent: tester prompt: "Check integration tests for PR #{{pr_number}}" output: integration_report

Conditional execution

  • name: write_summary agent: documenter prompt: | Write a PR summary based on:
    • Review: {{review_report}}
    • Tests: {{test_report}}
    • Integration: {{integration_report}} if: "all previous steps succeeded" output: final_summary
outputs:
  • review_report
  • test_report
  • integration_report
  • final_summary
undefined
name: "PR Review Pipeline" description: "Review PR, check for bugs, suggest improvements"
inputs:
  • name: pr_number required: true description: "Pull request number to review"
agents: reviewer: personality: | You are a thorough code reviewer focused on security, best practices, and maintainability. tester: personality: | You are a QA engineer focused on edge cases and test coverage. documenter: personality: | You are a technical writer who creates clear documentation.
steps:

Sequential steps run one after another

  • name: review_code agent: reviewer prompt: | Review pull request #{{pr_number}} for:
    • Security issues
    • Code quality
    • Best practices output: review_report

Parallel steps run concurrently

  • name: parallel_tests parallel:
    • name: unit_tests agent: tester prompt: "Check test coverage for PR #{{pr_number}}" output: test_report
    • name: integration_tests agent: tester prompt: "Check integration tests for PR #{{pr_number}}" output: integration_report

Conditional execution

  • name: write_summary agent: documenter prompt: | Write a PR summary based on:
    • Review: {{review_report}}
    • Tests: {{test_report}}
    • Integration: {{integration_report}} if: "all previous steps succeeded" output: final_summary
outputs:
  • review_report
  • test_report
  • integration_report
  • final_summary
undefined

Commands

命令

Run a Workflow

运行工作流

bash
undefined
bash
undefined

Run a local workflow file

Run a local workflow file

workflow run my-workflow.workflow
workflow run my-workflow.workflow

Run with inputs

Run with inputs

workflow run my-workflow.workflow --input pr_number=123
workflow run my-workflow.workflow --input pr_number=123

Run a remote workflow

Run a remote workflow

workflow run https://example.com/workflow.workflow
undefined
workflow run https://example.com/workflow.workflow
undefined

Compile/Validate

编译/验证

bash
undefined
bash
undefined

Validate workflow syntax without running

Validate workflow syntax without running

workflow compile my-workflow.workflow
undefined
workflow compile my-workflow.workflow
undefined

List Available Workflows

列出可用工作流

bash
undefined
bash
undefined

Show workflows in current directory

Show workflows in current directory

workflow list
undefined
workflow list
undefined

Execution Model

执行模型

The workflow orchestrator:
  1. Parses the workflow file
  2. Validates syntax and required inputs
  3. Creates agent definitions with custom personalities
  4. Executes steps according to dependencies:
    • Sequential steps wait for previous completion
    • Parallel steps spawn multiple jobs concurrently
    • Conditional steps evaluate AI-determined conditions
  5. Collects outputs from each step
  6. Reports final results
工作流编排器的执行流程：
  1. 解析工作流文件
  2. 验证语法和必填输入项
  3. 创建带有自定义个性的Agent定义
  4. 执行步骤（遵循依赖关系）：
    • 顺序步骤需等待前序步骤完成后再执行
    • 并行步骤会同时启动多个任务
    • 条件步骤会评估AI判定的条件
  5. 收集每个步骤的输出
  6. 汇报最终结果

Job Management

任务管理

Each workflow step creates a PopeBot job:
  • Jobs are created in 
    job/workflow-{workflow_id}-{step_name}
    branches
  • Job results are stored in 
    /job/tmp/workflows/{workflow_id}/{step_name}/
  • Failed steps can be retried individually
  • Workflows can be paused for approval gates
每个工作流步骤都会创建一个PopeBot任务：
  • 任务会在
    job/workflow-{workflow_id}-{step_name}
    分支中创建
  • 任务结果存储在
    /job/tmp/workflows/{workflow_id}/{step_name}/
    目录下
  • 失败的步骤可单独重试
  • 工作流可暂停以等待审批环节

Approval Gates

审批环节

Insert approval checkpoints in workflows:
yaml
steps:
  - name: draft_email
    agent: assistant
    prompt: "Draft a response to the customer complaint"
    output: email_draft

  - name: approval_gate
    type: approval
    prompt: "Send this email?"
    data: "{{email_draft}}"
    on_approve:
      - name: send_email
        agent: assistant
        prompt: "Send the approved email"
    on_reject:
      - name: revise_email
        agent: assistant
        prompt: "Revise the email based on feedback"
可在工作流中插入审批检查点：
yaml
steps:
  - name: draft_email
    agent: assistant
    prompt: "Draft a response to the customer complaint"
    output: email_draft

  - name: approval_gate
    type: approval
    prompt: "Send this email?"
    data: "{{email_draft}}"
    on_approve:
      - name: send_email
        agent: assistant
        prompt: "Send the approved email"
    on_reject:
      - name: revise_email
        agent: assistant
        prompt: "Revise the email based on feedback"

Error Handling

错误处理

yaml
steps:
  - name: risky_operation
    agent: assistant
    prompt: "Do something that might fail"
    retry:
      max_attempts: 3
      backoff: exponential
    on_error:
      - name: handle_error
        agent: assistant
        prompt: "Handle this error: {{error_message}}"
yaml
steps:
  - name: risky_operation
    agent: assistant
    prompt: "Do something that might fail"
    retry:
      max_attempts: 3
      backoff: exponential
    on_error:
      - name: handle_error
        agent: assistant
        prompt: "Handle this error: {{error_message}}"

Variable Substitution

变量替换

Use 
{{variable_name}}
to reference:
  • Workflow inputs: 
    {{pr_number}}
  • Step outputs: 
    {{review_report}}
  • Previous step data in parallel blocks
使用
{{variable_name}}
引用以下内容：
  • 工作流输入项：
    {{pr_number}}
  • 步骤输出：
    {{review_report}}
  • 并行块中前序步骤的数据

Configuration

配置

yaml
undefined
yaml
undefined

In config/WORKFLOWS.json (optional)

In config/WORKFLOWS.json (optional)

{ "default_timeout": 600, "max_parallel_jobs": 5, "workspace": "/job/tmp/workflows", "notification_channel": "telegram" }
undefined
{ "default_timeout": 600, "max_parallel_jobs": 5, "workspace": "/job/tmp/workflows", "notification_channel": "telegram" }
undefined

Examples

示例

Multi-Agent Research

多Agent研究

yaml
name: "Research Deep Dive"
inputs:
  - name: topic
    required: true

steps:
  - name: initial_research
    parallel:
      - agent: researcher
        prompt: "Research {{topic}} from technical perspective"
        output: tech_research
      - agent: researcher
        prompt: "Research {{topic}} market applications"
        output: market_research
  
  - name: synthesize
    agent: analyst
    prompt: |
      Synthesize findings:
      Technical: {{tech_research}}
      Market: {{market_research}}
    output: final_report
yaml
name: "Research Deep Dive"
inputs:
  - name: topic
    required: true

steps:
  - name: initial_research
    parallel:
      - agent: researcher
        prompt: "Research {{topic}} from technical perspective"
        output: tech_research
      - agent: researcher
        prompt: "Research {{topic}} market applications"
        output: market_research
  
  - name: synthesize
    agent: analyst
    prompt: |
      Synthesize findings:
      Technical: {{tech_research}}
      Market: {{market_research}}
    output: final_report

CI/CD Pipeline

CI/CD流水线

yaml
name: "Release Pipeline"
inputs:
  - name: version
    required: true

steps:
  - name: build
    agent: builder
    prompt: "Build version {{version}} and run tests"
  
  - name: security_scan
    agent: security
    prompt: "Scan {{version}} for vulnerabilities"
    parallel: true
  
  - name: approval
    type: approval
    prompt: "Deploy version {{version}}?"
  
  - name: deploy
    agent: deployer
    prompt: "Deploy {{version}} to production"
    if: "**approval granted**"
yaml
name: "Release Pipeline"
inputs:
  - name: version
    required: true

steps:
  - name: build
    agent: builder
    prompt: "Build version {{version}} and run tests"
  
  - name: security_scan
    agent: security
    prompt: "Scan {{version}} for vulnerabilities"
    parallel: true
  
  - name: approval
    type: approval
    prompt: "Deploy version {{version}}?"
  
  - name: deploy
    agent: deployer
    prompt: "Deploy {{version}} to production"
    if: "**approval granted**"

State Management

状态管理

Workflow state persists in:
  • /job/tmp/workflows/{workflow_id}/state.json
    - Current execution state
  • /job/tmp/workflows/{workflow_id}/steps/
    - Individual step results
  • /job/tmp/workflows/{workflow_id}/logs/
    - Execution logs
工作流状态持久存储在以下位置：
  • /job/tmp/workflows/{workflow_id}/state.json
    - 当前执行状态
  • /job/tmp/workflows/{workflow_id}/steps/
    - 各步骤的单独结果
  • /job/tmp/workflows/{workflow_id}/logs/
    - 执行日志

API Integration

API集成

Workflows can be triggered via:
bash
undefined
可通过以下方式触发工作流：
bash
undefined

Via PopeBot chat

Via PopeBot chat

/workflow run my-workflow.workflow
/workflow run my-workflow.workflow

Via API

Via API

curl -X POST /api/create-job
-H "x-api-key: YOUR_KEY"
-d '{"job": "workflow run my-workflow.workflow --input key=value"}'
undefined
curl -X POST /api/create-job
-H "x-api-key: YOUR_KEY"
-d '{"job": "workflow run my-workflow.workflow --input key=value"}'
undefined

When NOT to Use

不适用场景

  • Single simple tasks (use direct agent jobs)
  • Tasks requiring continuous human interaction
  • Real-time data processing
  • Tasks under 30 seconds (overhead not justified)
  • 单个简单任务（直接使用Agent任务即可）
  • 需要持续人机交互的任务
  • 实时数据处理任务
  • 耗时不足30秒的任务（编排开销得不偿失）

File Locations

文件位置

FileLocationPurpose
Skill filesSame dir as this SKILL.mdDocumentation and executor
User workflowsWorkspace 
*.workflow
files		User-created workflows
State
/job/tmp/workflows/
Runtime state and results
Config
config/WORKFLOWS.json
(optional)		Global settings
文件位置用途
Skill文件与本SKILL.md同目录文档和执行器
用户工作流工作区中的
*.workflow
文件		用户创建的工作流
状态文件
/job/tmp/workflows/
运行时状态和结果
配置文件
config/WORKFLOWS.json
（可选）		全局设置