# AOL (Agent Orchestration Language) 使用示例

## 基础示例

### 1. 简单顺序工作流

```toml
[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. 并行执行工作流

```toml
[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. 条件分支工作流

```toml
[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. 循环处理工作流

```toml
[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. 错误处理与回退

```toml
[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. 完整配置示例

```toml
[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 使用

### 编译工作流

```bash
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\""
  }'
```

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

### 执行工作流

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

响应:
```json
{
  "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
}
```

### 查询执行状态

```bash
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}}` | 循环当前索引 |