Back to Hello Agents

智能竞品分析Agent

Co-creation-projects/czxgg0630-ProductAnalysisAgent/ProductAnalysis_SimpleAgent.ipynb

1.0.315.5 KB
Original Source

智能竞品分析Agent

基于Hello Agents框架的智能化竞品分析系统

  • 自动收集竞品信息
  • 多维度对比分析
  • 生成专业报告

作者信息

  • 姓名: czxgg0630
  • GitHub: @czxgg0630
  • 日期: 2026-04-09

第2部分: 环境配置

python
# 安装依赖
!pip install -q hello-agents[all]
python
# 导入必要的库
from hello_agents import SimpleAgent, HelloAgentsLLM
from hello_agents.tools import Tool, ToolParameter
from hello_agents.tools.builtin.search_tool import SearchTool
from typing import Dict, Any, List
import os
os.environ['HTTPS_PROXY'] = 'http://127.0.0.1:8800'  # 你的代理地址
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

第3部分: 工具定义

python
class CompetitiveInfoSearchTool(Tool):
    """竞品信息搜索工具 - 使用真实搜索API"""
    
    def __init__(self):
        super().__init__(
            name="competitive_info_search",
            description="搜索指定竞品的产品信息、功能特性、定价策略等"
        )
        # 初始化内置搜索工具,使用 Tavily 后端
        self.search = SearchTool(backend="tavily")
    
    def get_parameters(self) -> List[ToolParameter]:
        """获取工具参数定义"""
        return [
            ToolParameter(
                name="product_name",
                type="string",
                description="要搜索的竞品名称",
                required=True
            )
        ]
    
    def run(self, parameters: Dict[str, Any]) -> str:
        """执行工具,使用真实搜索"""
        product_name = parameters.get("product_name", "")
        print(f"🔍 正在搜索 {product_name} 的竞品信息...")
        
        # 使用真实搜索API
        try:
            search_query = f"{product_name} 产品功能介绍 定价 优缺点 2024"
            result = self.search.run({
                "query": search_query,
                "max_results": 5
            })
            
            # 格式化搜索结果
            return f"""
【{product_name} 搜索结果】
{result}
"""
        except Exception as e:
            print(f"⚠️ 搜索失败: {e},使用备用数据")
            # 如果搜索失败,返回提示信息
            return f"""
【{product_name} 信息】
- 搜索遇到问题,请检查网络或API配置
- 产品名称: {product_name}
- 建议手动补充信息
"""


class DataProcessorTool(Tool):
    """数据处理工具 - 清洗和结构化竞品数据"""
    
    def __init__(self):
        super().__init__(
            name="data_processor",
            description="将原始竞品数据清洗并构建对比矩阵"
        )
    
    def get_parameters(self) -> List[ToolParameter]:
        """获取工具参数定义"""
        return [
            ToolParameter(
                name="raw_data",
                type="string",
                description="原始收集的竞品数据",
                required=True
            )
        ]
    
    def run(self, parameters: Dict[str, Any]) -> str:
        """执行工具"""
        print("📊 正在处理并结构化数据...")
        return """
【数据结构化结果】
1. ✓ 提取各竞品核心属性
2. ✓ 统一数据格式
3. ✓ 构建对比维度框架
"""


class ReportGeneratorTool(Tool):
    """报告生成工具 - 生成专业的竞品分析报告"""
    
    def __init__(self):
        super().__init__(
            name="report_generator",
            description="基于分析数据生成Markdown格式的竞品分析报告"
        )
    
    def get_parameters(self) -> List[ToolParameter]:
        """获取工具参数定义"""
        return [
            ToolParameter(
                name="analysis_data",
                type="string",
                description="分析后的数据",
                required=True
            )
        ]
    
    def run(self, parameters: Dict[str, Any]) -> str:
        """执行工具"""
        print("📝 正在生成竞品分析报告...")
        return "# 竞品分析报告\n\n## 执行摘要\n分析完成..."

print("✅ 三个核心工具已定义完成(搜索工具使用真实API)")

第4部分: 智能体构建

python
# 创建LLM
llm = HelloAgentsLLM()

# 定义系统提示词 - 明确指导LLM如何调用工具
SYSTEM_PROMPT = """你是一位专业的竞品分析专家,擅长通过系统化的方法对多个竞品进行深度分析。

【工具调用规范 - 必须遵守】

1. 当需要搜索竞品信息时,必须调用 competitive_info_search 工具
2. 参数格式必须是:{"product_name": "产品名称"}
3. product_name 必须是明确的单个产品名称,不能为空
4. 如果用户输入包含多个产品(如"分析A、B、C"),你需要分别调用搜索工具,每次只搜索一个产品

【调用示例】
- 搜索Notion: {"product_name": "Notion"}
- 搜索Obsidian: {"product_name": "Obsidian"}
- 搜索Logseq: {"product_name": "Logseq"}

【工作流程】
1. 从用户输入中提取所有竞品名称
2. 对每个产品分别调用 competitive_info_search 工具进行搜索
3. 使用 data_processor 工具处理收集到的数据
4. 使用 report_generator 工具生成最终报告
5. 基于搜索结果生成完整的竞品分析报告

【重要提醒】
- 严禁在 product_name 参数中传入空字符串
- 必须等待工具返回结果后再进行下一步
- 分析报告必须基于真实的搜索数据,不要编造"""

# 创建主控Agent
agent = SimpleAgent(
    name="竞品分析专家",
    llm=llm,
    system_prompt=SYSTEM_PROMPT
)

# 添加三类核心工具
agent.add_tool(CompetitiveInfoSearchTool())
agent.add_tool(DataProcessorTool())
agent.add_tool(ReportGeneratorTool())

print("✅ Plan-and-Solve 竞品分析Agent已初始化")
print("✅ 系统提示词已配置工具调用规范")

第5部分: 功能演示

python
# 示例1: 基础竞品分析
import time
from datetime import datetime

print("=" * 70)
print("📊 示例1: SimpleAgent 竞品快速分析")
print("=" * 70)

target_products = ["盒马", "叮咚买菜", "山姆会员商店"]
print(f"\n🎯 分析目标: {', '.join(target_products)}")
print(f"⏰ 开始时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
print("-" * 70)

# 执行分析
start_time = time.time()
result = agent.run(
    f"请对以下竞品进行深度对比分析: {', '.join(target_products)}。"
)
elapsed_time = time.time() - start_time

# 美观的输出排版
print("\n" + "=" * 70)
print("📋 分析完成")
print("=" * 70)
print(f"⏱️  总耗时: {elapsed_time:.2f} 秒")
print(f"📝 报告长度: {len(result)} 字符")
print("-" * 70)

# 显示报告摘要
print("\n📄 报告预览(前1000字符):")
print("-" * 70)
print(result[:1000] + "..." if len(result) > 1000 else result)
print("-" * 70)

# 保存结果到文件
output_filename = f"outputs/demo_result_{datetime.now().strftime('%Y%m%d_%H%M%S')}.md"
with open(output_filename, 'w', encoding='utf-8') as f:
    f.write(f"# 竞品分析报告\n\n")
    f.write(f"**分析时间**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n")
    f.write(f"**分析产品**: {', '.join(target_products)}\n\n")
    f.write(f"**分析耗时**: {elapsed_time:.2f} 秒\n\n")
    f.write("---\n\n")
    f.write(result)

print(f"\n💾 报告已保存至: {output_filename}")
print("=" * 70)

第6部分: 性能评估

第六部分: 性能评估与架构深度分析 (SimpleAgent)

一、SimpleAgent 架构特点分析

SimpleAgent 采用 单轨/ReAct 范式,是目前最常见的 Agent 实现方式之一。

评估维度SimpleAgent 表现说明
逻辑复杂度承载★★★ 中低依赖大模型自身的注意力机制去同时兼顾"理解上下文"、"选择工具"和"决定下一步"。分析 3 个竞品可行,分析 10 个极易产生幻觉或遗漏。
上下文消耗 (Token)★★ 较高所有的中间结果、报错信息、循环思考(Thought/Action/Observation)都在同一个上下文窗口里堆叠,容易触发 Context Window 限制。
可控性与干预度★★ 黑盒状态一旦运行,很难在中间阻断并修改它的思考路径。
实现复杂度★★★★★ 极简代码量少,易于理解和调试,适合作为入门学习和快速原型验证。
响应速度★★★★★ 快速无需额外的规划步骤,直接响应用户输入,端到端延迟较低。

二、执行稳定性与异常分析 (Stability & Error Handling)

1. 网络超时风险 (Network/Timeout Issues)

问题现象:在使用 SimpleAgent 时,程序可能因网络问题抛出异常,堆栈信息指向底层的网络读取 (ssl.py: read) 和 httpx。

诊断:这是同步阻塞导致的假死。无论是 LLM 的 API 响应过慢,还是 Tavily 搜索接口被墙/限流,整个主线程都会挂起。

改进建议:在生产环境中,任何外部 API 调用(LLM 或 Search)都必须配置强硬的 timeout 策略,并结合重试机制(如 tenacity 库),防止单点网络波动拖垮整个系统。

2. 防御性编程实践 (Defensive Programming)

现状:CompetitiveInfoSearchTool 中已实现了 try...except 异常处理并返回备用文本。

价值:保证了即使搜索失败,Agent 也能拿到明确的"失败反馈",而不是直接崩溃,让大模型有机会决定是否要重试或跳过。

三、工具链深度评估 (Toolchain Assessment)

当前状态:PoC (概念验证) 阶段

工具当前实现改进方向
SearchTool✅ 已接入真实 Tavily API增加缓存机制、支持多后端切换
DataProcessorTool⚠️ 返回固定字符串应接入 LLM 进行真实数据清洗和结构化
ReportGeneratorTool⚠️ 返回固定字符串应基于真实数据生成报告,而非 LLM 脑补

关键问题

目前 DataProcessorTool 和 ReportGeneratorTool 只是"假动作"——Agent 调用了它们,但返回的是写死的字符串,最终的长篇报告依然是 LLM 绕过工具直接生成的。

四、SimpleAgent 适用场景

场景适合度说明
快速原型验证★★★★★代码简洁,易于迭代
3个以内竞品分析★★★★复杂度可控,效果较好
10个以上竞品分析★★易产生幻觉,Token 消耗大
生产环境部署★★缺乏容错和可观测性
教学演示★★★★★便于理解 Agent 基本概念

五、综合评定

SimpleAgent 评级:★★☆☆☆ (2/5)

优势

  • 实现简单,代码量少
  • 响应快速,适合快速原型
  • 易于理解和调试

劣势

  • 不具备复杂业务的工程韧性
  • 黑盒执行,难以干预
  • 上下文膨胀问题严重
  • 缺乏显式规划能力

结论:SimpleAgent 适合作为基础调试脚手架和教学演示,但在复杂业务场景下需要考虑迁移到 Plan-and-Solve 或其他更健壮的架构。

六、性能实测数据

在实际测试中,我们得到以下性能数据:

  • 信息搜索工具: 平均响应时间约 0.5-2 秒(取决于网络状况)
  • 数据处理工具: 本地处理,响应时间 < 0.01 秒
  • 报告生成工具: 本地处理,响应时间 < 0.01 秒
  • 完整分析流程: 3 个竞品分析约需 20-60 秒(比 Plan-and-Solve 更快,但缺少规划透明度)

测试时间: 2026-04-09

说明: SimpleAgent 响应更快,但在复杂场景下容易丢失上下文或产生幻觉。

第7部分: 总结与展望

第七部分: 项目总结与展望

一、实现的功能

本次项目基于 Hello Agents 框架成功实现了竞品分析 Agent,主要成果包括:

1. 核心工具链搭建

  • CompetitiveInfoSearchTool: 基于 Tavily API 的真实搜索工具,可动态抓取竞品信息
  • DataProcessorTool: 数据处理工具框架(当前为 PoC 阶段)
  • ReportGeneratorTool: 报告生成工具框架(当前为 PoC 阶段)

2. SimpleAgent 实现

  • ✅ 基于 SimpleAgent 类构建单轨/ReAct 范式的竞品分析 Agent
  • ✅ 配置详细的系统提示词,指导 LLM 正确调用工具
  • ✅ 实现了工具注册和自动调用机制
  • ✅ 完整的竞品分析流程:搜索 → 处理 → 报告

3. 工程实践

  • ✅ 环境变量配置(.env)管理 API Keys
  • ✅ 防御性编程:搜索工具包含 try-except 异常处理
  • ✅ 代理支持:适配国内网络环境的 HTTPS_PROXY 配置

二、遇到的挑战与解决方案

挑战解决方案状态
工具导入错误BaseTool 改为 Tool,并实现 get_parameters() 方法✅ 已解决
参数传递为空优化系统提示词,明确指导 LLM 提取产品名称✅ 已解决
网络 SSL 错误增加异常处理和备用返回,配置代理✅ 已解决
上下文膨胀SimpleAgent 架构固有限制,需在复杂场景下迁移到 Plan-and-Solve⚠️ 已知限制
工具"假动作"DataProcessorTool 和 ReportGeneratorTool 返回固定字符串,未处理真实数据⚠️ 待改进

三、关键经验教训

1. Agent 设计要点

  • 系统提示词必须足够详细,明确指导 LLM 如何调用工具
  • 工具参数名要简洁明了(如 nameproduct_name 更易被 LLM 理解)
  • 必须做防御性编程,网络请求随时可能失败

2. SimpleAgent 的局限性

  • 适合 3 个以内竞品的快速分析
  • 不适合复杂多步骤任务(易丢失上下文)
  • 黑盒执行,难以干预和调试

3. 工具链设计原则

  • 工具应该真正处理数据,而不是返回固定文本
  • 每个工具应该只做一件事,保持单一职责
  • 工具的输入输出应该可验证、可测试

四、未来改进方向

短期改进(1-2 周)

  • 真实数据处理:让 DataProcessorTool 真正解析搜索返回的文本,提取结构化信息
  • 真实报告生成:让 ReportGeneratorTool 基于结构化数据生成报告
  • 重试机制:使用 tenacity 库为搜索工具添加自动重试
  • 缓存机制:缓存搜索结果,避免重复调用 API

中期改进(1 个月)

  • 多后端搜索:支持 DuckDuckGo 作为 Tavily 的免费备选
  • 结果持久化:将分析结果保存到数据库,支持历史查询
  • 可视化图表:使用 matplotlib/plotly 生成对比雷达图、柱状图
  • 批量分析:支持从 CSV/Excel 导入竞品列表进行批量分析

长期改进(3 个月)

  • Web 界面:使用 Gradio/Streamlit 构建用户友好的界面
  • 增量更新:支持定期监控竞品动态,自动检测变化
  • 多模态支持:分析竞品的截图、宣传视频等内容
  • 协作功能:支持团队共享分析结果、添加评论

五、总结评价

SimpleAgent 在本次项目中的表现

  • 学习价值高:代码简洁,易于理解 Agent 基本原理
  • 快速验证:适合快速原型验证和教学演示
  • ⚠️ 生产限制:不具备复杂业务的工程韧性

推荐后续行动

  1. 短期:完善 DataProcessorTool 和 ReportGeneratorTool,让工具链真正运转
  2. 中期:对比体验 PlanAndSolveAgent,理解两种范式的差异
  3. 长期:基于业务需求选择合适的架构进行产品化

项目完成时间: 2026-04-09
作者: czxgg0630
GitHub: https://github.com/czxgg0630