aiagent/创建Agent经验.md

# 创建Agent经验总结

  

## 📋 目录

  

1. [创建Agent的完整流程](#创建agent的完整流程)

2. [工作流设计经验](#工作流设计经验)

3. [节点配置要点](#节点配置要点)

4. [Prompt设计技巧](#prompt设计技巧)

5. [数据流转与上下文传递](#数据流转与上下文传递)

6. [常见问题和解决方案](#常见问题和解决方案)

7. [最佳实践](#最佳实践)

8. [实战案例](#实战案例)

  

---

  

## 创建Agent的完整流程

  

### 1. 准备工作

  

#### 1.1 明确Agent目标

- **功能定位**：确定Agent要解决什么问题

- **目标用户**：明确使用场景和用户群体

- **输出格式**：确定最终输出的格式（文本、JSON、Markdown等）

  

#### 1.2 设计工作流结构

- 绘制工作流流程图

- 确定节点类型和数量

- 规划数据流转路径

- 考虑分支和合并逻辑

  

#### 1.3 准备Prompt模板

- 为每个LLM节点准备详细的Prompt

- 考虑上下文传递和变量替换

- 明确输出格式要求

  

### 2. 编写生成脚本

  

#### 2.1 脚本结构模板

  

```python

#!/usr/bin/env python3

"""

生成[Agent名称]Agent

[Agent功能描述]

"""

import sys

import os

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

  

from sqlalchemy.orm import Session

from app.core.database import SessionLocal

from app.models.agent import Agent

from app.models.user import User

from datetime import datetime

import uuid

  
  

def generate_xxx_agent(db: Session, username: str = "admin"):

    """生成[Agent名称]Agent"""

    print("=" * 60)

    print("生成[Agent名称]Agent")

    print("=" * 60)

    print()

    # 1. 查找用户

    user = db.query(User).filter(User.username == username).first()

    if not user:

        print(f"❌ 未找到用户 '{username}'，请先创建该用户")

        return

    print(f"✅ 找到用户: {user.username} (ID: {user.id})")

    print()

    # 2. 创建工作流配置

    nodes = []

    edges = []

    # 3. 添加节点

    # ... 节点配置 ...

    # 4. 添加连接

    # ... 边配置 ...

    # 5. 创建或更新Agent

    workflow_config = {

        "nodes": nodes,

        "edges": edges

    }

    agent = db.query(Agent).filter(

        Agent.name == "[Agent名称]",

        Agent.user_id == user.id

    ).first()

    if agent:

        # 更新现有Agent

        agent.workflow_config = workflow_config

        agent.updated_at = datetime.now()

        agent.status = "published"  # 设置为已发布

        print("⚠️  Agent已存在，将更新它...")

    else:

        # 创建新Agent

        agent = Agent(

            id=str(uuid.uuid4()),

            name="[Agent名称]",

            description="[Agent描述]",

            workflow_config=workflow_config,

            status="published",  # 直接设置为已发布，可立即使用

            user_id=user.id,

            version=1

        )

        db.add(agent)

    # 6. 提交并输出结果

    try:

        db.commit()

        db.refresh(agent)

        print("✅ Agent创建/更新成功！")

        print(f"   - ID: {agent.id}")

        print(f"   - 状态: {agent.status}")

        return agent

    except Exception as e:

        db.rollback()

        print(f"❌ 创建Agent失败: {str(e)}")

        return None

  
  

def main():

    """主函数"""

    db = SessionLocal()

    try:

        generate_xxx_agent(db, username="admin")

    finally:

        db.close()

  
  

if __name__ == "__main__":

    main()

```

  

### 3. 执行脚本

  

```bash

# 1. 添加执行权限

chmod +x backend/scripts/generate_xxx_agent.py

  

# 2. 运行脚本

python3 backend/scripts/generate_xxx_agent.py

```

  

### 4. 验证和测试

  

- 在Agent管理页面查看创建的Agent

- 使用"使用"按钮测试Agent功能

- 根据测试结果调整Prompt和工作流

  

---

  

## 工作流设计经验

  

### 1. 常见工作流模式

  

#### 模式1：线性流程

```

开始 → 处理1 → 处理2 → 处理3 → 结束

```

**适用场景**：简单的顺序处理任务

  

#### 模式2：分支流程

```

开始 → 分析 → 条件判断 → [分支A | 分支B] → 整合 → 结束

```

**适用场景**：需要根据条件选择不同处理路径

  

#### 模式3：并行处理

```

开始 → 分析 → [处理A | 处理B | 处理C] → 整合 → 结束

```

**适用场景**：多个独立任务可以并行执行

  

#### 模式4：循环处理

```

开始 → 循环开始 → 处理 → 条件判断 → [继续循环 | 退出] → 结束

```

**适用场景**：需要重复处理的数据

  

### 2. 节点布局建议

  

#### 2.1 位置规划

- **X轴间距**：建议200-250像素，确保节点不重叠

- **Y轴间距**：分支节点建议100-150像素

- **起始位置**：开始节点建议 (50, 300-400)

  

#### 2.2 布局示例

```python

# 线性布局

start_node = {"position": {"x": 50, "y": 400}}

node1 = {"position": {"x": 250, "y": 400}}

node2 = {"position": {"x": 450, "y": 400}}

  

# 分支布局

condition_node = {"position": {"x": 450, "y": 400}}

branch_true = {"position": {"x": 650, "y": 300}}  # 上分支

branch_false = {"position": {"x": 650, "y": 500}}  # 下分支

```

  

### 3. 工作流设计原则

  

#### 3.1 单一职责原则

- 每个节点只负责一个明确的任务

- 避免在一个节点中做太多事情

  

#### 3.2 数据流清晰

- 明确每个节点的输入和输出

- 使用Transform节点整理数据

- 避免数据丢失或混乱

  

#### 3.3 错误处理

- 考虑异常情况的处理

- 提供默认分支

- 添加错误提示节点（可选）

  

#### 3.4 可扩展性

- 预留扩展点

- 使用条件节点支持多种场景

- 保持工作流的灵活性

  

---

  

## 节点配置要点

  

### 1. 开始节点 (start)

  

```python

start_node = {

    "id": "start-1",  # 唯一ID，建议使用 start-1, start-2 等

    "type": "start",

    "position": {"x": 50, "y": 400},

    "data": {

        "label": "开始",

        "output_format": "json"  # 可选：json 或 text

    }

}

```

  

**要点**：

- ID必须唯一

- `output_format` 决定后续节点如何接收数据

  

### 2. LLM节点 (llm)

  

```python

llm_node = {

    "id": "llm-xxx",

    "type": "llm",

    "position": {"x": 250, "y": 400},

    "data": {

        "label": "节点名称",

        "provider": "deepseek",  # 或 "openai"

        "model": "deepseek-chat",  # 模型名称

        "temperature": "0.3",  # 温度参数，字符串格式

        "max_tokens": "2000",  # 最大token数，字符串格式

        "prompt": """你的Prompt内容

使用 {{variable}} 引用变量

使用 {{query}} 引用用户输入

使用 {{output}} 引用上一个节点的输出"""

    }

}

```

  

**要点**：

- `temperature` 和 `max_tokens` 必须是字符串

- Prompt中使用 `{{variable}}` 进行变量替换

- 明确指定输出格式要求（JSON、Markdown等）

  

### 3. 条件节点 (condition)

  

```python

condition_node = {

    "id": "condition-xxx",

    "type": "condition",

    "position": {"x": 450, "y": 400},

    "data": {

        "label": "条件判断",

        "condition": "{variable} contains '关键词' or {variable} contains '另一个关键词'"

    }

}

```

  

**要点**：

- 条件表达式使用 `{variable}` 引用变量

- 支持 `contains`、`==`、`!=` 等操作符

- 支持 `and`、`or` 逻辑运算符

- 连接边需要指定 `sourceHandle`：`"true"` 或 `"false"`

  

### 4. Transform节点 (transform)

  

```python

transform_node = {

    "id": "transform-xxx",

    "type": "transform",

    "position": {"x": 650, "y": 400},

    "data": {

        "label": "数据转换",

        "mode": "merge",  # 或 "replace"、"extract"

        "mapping": {

            "key1": "{{variable1}}",

            "key2": "{{variable2}}",

            "key3": "{{output}}"

        }

    }

}

```

  

**要点**：

- `mode: "merge"` 用于合并多个数据源

- `mode: "replace"` 用于替换整个数据

- `mode: "extract"` 用于提取特定字段

- 使用 `{{variable}}` 引用变量

  

### 5. 结束节点 (end)

  

```python

end_node = {

    "id": "end-1",

    "type": "end",

    "position": {"x": 1450, "y": 400},

    "data": {

        "label": "结束",

        "description": "返回最终结果"

    }

}

```

  

**要点**：

- 结束节点会返回最终输出

- 可以设置 `output_format` 控制输出格式

  

### 6. 连接边 (edges)

  

```python

# 普通连接

edge = {

    "id": "e1",  # 唯一ID

    "source": "start-1",  # 源节点ID

    "target": "llm-xxx"  # 目标节点ID

}

  

# 条件分支连接

edge_true = {

    "id": "e2-true",

    "source": "condition-xxx",

    "target": "branch-true",

    "sourceHandle": "true"  # true分支

}

  

edge_false = {

    "id": "e2-false",

    "source": "condition-xxx",

    "target": "branch-false",

    "sourceHandle": "false"  # false分支

}

```

  

**要点**：

- 每个边必须有唯一的ID

- 条件节点的分支必须指定 `sourceHandle`

- 确保所有节点都有正确的连接

  

---

  

## Prompt设计技巧

  

### 1. Prompt结构

  

#### 1.1 角色定位

```

你是一个专业的[角色]，请[任务描述]。

```

**示例**：

```

你是一个专业的Android开发顾问。请分析用户的需求，提取关键信息。

```

  

#### 1.2 任务说明

- 明确任务目标

- 列出具体要求

- 提供输出格式示例

  

#### 1.3 上下文信息

```

用户需求：{{query}}

需求分析结果：{{requirement_analysis}}

```

  

#### 1.4 输出要求

```

请以JSON格式输出分析结果：

{

  "key1": "value1",

  "key2": "value2"

}

```

  

### 2. 变量使用

  

#### 2.1 常用变量

- `{{query}}` - 用户原始输入

- `{{user_query}}` - 用户查询（可能经过处理）

- `{{output}}` - 上一个节点的输出

- `{{variable_name}}` - 自定义变量（通过Transform节点传递）

  

#### 2.2 变量引用示例

```python

"prompt": """用户需求：{{query}}

需求分析：{{requirement_analysis}}

请根据以上信息生成代码。"""

```

  

### 3. 输出格式控制

  

#### 3.1 JSON格式

```

请以JSON格式输出：

{

  "field1": "value1",

  "field2": ["item1", "item2"]

}

请确保输出是有效的JSON格式。

```

  

#### 3.2 Markdown格式

```

请以Markdown格式输出，包含：

1. 标题

2. 代码块（使用正确的语言标识）

3. 列表

4. 表格（如需要）

```

  

#### 3.3 纯文本格式

```

请直接输出优化后的完整内容（纯文本格式）。

不要包含JSON格式或其他包装。

```

  

### 4. 温度参数选择

  

| 场景 | Temperature | 说明 |

|------|------------|------|

| 代码生成 | 0.2-0.3 | 需要准确、一致的输出 |

| 需求分析 | 0.3-0.5 | 需要平衡准确性和灵活性 |

| 创意内容 | 0.7-0.9 | 需要多样性和创造性 |

| 格式化输出 | 0.1-0.2 | 需要严格按照格式要求 |

  

### 5. Token限制

  

| 任务类型 | Max Tokens | 说明 |

|---------|-----------|------|

| 简单分析 | 1000-2000 | 简短的分析和提取 |

| 代码生成 | 3000-4000 | 完整的代码文件 |

| 长文档生成 | 4000-8000 | 长篇文章或文档 |

| 格式化输出 | 2000-4000 | 整理和格式化内容 |

  

---

  

## 数据流转与上下文传递

  

### 1. 数据流转路径

  

```

开始节点 → LLM节点 → Transform节点 → 条件节点 → LLM节点 → 结束节点

   ↓          ↓            ↓            ↓           ↓          ↓

  query    output      merged_data   condition   solution   final_output

```

  

### 2. 上下文传递策略

  

#### 2.1 使用Transform节点合并数据

```python

transform_node = {

    "data": {

        "mode": "merge",

        "mapping": {

            "user_query": "{{query}}",  # 保留原始输入

            "analysis": "{{output}}",   # 保留分析结果

            "context": "{{previous_output}}"  # 保留上下文

        }

    }

}

```

  

#### 2.2 在Prompt中传递上下文

```python

"prompt": """用户原始需求：{{user_query}}

需求分析结果：{{requirement_analysis}}

请根据以上信息生成代码。"""
```

#### 2.3 数据传递示例

```python
# 完整的数据流转示例
# 1. 开始节点输出：{"query": "用户输入"}
# 2. LLM节点分析，输出：{"app_type": "...", "modules": [...]}
# 3. Transform节点合并：
transform_node = {
    "data": {
        "mode": "merge",
        "mapping": {
            "user_query": "{{query}}",           # 保留原始输入
            "requirement_analysis": "{{output}}" # 保留分析结果
        }
    }
}
# 4. 后续LLM节点可以使用：{{user_query}} 和 {{requirement_analysis}}
```

### 3. 避免数据丢失

#### 3.1 使用Transform节点保留关键数据

```python
# 在分支前合并数据，确保所有分支都能访问
transform_before_branch = {
    "data": {
        "mode": "merge",
        "mapping": {
            "original_query": "{{query}}",
            "analysis": "{{output}}",
            "context": "{{previous_context}}"
        }
    }
}
```

#### 3.2 在Prompt中明确引用

```python
"prompt": """请参考以下完整上下文：

原始需求：{{user_query}}
分析结果：{{requirement_analysis}}
历史上下文：{{context}}

根据以上信息完成任务。"""
```

---

## 常见问题和解决方案

### 1. Agent无法执行（403错误）

**问题现象**：
- 点击"使用"按钮提示无权限
- API调用返回403

**原因分析**：
- Agent状态不是 `published` 或 `running`
- 非owner用户尝试执行 `draft` 状态的Agent

**解决方案**：
```python
# 在创建脚本中设置状态
agent = Agent(
    ...
    status="published",  # 直接设置为已发布
    ...
)
```

### 2. LLM输出答非所问

**问题现象**：
- Agent执行了，但回答不相关
- 输出内容与用户需求不符

**原因分析**：
- Prompt中没有正确引用用户输入
- 缺少需求分析步骤
- 上下文传递丢失

**解决方案**：
```python
# 1. 确保Prompt中包含用户输入
"prompt": """用户需求：{{query}}

请根据用户需求完成任务。"""

# 2. 添加需求分析节点
# 先分析需求，再生成内容

# 3. 使用Transform节点保留原始输入
transform_node = {
    "data": {
        "mode": "merge",
        "mapping": {
            "user_query": "{{query}}"  # 保留原始输入
        }
    }
}
```

### 3. 条件节点分支执行错误

**问题现象**：
- 条件判断后，所有分支都执行了
- 或者分支执行顺序错误

**原因分析**：
- 边的 `sourceHandle` 未设置或设置错误
- 条件表达式不正确

**解决方案**：
```python
# 1. 确保条件节点的边有sourceHandle
edge_true = {
    "id": "e-true",
    "source": "condition-xxx",
    "target": "branch-true",
    "sourceHandle": "true"  # 必须设置
}

edge_false = {
    "id": "e-false",
    "source": "condition-xxx",
    "target": "branch-false",
    "sourceHandle": "false"  # 必须设置
}

# 2. 条件表达式要明确
"condition": "{user_query} contains '生成' or {user_query} contains '创建'"
```

### 4. 输出格式混乱

**问题现象**：
- 输出包含多余信息
- 格式不统一
- 代码块格式错误

**原因分析**：
- 缺少格式化节点
- Prompt中格式要求不明确
- End节点输出了不必要的数据

**解决方案**：
```python
# 1. 添加格式化节点
format_node = {
    "id": "llm-format",
    "type": "llm",
    "data": {
        "label": "格式化输出",
        "temperature": "0.1",  # 低温度确保格式一致
        "prompt": """请将以下内容整理成专业的Markdown格式：

内容：{{input}}

要求：
- 使用清晰的标题层级
- 代码块使用正确的语言标识
- 格式统一、易读"""
    }
}

# 2. End节点只输出必要字段
# 在workflow_engine.py中，End节点会排除query、USER_INPUT等字段
```

### 5. 数据传递中断

**问题现象**：
- 后续节点无法获取前面节点的输出
- 变量引用失败

**原因分析**：
- 节点之间缺少连接
- Transform节点映射错误
- 变量名不匹配

**解决方案**：
```python
# 1. 检查节点连接
edges = [
    {"id": "e1", "source": "node1", "target": "node2"},
    {"id": "e2", "source": "node2", "target": "node3"}
]

# 2. 使用Transform节点明确映射
transform_node = {
    "data": {
        "mode": "merge",
        "mapping": {
            "key1": "{{output}}",      # 上一个节点的输出
            "key2": "{{query}}",        # 用户输入
            "key3": "{{custom_var}}"    # 自定义变量
        }
    }
}

# 3. 在Prompt中正确引用
"prompt": """使用变量：{{key1}}、{{key2}}、{{key3}}"""
```

### 6. Token限制导致输出截断

**问题现象**：
- 输出内容不完整
- 代码生成到一半就停止了

**原因分析**：
- `max_tokens` 设置过小
- 输出内容过长

**解决方案**：
```python
# 根据任务类型调整max_tokens
llm_node = {
    "data": {
        "max_tokens": "4000",  # 代码生成建议3000-4000
        # 长文档建议4000-8000
    }
}
```

---

## 最佳实践

### 1. 工作流设计原则

#### 1.1 单一职责
- 每个节点只做一件事
- 避免在一个节点中处理多个任务

#### 1.2 数据流清晰
- 明确每个节点的输入输出
- 使用Transform节点整理数据
- 保留关键上下文信息

#### 1.3 错误处理
- 提供默认分支
- 考虑异常情况
- 添加错误提示

#### 1.4 可扩展性
- 预留扩展点
- 使用条件节点支持多种场景
- 保持工作流灵活性

### 2. Prompt设计原则

#### 2.1 明确角色定位
```
你是一个专业的[角色]，请[任务描述]。
```

#### 2.2 结构化输出
- 明确指定输出格式（JSON、Markdown等）
- 提供输出示例
- 要求验证格式正确性

#### 2.3 上下文传递
- 在Prompt中明确引用所有需要的变量
- 保留原始用户输入
- 传递分析结果和上下文

#### 2.4 温度参数选择
- 代码生成：0.2-0.3（准确）
- 需求分析：0.3-0.5（平衡）
- 创意内容：0.7-0.9（多样）
- 格式化：0.1-0.2（严格）

### 3. 节点配置建议

#### 3.1 节点ID命名规范
- 开始节点：`start-1`, `start-2`
- LLM节点：`llm-xxx`（如 `llm-analysis`, `llm-generation`）
- 条件节点：`condition-xxx`
- Transform节点：`transform-xxx`
- 结束节点：`end-1`

#### 3.2 边ID命名规范
- 普通边：`e1`, `e2`, `e3`...
- 条件分支：`e-true`, `e-false`
- 多分支：`e-branch1`, `e-branch2`

#### 3.3 位置布局
- X轴间距：200-250像素
- Y轴间距：分支节点100-150像素
- 起始位置：(50, 300-400)

### 4. 测试和验证

#### 4.1 单元测试
- 测试每个节点的输入输出
- 验证数据传递正确性
- 检查条件分支逻辑

#### 4.2 集成测试
- 测试完整工作流
- 验证最终输出格式
- 检查错误处理

#### 4.3 用户测试
- 收集真实使用反馈
- 根据反馈调整Prompt
- 优化工作流结构

---

## 实战案例

### 案例1：Android应用开发助手

**目标**：帮助开发者快速生成、优化和调试Android应用

**工作流结构**：
```
开始 → 需求分析 → 需求分类 → [代码生成 | 架构设计/问题诊断/性能优化] → 结果整合 → 格式化输出 → 结束
```

**关键设计**：
1. **需求分析节点**：提取结构化信息（JSON格式）
2. **需求分类节点**：根据关键词判断需求类型
3. **分支处理**：不同需求类型走不同分支
4. **结果整合**：使用Transform节点合并数据
5. **格式化输出**：统一Markdown格式

**脚本位置**：`backend/scripts/generate_android_agent.py`

**状态**：已发布，可直接使用

### 案例2：内容生成助手

**目标**：根据用户需求生成各种类型的高质量内容

**工作流结构**：
```
开始 → 需求分析 → 内容类型判断 → [文章生成 | 文案生成 | 脚本生成 | 通用生成] → 内容整合 → 内容优化 → 结束
```

**关键设计**：
1. **多分支处理**：根据内容类型选择不同生成策略
2. **内容优化**：添加优化润色节点
3. **格式统一**：确保输出格式一致

**脚本位置**：`backend/scripts/generate_content_agent.py`

### 案例3：智能需求分析与解决方案生成器

**目标**：分析用户需求并生成专业解决方案

**工作流结构**：
```
开始 → 需求理解 → 需求分类 → [技术方案分支 | 业务流程分支] → 方案整合 → 输出优化 → 结束
```

**关键设计**：
1. **深度分析**：多步骤需求理解
2. **专业分支**：技术方案和业务流程分开处理
3. **方案整合**：合并各分支结果

---

## 总结

创建Agent是一个系统性的工作，需要：

1. **明确目标**：确定Agent要解决什么问题
2. **设计工作流**：规划节点和连接关系
3. **编写Prompt**：设计清晰、有效的提示词
4. **数据流转**：确保上下文正确传递
5. **测试验证**：充分测试各种场景
6. **持续优化**：根据反馈不断改进

### 关键要点

- ✅ **状态设置**：创建时直接设置 `status="published"` 可立即使用
- ✅ **数据传递**：使用Transform节点保留关键上下文
- ✅ **条件分支**：必须设置 `sourceHandle` 才能正确分支
- ✅ **Prompt设计**：明确角色、任务、输出格式
- ✅ **格式化输出**：添加格式化节点确保输出统一

### 参考资源

- **生成脚本示例**：
  - `backend/scripts/generate_android_agent.py`
  - `backend/scripts/generate_content_agent.py`
  - `backend/scripts/generate_smart_agent.py`

- **API文档**：
  - `backend/app/api/agents.py` - Agent管理API
  - `backend/app/api/executions.py` - 执行管理API

- **工作流引擎**：
  - `backend/app/services/workflow_engine.py` - 工作流执行逻辑

- **提示词文档**：
  - `androidExampleDemo/多功能android应用智能体的提示词.md`

---

**最后更新**：2026-01-20

**版本**：v1.0

**作者**：Agent开发团队