最小论文侦察 Agent

这是一个为学习 Agent 原理设计的最小项目。它不是把问题直接交给模型回答，而是让模型在一个可见循环里自主选择本地工具：

1. search_papers：检索论文笔记；
2. read_paper：读取完整证据；
3. save_finding：在用户要求时保存有证据的结论。

模型只负责选择行动和组织答案；Python 程序才真正执行工具。

1. Windows 环境准备

需要 Python 3.10 或更高版本。在 PowerShell 中进入项目目录：

py -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

2. 设置智谱配置

不要把 API Key 发给别人，也不要写进代码。只在当前 PowerShell 窗口设置：

$env:ZAI_API_KEY="你的智谱APIKey"
$env:LLM_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
$env:LLM_MODEL="glm-5.3-flash"

如果智谱控制台显示的 Flash 模型 ID 不同，只修改 LLM_MODEL。关闭这个 PowerShell 窗口后，临时环境变量会失效。

3. 先做不花钱的本地检查

python agent.py --check
python agent.py --demo-tools
python -m unittest discover -s tests -v

以上命令都不会请求模型 API。

4. 第一次真实运行

单问题模式：

python agent.py --question "为什么 ReAct 对现代 Agent 很重要？请先查找本地论文再回答。"

交互模式：

python agent.py

可以继续提问：

RAG 和 Agent 有什么区别？
从 Transformer 到 Toolformer，关键能力是怎么演进的？
请比较 ReAct 和 Reflexion，并把结论保存下来。

运行时会显示每轮工具名称、参数和结果。完整轨迹保存在 output/trace.jsonl，明确要求保存的研究结论在 output/findings.jsonl。

5. 更换其他国产 API

代码使用的是兼容协议，换供应商只修改环境变量。

DeepSeek 示例：

$env:LLM_API_KEY="你的DeepSeekKey"
$env:LLM_BASE_URL="https://api.deepseek.com/"
$env:LLM_MODEL="deepseek-v4-flash"

硅基流动示例：

$env:LLM_API_KEY="你的硅基流动Key"
$env:LLM_BASE_URL="https://api.siliconflow.cn/v1/"
$env:LLM_MODEL="平台中明确支持Function Calling的模型ID"

并不是所有模型都支持 Function Calling；选择模型时要检查平台的能力标记。

6. 添加你自己的论文

编辑 data/papers.json，每篇至少保留这些字段：

{
  "paper_id": "唯一且简短的ID",
  "title": "论文标题",
  "authors": ["作者"],
  "year": 2026,
  "url": "论文链接",
  "keywords": ["关键词"],
  "summary": "你核对过的摘要或笔记",
  "contribution": "主要贡献",
  "limitations": "局限"
}

第一版检索使用可读的关键词匹配，目的是理解 RAG 流程。等这个版本跑通后，再把 search_papers 换成向量检索，其他 Agent 代码无需改变。

常见问题

• 401：API Key 无效或没有设置在当前 PowerShell。
• 404：通常是 LLM_BASE_URL 或 LLM_MODEL 不正确。
• 模型回答但不调用工具：强化问题里的“请先查找本地论文”，并检查模型是否支持 Function Calling。
• 工具参数格式错误：换能力更强的模型，或缩短工具描述后重试。
• 达到调用上限：检查是否出现重复搜索，不要第一时间提高 MAX_TOOL_ROUNDS。