Agent 工作流编排实战

在上一节快速入门中，我们创建了一个简单的单轮对话 Agent。但在实际应用中，很多任务需要多个步骤协同完成。OpenClaw 的工作流编排引擎让你可以用 YAML 声明式地定义复杂的多步骤工作流，实现条件分支、并行执行和错误处理等高级功能。本教程将通过构建一个"研究助手"工作流，带你掌握工作流编排的核心技能。

工作流基础概念

在 OpenClaw 中，工作流由以下几个核心概念组成：

• 步骤（Step）：工作流的最小执行单元，每个步骤对应一个 Agent 任务或工具调用
• 条件（Condition）：基于上一步的输出决定下一步的执行路径
• 并行组（Parallel Group）：多个可以同时执行的步骤集合
• 变量（Variable）：在步骤之间传递数据的容器
• 错误处理器（Error Handler）：当步骤执行失败时的回退逻辑

定义你的第一个工作流

让我们从一个简单的三步骤工作流开始：接收用户的研究主题，搜索相关资料，然后生成研究报告。在 OpenClaw 中，工作流定义文件通常放在项目的 workflows/ 目录下。

# workflows/research_agent.yaml
name: "研究助手工作流"
description: "自动搜索相关资料并生成结构化研究报告"
version: "1.0.0"

# 定义工作流的输入参数
input:
  topic:
    type: string
    description: "研究主题"
    required: true
  depth:
    type: string
    default: "standard"
    enum: ["brief", "standard", "deep"]
    description: "研究深度"

# 定义步骤序列
steps:
  - name: "分析研究需求"
    agent: "analyst"
    prompt: |
      请分析以下研究主题，提取关键信息和研究方向：
      主题：{{input.topic}}
      研究深度：{{input.depth}}
      请输出3-5个关键研究方向。
    output: research_plan

  - name: "搜索资料"
    agent: "searcher"
    prompt: |
      根据以下研究计划搜索相关资料：
      {{steps.research_plan.output}}
      请为每个研究方向找到至少2个可靠来源。
    output: search_results

  - name: "生成报告"
    agent: "writer"
    prompt: |
      基于以下搜索结果，撰写一份结构化的研究报告：
      主题：{{input.topic}}
      研究计划：{{steps.research_plan.output}}
      搜索资料：{{steps.search_results.output}}
      报告格式：摘要、背景、主要发现、结论、参考来源。
    output: final_report

# 定义工作流的输出
output:
  report: "{{steps.final_report.output}}"

这个工作流定义展示了 OpenClaw 工作流引擎的核心设计思想：声明式配置。你只需要描述"做什么"，而不需要关心"怎么做"。引擎会自动处理步骤之间的数据传递、Agent 调度和状态管理。

条件分支：智能决策

现实中的业务流程往往需要根据中间结果做出不同的决策。OpenClaw 支持基于表达式的条件分支，让工作流能够智能地选择执行路径。例如，我们可以在研究助手工作流中加入深度判断逻辑：

# 条件分支示例
steps:
  - name: "评估研究深度"
    agent: "evaluator"
    prompt: "评估以下主题的研究复杂度，返回 brief/standard/deep：{{input.topic}}"
    output: complexity

  - name: "简要研究"
    agent: "searcher"
    condition: "{{steps.complexity.output}} == 'brief'"
    prompt: "对 {{input.topic}} 进行简要概述，控制在500字以内。"
    output: research_content

  - name: "标准研究"
    agent: "searcher"
    condition: "{{steps.complexity.output}} == 'standard'"
    prompt: "对 {{input.topic}} 进行标准研究，包含背景、现状和趋势分析。"
    output: research_content

  - name: "深度研究"
    agent: "searcher"
    condition: "{{steps.complexity.output}} == 'deep'"
    prompt: |
      对 {{input.topic}} 进行深度研究，需要包含：
      1. 历史演变 2. 技术细节 3. 行业对比
      4. 数据支撑 5. 专家观点 6. 未来预测
    output: research_content

  - name: "汇总输出"
    agent: "writer"
    prompt: "整理研究内容：{{steps.research_content.output}}"
    output: final_output

条件分支使用 condition 字段来定义，支持常见的比较运算符和逻辑运算符。当条件为真时，对应的步骤才会被执行。如果所有条件都不满足，该步骤会被跳过。你也可以定义一个 default 步骤作为默认分支。

并行执行：提升效率

当多个步骤之间没有依赖关系时，可以使用并行执行来大幅提升工作流的运行效率。在研究助手场景中，我们可以同时搜索多个方向的材料：

# 并行执行示例
steps:
  - name: "并行资料搜索"
    type: parallel
    branches:
      - name: "搜索学术论文"
        agent: "academic_searcher"
        prompt: "搜索与 {{input.topic}} 相关的学术论文和研究成果"
        output: academic_results

      - name: "搜索行业报告"
        agent: "industry_searcher"
        prompt: "搜索与 {{input.topic}} 相关的行业报告和市场分析"
        output: industry_results

      - name: "搜索新闻动态"
        agent: "news_searcher"
        prompt: "搜索与 {{input.topic}} 相关的最新新闻和动态"
        output: news_results

    # 并行步骤的超时设置
    timeout: 120
    # 失败策略：all（全部成功）或 any（任一成功）
    completion: "any"

  - name: "综合整理"
    agent: "synthesizer"
    prompt: |
      请综合以下三个来源的信息，生成一份全面的研究报告：
      学术论文：{{steps.并行资料搜索.academic_results}}
      行业报告：{{steps.并行资料搜索.industry_results}}
      新闻动态：{{steps.并行资料搜索.news_results}}
    output: final_report

并行执行使用 type: parallel 来声明，内部的 branches 定义了多个可以同时执行的分支。completion 字段控制并行步骤何时算作完成：all 表示所有分支都必须成功，any 表示只要有一个分支成功即可。timeout 设置了整个并行组的最长等待时间。

错误处理：构建健壮的工作流

在生产环境中，错误处理是工作流设计的关键环节。网络超时、API 限流、模型输出异常等情况都可能发生。OpenClaw 提供了多层次的错误处理机制：

• 步骤级重试：自动重试失败的步骤，支持配置重试次数和间隔
• 回退步骤（Fallback）：当步骤彻底失败时，执行预定义的替代逻辑
• 全局错误处理器：捕获工作流中未被处理的异常，执行清理操作

# 错误处理示例
steps:
  - name: "调用外部API"
    agent: "api_caller"
    prompt: "调用研究数据库API查询：{{input.topic}}"
    output: api_result

    # 步骤级重试配置
    retry:
      max_attempts: 3
      delay: 5        # 重试间隔（秒）
      backoff: 2      # 退避倍数

    # 回退步骤
    fallback:
      agent: "local_searcher"
      prompt: "使用本地知识库搜索：{{input.topic}}"
      output: api_result

# 全局错误处理器
on_error:
  - name: "记录错误日志"
    agent: "logger"
    prompt: |
      工作流执行出错：
      错误步骤：{{error.step_name}}
      错误信息：{{error.message}}
      执行时间：{{error.timestamp}}

  - name: "发送告警通知"
    agent: "notifier"
    prompt: "向管理员发送工作流执行失败的告警通知"

实战：构建完整的研究助手工作流

现在，让我们将上面学到的所有概念整合起来，构建一个完整的研究助手工作流。这个工作流将包含条件分支、并行执行和错误处理，是一个可以直接用于生产环境的示例。

完整的工作流执行流程如下：首先分析用户的研究主题和深度需求，然后根据深度级别选择不同的搜索策略，接着并行搜索多个信息来源，之后综合所有资料生成研究报告，最后进行质量检查。如果质量不达标，会自动触发补充搜索。整个流程中，每个关键步骤都有重试和回退机制。

运行工作流非常简单，只需要一条命令：

# 运行研究助手工作流
openclaw workflow run research_agent \
  --input topic="大语言模型在教育领域的应用" \
  --input depth="deep"

# 查看工作流执行状态
openclaw workflow status research_agent --latest

# 查看执行日志
openclaw workflow logs research_agent --step "综合整理"

小结

工作流编排是 OpenClaw 最强大的功能之一。通过 YAML 声明式配置，你可以轻松构建包含条件分支、并行执行和错误处理的复杂 Agent 工作流。掌握工作流编排，意味着你可以将 AI Agent 从简单的问答工具升级为能够处理真实业务场景的智能自动化系统。在下一节教程中，我们将学习如何让 Agent 调用外部工具，进一步扩展 Agent 的能力边界。