HamsterResearchAgent

“寻找AI全能王”阿里云 Data+AI 工程师全球大奖赛：高校赛道 鼠鼠队参赛作品

初赛88名

复赛33名

参赛反思

没有搭建起一个测评流水线，在初赛时一边测题目一边改，只能说是搭建起了一个能跑的agent，没有进一步根据比赛题目和特征进行优化

搜索API选择过于单一，在复赛测评的时候API额度不够了，没有备选API，和根据中英文切换搜索引擎

核心特性

• Thinker-Judge-Actor 架构: 采用经典的认知架构，将任务拆分为思考规划 (Thinker)、批判决策 (Judge) 和行动执行 (Actor) 三个阶段，确保每一步操作都经过深思熟虑。
• 自我修正与反思: 具备自我反思能力，Judge 节点会评估当前研究进展，若发现方向错误或信息不足，会驳回 Thinker 的提案并要求重试。
• 鲁棒的执行机制:
  • API Key 轮询: 内置 SerpApi 多 Key 轮换机制，自动处理额度超限 (429/402) 错误，保障搜索服务不中断。
  • 超时与重试: 针对 LLM 和网络请求实现了超时保护 (90s) 和智能重试策略。
  • 防死循环: 能够检测 LLM 的无意义重复输出或思维发散，并自动截断或纠正。
• 流式输出: 支持 Server-Sent Events (SSE) 协议，提供流畅的实时响应体验。
• 结构化输出 (Function Call): 关键节点使用函数调用输出，降低解析错误并提升稳定性。
• 可控计算工具: 内置受限 python_exec，用于确定性计算（无文件/网络，超时限制）。

🏗️ 架构设计

本智能体的工作流基于图结构 (Graph) 运行：

核心节点说明

1. Preprocessing (预处理): 分析用户问题，提取关键实体 (Events) 和关系 (Relations)。
2. Thinker (思考者): “大脑”。分析当前已知信息，识别逻辑缺口，规划下一步行动 (如搜索某个关键词)。
3. Judge (评判者): “质检员”。审核 Thinker 的计划是否合理、是否重复或陷入死循环。只有通过审核的计划才会被执行。
4. Actor (执行者): “手”。根据指令调度具体工具。
5. Tools (工具):
   • web_search: 调用搜索引擎 (Google via SerpApi) 获取信息。
   • web_browse: 访问具体网页 URL 提取深度内容。
   • python_exec: 执行受限 Python 代码，用于确定性计算。
   • rewrite_query: 优化搜索关键词。
6. Final Answer: 综合所有研究成果，生成最终回答。
7. Format Answer: 对最终答案做格式与标点校验。

🛠️ 环境准备与安装

推荐使用 Python 3.10+ 版本。

1. 克隆项目

git clone <repository_url>
cd HamsterResearchAgent

2. 配置环境变量

在项目根目录创建 .env 文件，填入必要的 API Key：

# 阿里百炼/通义千问 API Key
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Google Search API (SerpApi)
# 支持配置多个 Key 以通过逗号分隔 (key1,key2,key3)，系统会自动轮询使用
SERP_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx,yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

# 模型配置 (可选)
MASTER_MODEL=qwen3.5-plus
BASE_MODEL=qwen3.5-flash

# API Base URL (可选)
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

🚀 运行与部署

本项目基于 agentscope-runtime 开发，可通过标准的 ASGI 服务器启动。

启动服务

# 假设 agent_app 暴露了 ASGI 接口 (具体视 agentscope 运行方式而定)
python agent.py
# 或使用 uvicorn (如果代码中集成了 server 启动)

📡 API 调用示例

智能体提供 /answer 接口用于接收问题并返回答案。

响应说明

接口默认返回 Server-Sent Events (SSE) 流：

• 中间过程: 默认隐藏，仅在内部记录。
• 最终答案: 当智能体完成研究后，会推送包含 answer 字段的 JSON 数据。

🔐 Python 计算工具说明

python_exec 仅用于纯计算，默认禁止文件、网络与导入。代码需设置 result 变量作为输出。

允许的内置函数与模块详见 prompts/python_exec_prompt.md。

📂 项目结构

HamsterResearchAgent/
├── agent.py            # 主程序入口，定义 AgentApp 和 Graph 结构
├── config.py           # 配置加载 (.env 管理)
├── requirements.txt    # 项目依赖
├── graph/              # 图节点逻辑
│   ├── nodes.py        # Thinker/Judge/Actor 等核心节点函数
│   ├── tools.py        # Web Search/Browse 工具实现
│   └── states.py       # Graph 状态定义 (State Schema)
├── prompts/            # 修改和管理各类 Prompt (思考、提取、总结等)
│   ├── thinker_prompt.md
│   ├── judge_prompt.md
│   ├── python_exec_prompt.md
│   ├── ...
├── schemas/             # 结构化输出与行动 Schema
│   ├── action_schema.json
│   ├── final_answer_schema.json
│   ├── format_answer_schema.json
│   ├── rerank_schema.json
│   ├── ...
├── utils/              # 通用工具函数
│   ├── llm_utils.py    # LLM 调用封装 (含重试、轮询保护)
│   └── file_loader.py  # 文件读取辅助
└── .env                # (需自行创建) 环境变量配置文件