研究代理工具

FastMCP × PydanticAI 研究代理

一个使用PydanticAI的对话式ReAct风格研究代理，它连接到一个MCP HTTP服务器（FastMCP），用于开放网络风格的工具：搜索、获取、笔记记忆和PII（个人可识别信息）保护。该代理生成结构化的研究简报，包含数字引用、简短引文和持久日志。

特点/特性

• 带有MCP工具调用（搜索、获取、笔记、守卫）的ReAct决策循环
• 从抓取的页面中清理并提取片段
• 撰写5至8段的简短文章，并在文中直接标注数字编号的引用[n]
• 确保至少2条简短引语（每条不超过10个字）
• 参考文献部分映射[n]到标题+网址（≥3个不同域名）
• PII（个人可识别信息）保护检查；若标记则创建HITL（人工在环测试）工单
• 日志文件：search_results.json（搜索结果.json）、selected_urls.json（选中网址.json）、snippets.json（片段.json）
• 持久化存储 SQLite 内存（notes.sqlite）

快速入门

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -U pip
pip install -r requirements.txt
Copy-Item .env.example .env  # then edit OPENAI_API_KEY if you have one

运行（确保 MCP_HTTP_URL 指向一个正在运行的 MCP HTTP 服务器组件或开发服务器）：

python -m student.run --topic "US semiconductor export controls (2024–2025) overview" --out artifacts

可选：运行本地开发MCP存根

启动存根服务器（在另一个终端中）：

python -m student.dev_server

然后在运行代理之前，在你的shell中进行设置：

$env:MCP_HTTP_URL="http://127.0.0.1:8765"

写入输出目录的工件：

• brief.md（除非标记为PII）
• report.json（包含 pii_flagged 布尔值）
• search_results.json 翻译为中文是：“搜索结果.json”
• selected_urls.json 翻译为中文是：“选定的URL列表.json”
• snippets.json 翻译成中文是：“代码片段.json”
• notes.sqlite（或已更新）
• hitl_ticket.json（仅当PII被标记时）
• reflection.txt（单篇600-700字的反思，生成一次）

环境变量

• OPENAI_API_KEY（如果模型已存根，则在评分时可选）
• OPENAI_MODEL（默认：openai:gpt-4o-mini）
• MCP_HTTP_URL（必需）：MCP HTTP服务器的基础URL
• ASSIGNMENT_MODE（可选）：dev（开发）或 grading（评分）

开发说明

如果你没有真实的MCP服务器，我们稍后会添加一个最小的存根用于本地测试。评分系统会提供其自己的确定性MCP。

反思：在成功运行非个人身份信息（PII）任务后，若未手动指定，则自动生成名为reflection.txt的文件。

安全

请不要提交真实的API密钥（.env文件已被git忽略）。撤销任何你公开粘贴的密钥。

许可证

教育任务支架（或教学任务脚手架）。