openfang/docs/aol-examples.md

AOL (Agent Orchestration Language) 使用示例

基础示例

1. 简单顺序工作流

[workflow]
name = "simple-pipeline"
version = "1.0.0"
description = "简单的研究流程"

[workflow.input]
topic = { type = "string", required = true, description = "研究主题" }

[[workflow.steps.sequential]]
id = "research"
agent = { kind = "by_name", name = "researcher" }
task = "搜索关于 {{input.topic}} 的最新信息"
output = "research_result"

[[workflow.steps.sequential]]
id = "summarize"
agent = { kind = "by_name", name = "writer" }
task = "总结以下研究结果: {{research_result}}"
output = "summary"

2. 并行执行工作流

[workflow]
name = "parallel-research"
version = "1.0.0"

[workflow.input]
topic = { type = "string", required = true }

[[workflow.steps.parallel]]
id = "parallel-search"
collect = "merge"
output = "all_results"
max_concurrency = 3

[[workflow.steps.parallel.steps]]
id = "academic"
agent = { kind = "by_name", name = "academic-researcher" }
task = "搜索 {{input.topic}} 的学术论文"
output = "papers"

[[workflow.steps.parallel.steps]]
id = "news"
agent = { kind = "by_name", name = "news-researcher" }
task = "搜索 {{input.topic}} 的新闻报道"
output = "news"

[[workflow.steps.parallel.steps]]
id = "market"
agent = { kind = "by_role", role = "analyst" }
task = "分析 {{input.topic}} 的市场趋势"
output = "market_data"

[[workflow.steps.collect]]
id = "combine"
sources = ["papers", "news", "market_data"]
strategy = "merge"
output = "combined_research"

[[workflow.steps.sequential]]
id = "synthesize"
agent = { kind = "by_name", name = "writer" }
task = "综合以下研究结果生成报告: {{combined_research}}"
output = "final_report"

3. 条件分支工作流

[workflow]
name = "conditional-workflow"
version = "1.0.0"

[workflow.input]
complexity = { type = "string", required = true, enum_values = ["quick", "standard", "exhaustive"] }
topic = { type = "string", required = true }

[[workflow.steps.sequential]]
id = "initial-research"
agent = { kind = "by_name", name = "researcher" }
task = "初步研究: {{input.topic}}"
output = "initial_result"

[[workflow.steps.conditional]]
id = "depth-check"

[[workflow.steps.conditional.branches]]
id = "exhaustive-branch"
condition = "{{input.complexity}} == exhaustive"

[[workflow.steps.conditional.branches.steps.sequential]]
id = "deep-research"
agent = { kind = "by_name", name = "expert-researcher" }
task = "深入研究: {{initial_result}}"
output = "deep_result"

[[workflow.steps.conditional.branches.steps.sequential]]
id = "peer-review"
agent = { kind = "by_role", role = "reviewer" }
task = "同行评审: {{deep_result}}"
output = "reviewed_result"

[[workflow.steps.conditional.branches]]
id = "quick-branch"
condition = "{{input.complexity}} == quick"

[[workflow.steps.conditional.branches.steps.sequential]]
id = "quick-summary"
agent = { kind = "by_name", name = "writer" }
task = "快速总结: {{initial_result}}"
output = "quick_summary"

[[workflow.steps.conditional.default]]

[[workflow.steps.conditional.default.sequential]]
id = "standard-summary"
agent = { kind = "by_name", name = "writer" }
task = "标准总结: {{initial_result}}"
output = "standard_summary"

4. 循环处理工作流

[workflow]
name = "batch-processor"
version = "1.0.0"

[workflow.input]
items = { type = "array", required = true, description = "要处理的项目列表" }

[[workflow.steps.loop]]
id = "process-items"
item_var = "item"
index_var = "idx"
collection = "{{input.items}}"
collect = "merge"
output = "processed_items"

[[workflow.steps.loop.steps.sequential]]
id = "process-single"
agent = { kind = "by_name", name = "processor" }
task = "处理第 {{loop.idx}} 个项目: {{loop.item}}"
output = "item_result"

5. 错误处理与回退

[workflow]
name = "robust-workflow"
version = "1.0.0"

[workflow.input]
query = { type = "string", required = true }

[workflow.config]
default_error_mode = "retry"
max_retries = 3

[[workflow.steps.fallback]]
id = "search-with-fallback"
output = "search_result"

[workflow.steps.fallback.primary.sequential]
id = "primary-search"
agent = { kind = "by_name", name = "primary-searcher" }
task = "搜索: {{input.query}}"
error_mode = "skip"
timeout_secs = 30

[[workflow.steps.fallback.fallbacks.sequential]]
id = "fallback-search"
agent = { kind = "by_name", name = "backup-searcher" }
task = "备用搜索: {{input.query}}"

[[workflow.steps.fallback.fallbacks.sequential]]
id = "cached-search"
agent = { kind = "by_name", name = "cache-agent" }
task = "从缓存查找: {{input.query}}"

6. 完整配置示例

[workflow]
name = "enterprise-research-pipeline"
version = "2.0.0"
description = "企业级研究流水线"
author = "OpenFang Team"
tags = ["research", "analysis", "enterprise"]

[workflow.input]
topic = { type = "string", required = true, description = "研究主题" }
depth = { type = "string", required = false, default = "standard", enum_values = ["quick", "standard", "exhaustive"] }
max_sources = { type = "integer", required = false, default = 10 }

[workflow.config]
timeout_secs = 1800        # 30分钟总超时
max_retries = 3            # 最大重试次数
default_error_mode = "fail"
max_concurrency = 5        # 最大并行数
persist_state = true       # 持久化状态以支持恢复

# ... 步骤定义 ...

API 使用

编译工作流

curl -X POST http://localhost:4200/api/aol/compile \
  -H "Content-Type: application/json" \
  -d '{
    "toml": "[workflow]\nname = \"test\"\nversion = \"1.0.0\"\n\n[[workflow.steps.sequential]]\nid = \"step1\"\nagent = { kind = \"by_name\", name = \"assistant\" }\ntask = \"Hello\""
  }'

响应:

{
  "id": "uuid",
  "name": "test",
  "version": "1.0.0",
  "step_count": 1,
  "inputs": [],
  "outputs": [],
  "validation_errors": []
}

执行工作流

curl -X POST http://localhost:4200/api/aol/execute \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "uuid",
    "inputs": {
      "topic": "人工智能"
    }
  }'

响应:

{
  "execution_id": "exec-uuid",
  "workflow_id": "uuid",
  "status": "Completed",
  "step_results": [
    {
      "step_id": "step1",
      "success": true,
      "output": "处理结果...",
      "error": null,
      "duration_ms": 1234,
      "retries": 0
    }
  ],
  "outputs": {
    "result": "最终输出..."
  },
  "error": null,
  "duration_ms": 1500
}

查询执行状态

curl http://localhost:4200/api/aol/executions/exec-uuid

Agent 引用方式

类型	语法	说明
按ID	{ kind = "by_id", id = "uuid" }	精确引用特定 Agent
按名称	{ kind = "by_name", name = "assistant" }	按名称查找 Agent
按角色	{ kind = "by_role", role = "researcher" }	按角色匹配 Agent
带能力	{ kind = "by_role", role = "worker", capability = "web_search" }	按角色+能力匹配

收集策略

策略	说明
merge	合并所有结果为数组 (默认)
first	只取第一个完成的结果
last	只取最后一个完成的结果
aggregate	聚合结果 (字符串连接/数值求和)

错误处理模式

模式	说明
fail	失败时终止工作流 (默认)
skip	失败时跳过此步骤
retry	失败时重试 (最多 max_retries 次)

模板变量

变量	说明
{{input.xxx}}	输入参数
{{output.step_name}}	步骤输出
{{loop.item}}	循环当前项
{{loop.idx}}	循环当前索引