# Agent 双模式设计思路

> 创建时间：2025-01-XX
> 
> 核心理念：Agent 不是"要么自由，要么固定"，而是同一身份下可兼顾两种场景。

---

## 一、核心洞察

```
Agent 不是"要么自由，要么固定"

而是：

Agent 有"身份"（比如财务 Agent）
       ↓
   这个身份下有两种场景：
       ↓
   ├─ 固定流程：报销审批 → 按图执行
   └─ 灵活咨询：财务问题 → 自由发挥
```

---

## 二、真实场景举例

### 财务 Agent

```
场景1：员工报销（固定流程）
员工：我要报销 500 块打车费
Agent：好的，走报销流程
      → 步骤1：收集发票
      → 步骤2：检查金额
      → 步骤3：提交审批
      → 步骤4：通知结果
      （按部就班，不会乱）

场景2：财务咨询（自由对话）
员工：公司的差旅标准是多少？
Agent：（自由回答）根据公司规定...
员工：那招待客户有啥限制？
Agent：（自由回答）招待费用需要...
      （灵活应对，随机应变）
```

### HR Agent

```
固定流程：
- 请假审批 → 固定步骤
- 入职办理 → 固定步骤
- 离职流程 → 固定步骤

自由对话：
- 咨询社保问题
- 咨询公积金政策
- 咨询公司福利
```

### 法务 Agent

```
固定流程：
- 合同初审 → 固定步骤
- 合同归档 → 固定步骤

自由对话：
- 法律咨询
- 风险解答
```

---

## 三、设计思路

### 3.1 层级结构

```
Agent（身份）
    │
    ├── 技能1：报销处理
    │       └── 模式：safe（固定流程）
    │           收集发票 → 检查金额 → 提交审批 → 通知
    │
    ├── 技能2：财务咨询
    │       └── 模式：free（自由对话）
    │           LLM 自己决定怎么回答
    │
    └── 技能3：预算查询
            └── 模式：safe（固定流程）
                查询系统 → 格式化 → 返回结果
```

### 3.2 关键点

| 层级 | 说明 |
|------|------|
| **Agent** | 定义身份（财务、HR、法务...） |
| **技能** | 定义能做什么（报销、咨询...） |
| **模式** | 每个技能有自己的模式（safe/free） |

```
Agent 不选模式
      ↓
技能才选模式
      ↓
一个 Agent 可以有多个技能
      ↓
有的技能是固定的，有的是自由的
```

---

## 四、两种模式对比

### 自由模式（Free）

| 特点 | 说明 |
|------|------|
| 执行方式 | LLM 实时决策 |
| 流程 | 动态变化 |
| 可追溯 | 难 |
| 可恢复 | 难 |
| 速度 | 快 |
| 适合场景 | 探索、聊天、快速验证 |

```
用户：帮我分析这个项目
LLM：让我想想...
     → 诶，我先读 README
     → 哦，发现有个配置文件，读一下
     → 感觉要看下代码结构
     → ...随机应变
```

### 安全模式（Safe）

| 特点 | 说明 |
|------|------|
| 执行方式 | 先规划再执行 |
| 流程 | 固定步骤 |
| 可追溯 | 容易（每步有日志） |
| 可恢复 | 容易（检查点） |
| 速度 | 稍慢 |
| 适合场景 | 正式任务、敏感操作、合规要求 |

```
用户：我要报销打车费
Agent：启动报销流程
      步骤1：收集发票 ✅
      步骤2：检查金额 ✅
      步骤3：提交审批 ✅
      步骤4：通知结果 ✅
      （按部就班，每步留痕）
```

---

## 五、动态定义流程

### 核心难点

```
传统方式（LangGraph）：
    开发者写代码定义流程
    graph.add_node(...)
    graph.add_edge(...)
    ↓
    不适合普通用户

理想的方案：
    用户不用写代码
    但又能定义固定流程
```

### 方案对比

| 方案 | 难度 | 用户体验 | 适合谁 |
|------|------|---------|--------|
| 自然语言定义 | 中 | 最好 | 普通用户 |
| YAML 配置 | 低 | 一般 | 技术用户 |
| 可视化拖拽 | 高 | 直观 | 所有用户 |

### 推荐方案：自然语言 + YAML

#### 方式1：自然语言定义

```
用户输入：
"创建一个报销流程：
 1. 先让员工上传发票
 2. 检查金额是否超过限额
 3. 如果超过就找经理审批
 4. 最后通知员工结果"

Agent 解析后生成流程配置
```

#### 方式2：YAML 配置

```yaml
name: 报销处理
mode: safe
description: 处理员工报销申请

steps:
  - id: 1
    name: 收集发票
    action: ask_user
    prompt: 请上传发票图片或填写发票信息
    save_to: receipt_info
    
  - id: 2
    name: 检查金额
    action: check_rule
    rule: 金额不能超过 {{max_amount}} 元
    
  - id: 3
    name: 提交审批
    action: submit
    endpoint: /api/approval
    
  - id: 4
    name: 通知申请人
    action: notify
    message: 您的报销申请已提交
```

---

## 六、实现思路

### 6.1 统一的流程格式

```python
from pydantic import BaseModel
from typing import Literal

class Step(BaseModel):
    id: int
    name: str
    action: str                    # 动作类型
    params: dict = {}              # 参数
    next_step: int | None = None   # 下一步
    condition: str | None = None   # 条件分支

class Workflow(BaseModel):
    name: str
    mode: Literal["safe", "free"]
    steps: list[Step]
    variables: dict = {}
```

### 6.2 动作类型

| 动作 | 说明 |
|------|------|
| `ask_user` | 向用户提问，等待输入 |
| `check_rule` | 检查规则条件 |
| `call_tool` | 调用工具 |
| `call_api` | 调用外部接口 |
| `notify` | 发送通知 |
| `wait` | 等待一段时间 |

### 6.3 用户触发方式

```
方式A：Agent 自动识别
用户：我要报销打车费
Agent：（识别到"报销"关键词）
       → 触发"报销处理"技能
       → 走固定流程

方式B：用户显式指定
用户：/报销 我要报销打车费
       ↑ 显式指定技能
Agent：启动报销流程...
```

### 6.4 流程执行器

```python
class WorkflowExecutor:
    """执行固定流程"""
    
    def run(self, user_input: str) -> str:
        while True:
            step = self.get_current_step()
            
            # 保存检查点（支持断点恢复）
            self.session.save_checkpoint()
            
            # 执行当前步骤
            result = self.execute_step(step)
            
            # 判断下一步
            if step.condition:
                next_step = self.eval_condition(step.condition)
            else:
                next_step = step.next_step
            
            if next_step is None:
                return "流程执行完成"
            
            self.current_step_id = next_step
```

---

## 七、业界参考

### Dify

- 提供 **Workflow**（可视化流程编排）
- 支持 **Agent**（自由对话）
- 两者可以结合使用

### Coze（扣子）

- 低代码平台
- 支持工作流编排
- 支持多 Agent 协作

### Zapier

- 自然语言描述 → 自动生成工作流
- 无代码自动化

---

## 八、总结

```
                    用户发起任务
                         │
                         ▼
              ┌─────────────────────┐
              │   Agent 识别意图     │
              └─────────────────────┘
                         │
              ┌──────────┴──────────┐
              │                     │
         匹配到技能            未匹配到技能
         (有固定流程)          (自由对话)
              │                     │
              ▼                     ▼
       ┌─────────────┐       ┌─────────────┐
       │  Safe 模式   │       │  Free 模式   │
       │  按步骤执行   │       │  LLM 自由发挥 │
       │  保存检查点   │       │             │
       └─────────────┘       └─────────────┘
```

### 核心价值

1. **一个 Agent，两种能力**
   - 固定流程：合规、可追溯、可恢复
   - 自由对话：灵活、智能、探索性

2. **用户友好**
   - 不用写代码
   - 自然语言或 YAML 定义流程

3. **企业级能力**
   - 敏感操作有固定步骤
   - 每一步都留痕
   - 支持断点恢复

---

## 九、下一步计划

- [ ] 设计统一的流程配置格式
- [ ] 实现自然语言解析成流程
- [ ] 实现流程执行器（支持检查点）
- [ ] 设计技能注册机制
- [ ] 实现意图识别路由

---

*文档整理自 QRClaw 项目讨论*