# 创建Agent经验总结（实战版）

> 基于本仓库实际落地的 **Android应用开发助手**（已发布可用）沉淀：从“想法→工作流→落库→发布→验证→避坑”一套流程。

## 1. 目标与验收标准

- **目标**：在 Agent 管理页面出现一个“可运行/可使用”的 Agent，并且能通过 `/api/v1/executions` 正常触发执行并拿到结果。
- **关键验收**：
  - **状态**：Agent 为 `published` 或 `running`（否则普通用户无法执行）
  - **工作流**：`workflow_config` 必须包含合法的 `nodes` / `edges`，能从 `start` 走到 `end`
  - **数据链路**：LLM prompt 能正确拿到用户输入（一般是 `{{query}}` / `{{user_query}}`）

## 2. 两种创建方式：UI vs 脚本

### 2.1 UI 创建（适合调试）

- 优点：所见即所得、方便调整 prompt/连线/节点参数
- 缺点：重复劳动多，不利于批量/版本化

### 2.2 脚本创建（推荐用于“生成一批可运行Agent/一键复现”）

- 典型做法：写一个 `backend/scripts/generate_xxx_agent.py`，直接用 SQLAlchemy 创建或更新 Agent。
- 本仓库示例：
  - `backend/scripts/generate_android_agent.py`（Android应用开发助手）
  - `backend/scripts/generate_content_agent.py`（内容生成助手）

## 3. Agent 能不能“运行”，最关键的规则

### 3.1 Agent 状态与执行权限

后端创建执行时会做状态校验：**非 owner 执行必须是 `published/running`**。

对应代码（要点：状态不对会 403）：

```103:104:backend/app/api/executions.py
        if agent.status not in ["published", "running"] and agent.user_id != current_user.id:
            raise HTTPException(status_code=403, detail="Agent未发布或无权执行")
```

**经验**：
- 如果你希望“创建出来立刻可用”，脚本里就直接写 `status="published"`。
- 如果你希望“先草稿”，脚本里写 `draft`，但要用 owner 测试或再部署发布。

### 3.2 workflow_config 的最低要求

- 必须包含：
  - `nodes`: 节点数组
  - `edges`: 连线数组
- 且能通过校验（创建接口会校验）：
  - 参考：`backend/app/api/agents.py` 中 `create_agent` 会调用 `validate_workflow(...)`

**经验**：
- 最小可运行工作流：`start -> llm -> end`
- 复杂工作流建议：`start -> 分析(llm) -> 分流(condition) -> 子分支(llm/transform) -> 汇总(transform) -> 输出优化(llm) -> end`

## 4. 数据流转与 Prompt 设计（决定“是否答非所问”）

### 4.1 输入字段命名建议

本平台执行 Agent 时，常见输入会放在：
- `query`
- `USER_INPUT`

Android 示例项目也是这样发起的：
- `query = 用户输入`
- `USER_INPUT = 用户输入`

**经验**：
- prompt 里优先用 `{{query}}`（平台链路更稳定）
- 如果你做了 transform 映射，可统一成 `user_query` 再用 `{{user_query}}`

### 4.2 先分析、再生成：降低跑偏

常见稳定结构：
- 第 1 个 LLM：**需求抽取/结构化**（JSON 输出）
- 后续 LLM：拿着“结构化需求 + 原始需求”做生成/诊断/优化

这样可以显著减少“答非所问”，也便于条件分支与 transform 做数据拼接。

## 5. 条件分支的关键坑：`sourceHandle`

条件节点“走哪个分支”，靠 edge 的 `sourceHandle` 来区分（例如 `true` / `false`）。

对应引擎逻辑（要点：**只保留 sourceHandle == branch 的边**）：

```1936:1961:backend/app/services/workflow_engine.py
                if node.get('type') == 'condition':
                    branch = result.get('branch', 'false')
                    # 只保留：不是从条件节点出发的边，或 从条件节点出发且sourceHandle匹配分支的边
                    edges_to_remove = []
                    edges_to_keep = []
                    for edge in active_edges:
                        if edge['source'] == next_node_id:
                            edge_handle = edge.get('sourceHandle')
                            if edge_handle == branch:
                                edges_to_keep.append(edge)
                            else:
                                edges_to_remove.append(edge)
                        else:
                            edges_to_keep.append(edge)
                    active_edges = edges_to_keep
```

**经验**：
- 条件节点的出边必须带 `sourceHandle`，而且值要与引擎产出的 `branch` 完全一致（常用：`true`/`false`）
- 否则会出现：
  - 分支全跑 / 分支全不跑 / 走错分支

## 6. 用脚本创建“可运行Agent”的推荐模板

核心点：
- 查用户（owner）
- 构造 `nodes/edges`
- 若同名存在则更新，否则创建
- 设置 `status="published"`

本仓库可直接复用（已验证创建成功）：
- `backend/scripts/generate_android_agent.py`

运行方式：

```bash
cd /home/renjianbo/aiagent
python3 backend/scripts/generate_android_agent.py
```

运行后会输出 Agent ID、节点数、边数，且状态为 `published`。

## 7. 如何验证 Agent “真的可运行”

### 7.1 前端验证

- 进入 **Agent管理**
- 找到 Agent（例如：Android应用开发助手）
- 状态为 **已发布/运行中**
- 点击 **使用**，输入一句话触发执行

### 7.2 API 验证（推荐可自动化）

1) 登录获取 token（form-urlencoded）
2) 发起执行：

```json
POST /api/v1/executions
{
  "agent_id": "你的agent_id",
  "input_data": {
    "query": "帮我生成一个登录页",
    "USER_INPUT": "帮我生成一个登录页"
  }
}
```

3) 轮询状态：
- `GET /api/v1/executions/{execution_id}/status`
4) 获取结果：
- `GET /api/v1/executions/{execution_id}`

## 8. 常见问题与排查清单

- **Agent 列表里看到了，但点“使用”无权限/403**
  - 检查 `status` 是否为 `published/running`
  - 是否为 owner 在测试草稿

- **LLM 输出跑偏/答非所问**
  - 是否把用户输入稳定透传到了 `{{query}}`
  - 是否先做“需求结构化”再生成
  - prompt 是否过泛、缺少输出格式约束

- **条件节点后续分支乱跑**
  - 检查条件节点出边是否有 `sourceHandle=true/false`
  - 检查引擎分支值是否与 sourceHandle 对齐

- **输出结构混乱**
  - 建议末端增加 `llm-format` 做统一 Markdown 格式化
  - end 节点尽量只输出最终 `output` 字段（不要拼接用户 query）

## 9. 本次落地成果（可复用资产）

- **可运行 Agent**：Android应用开发助手（脚本创建，状态 `published`）
- **生成脚本**：`backend/scripts/generate_android_agent.py`
- **Prompt 方案文档**：`androidExampleDemo/多功能android应用智能体的提示词.md`

---

最后更新：2026-01-20