admin/aiagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a7893210052f20edbcaf78a013343223cff32ed1
aiagent/创建Agent经验.md
rjb b8f340401a 自动布局
2026-01-20 18:05:31 +08:00

22 KiB
Raw Blame History

创建Agent经验总结

📋 目录

  1. 创建Agent的完整流程

  2. 工作流设计经验

  3. 节点配置要点

  4. Prompt设计技巧

  5. 数据流转与上下文传递

  6. 常见问题和解决方案

  7. 最佳实践

  8. 实战案例

创建Agent的完整流程

1. 准备工作

1.1 明确Agent目标

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

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

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

1.2 设计工作流结构

  • 绘制工作流流程图

  • 确定节点类型和数量

  • 规划数据流转路径

  • 考虑分支和合并逻辑

1.3 准备Prompt模板

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

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

  • 明确输出格式要求

2. 编写生成脚本

2.1 脚本结构模板


#!/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. 执行脚本


# 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 布局示例


# 线性布局

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)


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)


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)


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)


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)


end_node = {

    "id": "end-1",

    "type": "end",

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

    "data": {

        "label": "结束",

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

    }

}

要点：

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

  • 可以设置 output_format 控制输出格式

6. 连接边 (edges)


# 普通连接

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 变量引用示例


"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节点合并数据


transform_node = {

    "data": {

        "mode": "merge",

        "mapping": {

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

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

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

        }

    }

}

2.2 在Prompt中传递上下文


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

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

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

2.3 数据传递示例

# 完整的数据流转示例
# 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节点保留关键数据

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

3.2 在Prompt中明确引用

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

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

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

常见问题和解决方案

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

问题现象：

  • 点击"使用"按钮提示无权限
  • API调用返回403

原因分析：

  • Agent状态不是 published 或 running
  • 非owner用户尝试执行 draft 状态的Agent

解决方案：

# 在创建脚本中设置状态
agent = Agent(
    ...
    status="published",  # 直接设置为已发布
    ...
)

2. LLM输出答非所问

问题现象：

  • Agent执行了，但回答不相关
  • 输出内容与用户需求不符

原因分析：

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

解决方案：

# 1. 确保Prompt中包含用户输入
"prompt": """用户需求：{{query}}

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

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

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

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

问题现象：

  • 条件判断后，所有分支都执行了
  • 或者分支执行顺序错误

原因分析：

  • 边的 sourceHandle 未设置或设置错误
  • 条件表达式不正确

解决方案：

# 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节点输出了不必要的数据

解决方案：

# 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节点映射错误
  • 变量名不匹配

解决方案：

# 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 设置过小
  • 输出内容过长

解决方案：

# 根据任务类型调整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开发团队

Reference in New Issue View Git Blame Copy Permalink