这是《动手智能体构建》第 4 章的配套教学项目。系统继承前两章的 ChatBot 和 RAG 数字员工，并新增能够制定计划、调用工具、观察结果和积累长期记忆的 ReActAgent。
请使用 Python 3.10 或以上版本。
pip install -r requirements.txt
uvicorn app.main:app --reload浏览器访问 http://127.0.0.1:8000。
从第 3 章导入数据可运行 python scripts/migrate_chapter3_db.py。旧版第 4 章数据库先运行 python scripts/migrate_tool_bindings.py 迁移工具绑定，再运行 python scripts/migrate_memories.py，将旧日级记忆聚合为日记并保留核心记忆。
左侧包含六个功能页。
- 对话：选择已发布的 ChatBot、RAG 或 ReActAgent 完成任务。
- 知识库：管理资料、分块和检索调试。
- 工具管理：查看预设工具，创建自定义 HTTP 工具。
- 记忆管理：分页查看日记和核心记忆，手工修订或整理记忆。
- 模型配置：配置支持 OpenAI 兼容接口的对话模型。
- 数字员工：配置并发布不同类型的数字员工。
进入“模型配置”，填写 base_url、模型名和 API Key。ReActAgent 使用原生 Tool Calling，因此所选模型必须支持 OpenAI 兼容的 tools 和 tool_calls。
知识库向量检索使用 .env 中的 embedding 配置：
EMBEDDING_BASE_URL=https://your-compatible-endpoint
EMBEDDING_MODEL_NAME=your-embedding-model
EMBEDDING_API_KEY=your-api-key
EMBEDDING_DIMENSIONS=没有 embedding 时，知识检索和记忆检索都可以退化为关键词检索。
核心记忆默认在每天凌晨 2 点自动整理。应用启动后也会补跑一次，已经整理且没有再次更新的日记会自动跳过。可通过 .env 调整或关闭：
MEMORY_DREAM_ENABLED=true
MEMORY_DREAM_HOUR=2进入“数字员工”，编辑预置的“保险业务助手”。管理员代表使用系统的保险业务人员，客户是保险需求主体，两者不应混为一谈。
- 选择已配置的对话模型。
- 确认类型为 ReActAgent。
- 在工具列表中按需添加
knowledge_search，并在弹窗中选择保险知识标签和检索参数。 - 保留默认绑定的
calculator和memory_search。 - 最大工具调用轮数先使用默认值 24。一般任务不需要调大，复杂教学实验可在 1 至 100 之间调整。
- 按需开启“任务完成后更新日记”。该开关控制更新当天日记，
memory_search控制使用已有记忆，两者互不影响。 - 保存并发布。
plan 是可选工具。遇到包含多个相互依赖步骤或需要多类工具协作的复杂任务时，可以绑定它。该工具复用当前 Agent 的模型，将完整任务拆解为包含具体动作、建议工具和预期结果的执行计划。
进入“对话”新建会话，可以测试：
客户 C001 希望为一只 3 岁母猫购买为期 8 个月的短期宠物医疗险。
请检索可参考的保障、等待期和理赔资料，资料不足时明确说明，
再按给定的教学假设完成保费估算并形成产品设计草案。
回答上方会出现折叠的执行轨迹，按思考、执行和观察区分模型文本、工具调用及工具结果。知识检索命中的片段仍会显示在“引用资料”中。
工具页中的 plan、calculator、knowledge_search 和 memory_search 是只读预设工具。
创建 HTTP 工具时需要填写：
- 工具名和清晰的能力说明；
- 参数 JSON Schema；
- GET 或 POST；
- HTTP 或 HTTPS 地址；
- 可选静态请求头。
GET 参数会进入查询字符串，POST 参数会作为 JSON 请求体发送。请求超时为 10 秒，不跟随重定向，最多保留 16 KB 响应。
请求头和模型 API Key 都会明文保存在 SQLite 中。不要在共享环境或代码仓库中保存真实密钥。
先在 ReActAgent 对话中补充主体明确的客户需求和业务人员工作要求，例如：
客户 C001 的投保对象是 1 只 3 岁母猫，希望保障 8 个月左右。
我作为保险业务人员，希望产品草案先说明适用对象和保障范围，
再列出保费假设与风险提示。
任务完成后进入“记忆管理”，应能在“日记”页看到当天的全局日记和当前 ReActAgent 日记。每次成功任务都会在响应结束后异步更新同一天的两份 Markdown 日记。日记更新失败不会影响正常回答，可以查看后端日志定位模型返回格式。
新建会话后，可以询问：
客户 C001 再次咨询之前的宠物保险方案。
请说明已知需求，并列出下一步需要核实的产品信息。
Agent 应在需要时调用 memory_search，检索全局及当前数字员工可见的日记和核心记忆。
系统每天会自动读取尚未整理的日记增量，结合已有核心记忆进行合并、更新或删除。也可以切换到“核心记忆”页，选择全局或指定数字员工后手工整理。日记本身不区分事实和经验，核心记忆仍分为事实信息与任务经验，并尽量维持少量稳定条目。
python -m pytest -q测试不调用真实模型和外部 API，使用独立临时 SQLite 数据库和模拟响应。
- 原有 ChatBot 和 RAG 数字员工仍可正常对话。
- ReActAgent 能调用
plan、knowledge_search和calculator。 - 非法计算表达式或 HTTP 失败能作为观察返回，Agent 不会伪造成功。
- 执行轨迹和引用资料刷新后仍然存在。
- 同一天的连续任务只更新一份全局日记和一份当前 Agent 日记。
- 手工整理能从日记增量生成或更新带名称、类别的核心记忆。
- 每日自动整理只处理尚未整理或整理后再次更新的日记。
- 自定义 HTTP 工具可创建、绑定和调用。
本项目没有账号、权限审批、外部任务队列、MCP、技能系统和生产级安全防护。每日记忆整理使用单进程内定时任务，适合本地教学运行。它的重点是让学生看清 ReAct 循环、工具协议和记忆生命周期，而不是构建可直接上线的通用 Agent 平台。