Demo-Agent

《人工智能基础》大作业，选题一：AI Agent 框架搭建。

Demo-Agent 是一个从零实现的轻量 ReAct Agent。它接收自然语言任务，由 LLM 自主决定是否调用工具，把工具结果写回上下文，并继续多轮“思考-行动”循环，直到生成最终回答。项目不使用 LangChain、LlamaIndex 等高层 Agent 框架。

功能

• ReAct JSON 提示词与解析执行循环
• 异步后端：AsyncOpenAI + FastAPI
• 会话级上下文管理和并发保护
• 内置工具：
  • calculator：安全数学计算
  • wiki_search：维基百科检索
  • read_file / write_file：工作区内本地文件读写
• 本地桌面式前端：pywebview + HTML/CSS/JS，Material 风格，低圆角、无液态玻璃
• 标准库单元测试，可在没有真实 API key 的情况下验证核心逻辑

快速开始

conda env create -f environment.yml
conda activate demo-agent
pip install -e .
copy .env.example .env

在 .env 中填写：

OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=
OPENAI_MODEL=gpt-4o-mini

启动桌面应用：

python main.py

只启动 Web 服务：

python main.py --web --port 8000

然后访问 http://127.0.0.1:8000。

项目结构

.
├── client/                 # 本地前端界面
│   ├── app.js
│   ├── index.html
│   └── styles.css
├── docs/
│   └── REPORT.md           # 实验报告与 review 记录
├── server/
│   ├── agent.py            # 异步 ReAct Agent
│   ├── app.py              # FastAPI API 与静态前端挂载
│   ├── defs.py             # 系统提示词与 observation 模板
│   ├── openai/connector.py # OpenAI 兼容异步连接器
│   └── tools/              # 内置工具
├── tests/                  # 标准库 unittest 测试
├── environment.yml         # conda 环境定义
├── main.py                 # 入口
├── run.py                  # 服务与 pywebview 启动器
└── pyproject.toml

API

• GET /api/health：健康检查
• GET /api/tools：工具列表
• GET /api/sessions：会话列表
• POST /api/sessions：新建会话
• GET /api/sessions/{session_id}/messages：会话历史
• DELETE /api/sessions/{session_id}：删除会话
• POST /api/chat：发送消息

POST /api/chat 示例：

{
  "session_id": "optional-session-id",
  "message": "查一下爱因斯坦的出生年份，然后计算他活了多少岁"
}

测试

python -m unittest discover -s tests

核心 Agent 和工具测试不会真实调用 OpenAI API。

示例任务

查一下爱因斯坦的出生年份，然后算一下如果他活到 1955 年是多少岁

期望过程：

1. Agent 调用 wiki_search 查询出生年份。
2. Agent 调用 calculator 计算 1955 - 1879。
3. Agent 整理最终答案返回用户。

交付说明

本项目满足作业 README 要求：

• 至少 3 个工具：计算器、维基百科、本地文件读写
• 支持多步工具调用任务
• 维护对话历史
• 使用 Python + OpenAI 兼容 API
• 提供 Web/桌面式前端
• 异步 Agent 调用设计