Ao Workflow Runner

Multi-Role Workflow Runner

When the user asks to run a workflow (YAML file) or a multi-role collaboration task, follow these steps:

1. Parse Workflow

Read the specified YAML file. Extract name, inputs, steps, depends_on, conditions, and loops.

2. Collect Inputs

• required: true inputs must be provided by the user
• Optional inputs with default use the default value
• Optional inputs without default are set to empty string

3. Build Execution Order

Topological sort by depends_on. Steps without dependencies belong to the same level and can run in parallel.

4. Execute Steps

For each step: 1. Read agency-agents-zh/{role}.md (search order: YAML's agents_dir → ./agency-agents-zh/ → ../agency-agents-zh/ → node_modules/agency-agents-zh/) 2. Extract all markdown content after the frontmatter (---) as the role personality 3. Replace {{variables}} in the task with context values (from inputs or previous step outputs) 4. Evaluate conditions: if condition is set, evaluate it. Skip the step if the condition is not met. Operators: contains, equals, not_contains, not_equals 5. Fully embody the role — use that role's expertise, frameworks, and communication style. Output should be substantive. 6. Store the step's output text into the context variable (if step has an output field) 7. Check loops: if loop is set and exit_condition is not met, jump back to loop.back_to step (max: loop.max_iterations rounds)

Label each step: ### Step N/Total: step_id (Role Name)

5. Save Results

Save all outputs to files:

ao-output/{workflow-name}-{date}/
├── steps/
│   ├── 1-{step_id}.md
│   └── ...
├── summary.md          # Final step's full output
└── metadata.json       # Step states, timing, token counts

6. Suggest Iteration

After completion, always tell the user:

To improve a specific step, ask me to re-run from that step. I'll reuse all upstream outputs.

For CLI: ao run <workflow> --resume last --from <step-id>

Important Rules

• Each step must genuinely embody the assigned role — no generic responses
• Never skip or merge steps; execute strictly in topological order
• If a role file is missing, tell the user to install agency-agents-zh
• If a condition is not met, mark the step as "skipped" and continue
• For depends_on_mode: "any_completed", proceed when ANY upstream step completes (not all)

DeerFlow 2.0 集成

在 DeerFlow（字节跳动开源 SuperAgent）中直接运行多角色工作流。

🌐 English users: npm install -g agency-orchestrator — both 211 Chinese and 170+ English roles are bundled. Use ao compose "your idea" --run from CLI, or follow this guide for IDE-specific setup (translations coming in v0.6).

安装

# 1. 下载 211 个 AI 角色
cd your-project
git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git

# 2. 下载工作流模板和技能文件
git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
cp -r .ao-tmp/workflows ./workflows
mkdir -p skills/custom/ao-workflow-runner
cp .ao-tmp/integrations/deerflow/SKILL.md skills/custom/ao-workflow-runner/SKILL.md
rm -rf .ao-tmp

# 3. 开始使用
# 在 DeerFlow 中直接说：运行 workflows/story-creation.yaml

使用方式

方式一：Skill 模式（推荐）

DeerFlow 会自动发现 skills/custom/ao-workflow-runner/SKILL.md 中的技能。在会话中直接说：

运行 workflows/story-creation.yaml
创意：一个程序员在凌晨发现AI回复不该知道的事

DeerFlow 会通过 ao-workflow-runner 技能：

• 解析 YAML 工作流
• 加载每个角色的 .md 定义
• 按 DAG 顺序逐步执行
• 保存结果到 ao-output/

方式二：自然语言模式

不需要 YAML 文件，直接描述协作需求：

用产品经理分析需求，然后让架构师评估技术方案、设计师评估用户体验，最后产品经理汇总。
PRD 内容：[你的 PRD]

方式三：CLI 模式

npm install -g agency-orchestrator
export DEEPSEEK_API_KEY=sk-xxx
ao run workflows/product-review.yaml -i prd_content=@prd.md

可用工作流

自定义工作流

参见 工作流格式文档。