Co-creation-projects/czxgg0630-ProductAnalysisAgent/ProductAnalysis_SimpleAgent.ipynb
基于Hello Agents框架的智能化竞品分析系统
- 自动收集竞品信息
- 多维度对比分析
- 生成专业报告
# 安装依赖
!pip install -q hello-agents[all]
# 导入必要的库
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()
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)")
# 创建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("✅ 系统提示词已配置工具调用规范")
# 示例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)
SimpleAgent 采用 单轨/ReAct 范式,是目前最常见的 Agent 实现方式之一。
| 评估维度 | SimpleAgent 表现 | 说明 |
|---|---|---|
| 逻辑复杂度承载 | ★★★ 中低 | 依赖大模型自身的注意力机制去同时兼顾"理解上下文"、"选择工具"和"决定下一步"。分析 3 个竞品可行,分析 10 个极易产生幻觉或遗漏。 |
| 上下文消耗 (Token) | ★★ 较高 | 所有的中间结果、报错信息、循环思考(Thought/Action/Observation)都在同一个上下文窗口里堆叠,容易触发 Context Window 限制。 |
| 可控性与干预度 | ★★ 黑盒状态 | 一旦运行,很难在中间阻断并修改它的思考路径。 |
| 实现复杂度 | ★★★★★ 极简 | 代码量少,易于理解和调试,适合作为入门学习和快速原型验证。 |
| 响应速度 | ★★★★★ 快速 | 无需额外的规划步骤,直接响应用户输入,端到端延迟较低。 |
1. 网络超时风险 (Network/Timeout Issues)
问题现象:在使用 SimpleAgent 时,程序可能因网络问题抛出异常,堆栈信息指向底层的网络读取 (ssl.py: read) 和 httpx。
诊断:这是同步阻塞导致的假死。无论是 LLM 的 API 响应过慢,还是 Tavily 搜索接口被墙/限流,整个主线程都会挂起。
改进建议:在生产环境中,任何外部 API 调用(LLM 或 Search)都必须配置强硬的 timeout 策略,并结合重试机制(如 tenacity 库),防止单点网络波动拖垮整个系统。
2. 防御性编程实践 (Defensive Programming)
现状:CompetitiveInfoSearchTool 中已实现了 try...except 异常处理并返回备用文本。
价值:保证了即使搜索失败,Agent 也能拿到明确的"失败反馈",而不是直接崩溃,让大模型有机会决定是否要重试或跳过。
| 工具 | 当前实现 | 改进方向 |
|---|---|---|
| SearchTool | ✅ 已接入真实 Tavily API | 增加缓存机制、支持多后端切换 |
| DataProcessorTool | ⚠️ 返回固定字符串 | 应接入 LLM 进行真实数据清洗和结构化 |
| ReportGeneratorTool | ⚠️ 返回固定字符串 | 应基于真实数据生成报告,而非 LLM 脑补 |
目前 DataProcessorTool 和 ReportGeneratorTool 只是"假动作"——Agent 调用了它们,但返回的是写死的字符串,最终的长篇报告依然是 LLM 绕过工具直接生成的。
| 场景 | 适合度 | 说明 |
|---|---|---|
| 快速原型验证 | ★★★★★ | 代码简洁,易于迭代 |
| 3个以内竞品分析 | ★★★★ | 复杂度可控,效果较好 |
| 10个以上竞品分析 | ★★ | 易产生幻觉,Token 消耗大 |
| 生产环境部署 | ★★ | 缺乏容错和可观测性 |
| 教学演示 | ★★★★★ | 便于理解 Agent 基本概念 |
SimpleAgent 评级:★★☆☆☆ (2/5)
优势:
劣势:
结论:SimpleAgent 适合作为基础调试脚手架和教学演示,但在复杂业务场景下需要考虑迁移到 Plan-and-Solve 或其他更健壮的架构。
在实际测试中,我们得到以下性能数据:
测试时间: 2026-04-09
说明: SimpleAgent 响应更快,但在复杂场景下容易丢失上下文或产生幻觉。
本次项目基于 Hello Agents 框架成功实现了竞品分析 Agent,主要成果包括:
1. 核心工具链搭建
2. SimpleAgent 实现
SimpleAgent 类构建单轨/ReAct 范式的竞品分析 Agent3. 工程实践
| 挑战 | 解决方案 | 状态 |
|---|---|---|
| 工具导入错误 | 从 BaseTool 改为 Tool,并实现 get_parameters() 方法 | ✅ 已解决 |
| 参数传递为空 | 优化系统提示词,明确指导 LLM 提取产品名称 | ✅ 已解决 |
| 网络 SSL 错误 | 增加异常处理和备用返回,配置代理 | ✅ 已解决 |
| 上下文膨胀 | SimpleAgent 架构固有限制,需在复杂场景下迁移到 Plan-and-Solve | ⚠️ 已知限制 |
| 工具"假动作" | DataProcessorTool 和 ReportGeneratorTool 返回固定字符串,未处理真实数据 | ⚠️ 待改进 |
1. Agent 设计要点
name 比 product_name 更易被 LLM 理解)2. SimpleAgent 的局限性
3. 工具链设计原则
短期改进(1-2 周)
中期改进(1 个月)
长期改进(3 个月)
SimpleAgent 在本次项目中的表现:
推荐后续行动:
项目完成时间: 2026-04-09
作者: czxgg0630
GitHub: https://github.com/czxgg0630