基于 HelloAgents 与 FastAPI 构建多智能体健康档案助手：体检报告解读、饮食推荐与 Reflect 反馈闭环

基于 HelloAgents 与 FastAPI 构建多智能体健康档案助手体检报告解读、饮食推荐与 Reflect 反馈闭环【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读本文以开源仓库 Co-creation-projects/Shawnxyxy-HealthRecordAgent以下简称 HealthRecordAgent为核心系统讲解如何基于HelloAgentsHelloAgentsLLM与FastAPI构建一个可落地的多智能体健康管理应用。该应用覆盖三大能力体检报告的多 Agent 流水线解读、自然语言饮食日志驱动的多阶段饮食推荐以及推荐 → 执行 → Reflect 反馈 → 记忆沉淀的闭环。读完本文你将掌握 Plan-and-Execute 编排、Pydantic 约束的结构化输出与失败降级、SQLite 长期记忆与 Milvus 语义检索含自动回退的完整实现思路并能将仓库代码原样跑通。声明本项目输出仅供健康信息与流程演示不能替代执业医师的诊断或处方。一、功能概览模块说明档案分析文本或 PDF 体检报告 → 多 Agent 流水线规划 → 指标 → 风险 → 建议 → 报告异步任务可轮询状态饮食助手自然语言今日饮食日志→ LLM 解析与营养汇总 → 营养师 / 教练 / 习惯 多阶段结构化输出结合历史记忆与 Reflect 反馈长期记忆SQLite 存运行记录与反馈可选 Milvus 向量索引 Hybrid 检索失败回退 SQL 列表可观测pipeline_trace、errors/degraded、rag_debug报告/饮食 run 的 observability 接口与饮食replay前端静态页 Tab档案分析 | 饮食助手 | 历史类 Apple Health 信息层级开发者模式控制技术细节展示饮食Reflect反馈闭环二、系统架构与核心设计HealthRecordAgent 的整体架构要点如下与 README 中架构要点一节对应编排健康分析为Plan-and-Execute风格PlannerAgent后多 Specialist 串行饮食为多阶段流水线食物解析 → 营养师 → 教练 → 习惯各阶段Pydantic校验与失败降级。工具饮食场景内Tool Use如营养查询、活动/睡眠摘要 Mock可替换真实数据源。LLM通过hello_agents.HelloAgentsLLM调用兼容 OpenAI 的 APIAgent 基类与业务流水线在本仓库 backend/agents、backend/service 中实现。记忆与 RAG历史报告、饮食与反馈等落在SQLite需要语义召回时对记忆做向量索引Milvus按用户与场景检索相关片段并注入 Agent。Milvus 未开或不可用时自动回退为基于 SQL 的近期记忆列表。2.1 后端入口与路由挂载后端是一个标准的 FastAPI 应用入口为 backend/api/main.pyasynccontextmanager async def lifespan(_app: FastAPI): init_db() # 启动时初始化 SQLite 表结构 yield app FastAPI(titleHealthRecordAgent API, version1.0.0, lifespanlifespan) app.include_router(health_router, prefix/api) app.include_router(diet_router, prefix/api) app.add_middleware(CORSMiddleware, allow_origins[*], ...) # 开发阶段允许全部要点所有路由统一挂在/api前缀下lifespan中调用init_db()位于 backend/memory/store.py幂等创建users、report_runs、user_profiles、diet_runs、diet_reflect等表CORS 在开发阶段放开全部来源。2.2 健康分析Plan-and-Execute 风格流水线健康分析是典型的先规划、后执行结构。基类 backend/agents/base.py 定义了BaseAgent抽象类提供统一的thinkLLM 调用、call_tool工具执行、trace调试追踪、set_state状态上报机制并维护一个全局任务状态字典TASKSTASKS[task_id] { state: running, agents: { PlannerAgent: pending, HealthIndicatorAgent: pending, RiskAssessmentAgent: pending, AdviceAgent: pending, ReportAgent: pending}, report: None, }五个 Agent 各自继承BaseAgent实现run()PlannerAgent只关心goal用 Plan-And-Solve 提示词将目标拆解为36 个可执行步骤并强制输出 JSON 格式的plan解析失败时回退为FallbackAgent占位保证流程不断。HealthIndicatorAgent从报告文本中提取关键健康指标逐项输出value / status / risk_level / analysis不跨指标做综合结论。RiskAssessmentAgent基于指标结果综合判断overall_risk_levellow/medium/high、风险因素≤5 条、潜在健康方向与置信度confidence。AdviceAgent结合风险评估结果与 RAG 召回的历史记忆生成不涉及诊断、偏向生活方式与就医提示的具体建议。ReportAgent汇总上述所有阶段输出为最终报告。流水线的串联逻辑在 backend/service/health_analysis.py 的HealthAnalysisService.run()中Planner → HealthIndicator → RiskAssessment →RAG 检索→ Advice → Report每一步执行前后都通过update_agent_state更新全局任务状态供前端轮询报告写入 SQLite 与向量索引均为 best-effort失败不影响主流程返回。2.3 饮食助手多阶段流水线与结构化输出饮食推荐是另一条完全独立的流水线核心实现位于 backend/service/diet_pipeline.py 的DietMultiAgentPipeline。它依次执行四个阶段FoodParse食物解析把自然语言饮食日志解析为items[]餐次、食物名、份量、置信度与nutrition_summary蛋白/碳水/脂肪/膳食纤维/钠/热量。Nutritionist营养师计算蛋白质缺口protein_gap_g输出检索方向suggested_lookup_queries与关注点candidate_focus。Coach运动恢复结合活动/睡眠摘要输出训练恢复建议、进食时间约束等。Habit习惯养成对齐 Reflect 记忆产出可直接执行的meal_plan含每项食物、份量、估算蛋白与理由。每个阶段都走_run_validated_stage()LLM 输出先做 JSON 提取支持代码块剥离与首尾花括号截取再用 Pydantic v2 模型校验schema 定义在 backend/service/diet_schemas.pySCHEMA_VERSION 2全部extraforbid单阶段最多尝试2 次MAX_STAGE_ATTEMPTS单次超时上限95 秒DIET_STAGE_TIMEOUT_SEC校验失败会携带上一轮的报错信息做修复提示重试。for attempt in range(MAX_STAGE_ATTEMPTS): # 2 次 ... obj _extract_json_object(raw) # 剥离 markdown、截取 JSON validated model_cls.model_validate(obj) # Pydantic 校验 ... repair_hint err_text # 把错误喂回给模型要求重出若 2 次尝试全部失败则按阶段触发规则降级_fallback_food_parse/_fallback_nutritionist/_fallback_coach/_fallback_habit例如营养师阶段直接按目标蛋白增肌 130g、减脂 95g、维持 105g见_goal_target_protein与已解析蛋白做差估算缺口Habit 阶段给出希腊酸奶 水煮蛋 豆浆的安全兜底菜单。所有降级都会写入errors与degraded标记同时保留每阶段的attempts记录到pipeline_trace做到宁可降级也不让接口 500。统一的错误码定义在 backend/service/diet_errors.py错误码含义LLM_PARSE_ERROR无法从模型输出解析出合法 JSONVALIDATION_FAILED输出未通过 Pydantic schema 校验LLM_TIMEOUTLLM 调用超时TOOL_ERROR工具调用失败STAGE_ABORTED上游模型网关 5xx / SDK 异常等阶段中止DEGRADED_FALLBACK阶段失败后已使用规则降级输出2.4 工具机制Tool Use饮食场景内置了两个 Mock 工具实现在 backend/tools/diet_tools.pynutrition_lookup(query)按关键词支持中文逗号/英文逗号分隔在 mock 营养表中查询便利店/外卖常见食物的蛋白质、份量单位与热量如即食鸡胸肉 100g ≈ 24g 蛋白、120 kcal。activity_sleep_summary(user_id)返回今日步数、睡眠时长/质量、晚间是否训练等摘要source: mock_wearable。流水线在进入 LLM 阶段前会先_prefetch_tools()预取这两项数据并注入各阶段提示词营养师阶段还会按其suggested_lookup_queries追加一次营养查询nutrition_extra。工具的调度统一走dispatch_tool(name, action_input, user_id)未来替换真实数据源时只需替换这些函数实现。2.5 LLM 适配层所有 Agent 共享一个 LLM 适配器 backend/core/llm_adapter.py内部通过hello_agents.HelloAgentsLLM初始化兼容 OpenAI 的客户端并封装了invoke/ainvoke与响应文本提取。配置项来自 backend/core/config.pyLLMConfig: model_name: OPENAI_MODEL_ID # 默认 qwen-turbo api_key: OPENAI_API_KEY base_url: OPENAI_BASE_URL # 兼容网关必填 temperature: 0.7 max_tokens: 2048 timeout: 60三、长期记忆与语义检索SQLite Milvus3.1 SQLite 记忆库backend/memory/store.py 使用标准库sqlite3实现同步持久化在异步路由中通过asyncio.to_thread调用。核心表包括users用户主表report_runs体检分析履历含summary_text、report_json、agent_trace_json后两列用于可观测性user_profiles用户画像diet_runs饮食推荐 run含input_json、steps_trace_json、output_json、replayed_from_run_id溯源列diet_reflect执行反馈followed、reason_code、reason_detail。数据库默认路径为项目根目录下的data/health_memory.db可通过环境变量HEALTH_MEMORY_DB_PATH覆盖见get_db_path()。3.2 Milvus 向量检索与自动回退RAG 检索的统一入口是 backend/rag/retriever.py 的retrieve(user_id, query_context)if cfg.enabled: # RAG_ENABLEDtrue 时尝试 Milvus vec embed_texts([query_text])[0] chunks search(user_iduser_id, query_vectorvec, top_kk) if chunks: mode milvus if not chunks: # 无结果/未启用 → SQL 回退 rows list_user_memory_chunks_sql(user_iduser_id, ...) mode sql_fallback返回结构包含chunks、summary拼装成可直接注入提示词的文本与debugrag_enabled、mode、retrieved_count、retrieval_ms、source_breakdown等这正是前端与开发者排查当前走的是 Milvus 还是回退的依据对应 README 常见问题中的rag_debug.mode。底层细节向量化封装在 backend/rag/embedding.py默认走 OpenAI 兼容的embeddings.create可与 LLM 共用 base_url或单独配置外部嵌入失败时回退为 SHA-256 派生的哈希向量默认 64 维保证流程可运行但召回质量有限。Milvus 存储层在 backend/rag/milvus_store.py集合health_memory_chunks采用VARCHAR主键chunk_id、FLOAT_VECTOR向量字段索引使用IP内积AUTOINDEX检索时按user_id ...表达式过滤支持source_type多值过滤。索引回填逻辑在 backend/rag/indexers.pyindex_report_run报告摘要、index_diet_run饮食菜单 执行提示、index_reflect_event反馈运行结束后 best-effort 写入向量库。需要为历史数据批量建索引时可运行仓库内脚本 backend/scripts/reindex_milvus.pycd Co-creation-projects/Shawnxyxy-HealthRecordAgent/backend .venv/bin/python scripts/reindex_milvus.py3.3 Reflect 反馈闭环反馈接口将用户是否按推荐执行及原因写入diet_reflect表下一次推荐时流水线通过format_reflect_memory_for_prompt(user_id, limit8)把最近 8 条反馈拼入 Nutritionist 与 Habit 阶段的提示词实现上次没吃到的 → 这次换更易执行的方案的闭环调整。反馈原因码在 backend/api/routes/diet.py 中定义为枚举cant_buy买不到、too_late太晚、dont_want不想吃、executed_ok已执行、other。四、环境准备与快速开始4.1 环境要求Python3.10建议使用虚拟环境可选本地MilvusDocker与可用的Embedding接口用于开启 RAG4.2 安装依赖进入项目根目录HealthRecordAgent目录即本仓库下的Co-creation-projects/Shawnxyxy-HealthRecordAgentpython3 -m venv backend/.venv source backend/.venv/bin/activate # Windows: backend\.venv\Scripts\activate pip install -r requirements.txt依赖清单见 requirements.txtWeb 侧为fastapi、uvicorn、sse-starletteAgent/LLM 侧为hello-agents0.2.8、openaiPDF 解析为pdfplumber、pypdfRAG 侧为pymilvus。4.3 配置环境变量在backend/下创建.envpython-dotenv随进程工作目录加载因此请在backend目录下启动 Uvicorncd backend cp .env.example .env.env.examplebackend/.env.example的完整变量说明如下变量默认值说明OPENAI_API_KEY空必填OpenAI 兼容接口密钥OPENAI_BASE_URL空兼容网关地址使用网关时必填OPENAI_MODEL_IDqwen-turbo模型名RAG_ENABLEDfalse设为true开启语义记忆检索RAG_TOP_K5召回条数MILVUS_URIhttp://127.0.0.1:19530Milvus 地址MILVUS_TOKEN空Milvus 鉴权 token按需MILVUS_COLLECTIONhealth_memory_chunks集合名EMBEDDING_API_KEY空嵌入接口密钥可与 LLM 共用EMBEDDING_BASE_URL空嵌入接口地址EMBEDDING_MODELtext-embedding-v1嵌入模型名HEALTH_MEMORY_DB_PATHdata/health_memory.dbSQLite 路径覆盖4.4 启动后端cd backend source .venv/bin/activate # 若尚未激活虚拟环境 python -m uvicorn api.main:app --host 127.0.0.1 --port 8000 --reloadSwaggerhttp://127.0.0.1:8000/docs路由前缀/api例如POST /api/health/analysis4.5 启动前端静态服务另开终端cd frontend python3 -m http.server 8080 --bind 127.0.0.1浏览器打开http://127.0.0.1:8080/。前端默认请求http://127.0.0.1:8000见 frontend/app.js 顶部API_BASE请与后端端口保持一致前端页面支持档案分析 / 饮食助手 / 历史三个 Tab并可通过开发者模式开关切换展示中文步骤名与PlannerAgent等英文技术名。五、API 一览5.1 健康分析方法路径说明POST/api/health/analysis文本报告分析返回task_idPOST/api/health/analysis/pdf上传 PDF 分析GET/api/health/task_status/{task_id}任务与 Agent 状态GET/api/health/users/{user_id}/report_history用户历史报告GET/api/health/report_runs/{task_id}单次运行详情GET/api/health/report_runs/{task_id}/observability可观测性摘要文本分析的请求体见 backend/api/routes/health.py 的HealthRequest为{report_text: ..., user_id: ...}其中user_id经字段校验去空。分析是异步任务接口立即返回task_id由asyncio.create_task后台执行前端轮询/health/task_status/{task_id}获取各 Agent 的pending / running / completed状态。PDF 接口使用pdfplumber逐页抽取文本后再进入同一流水线。仓库自带一份示例报告 data/sample_reports/report.txt 可直接用于测试。5.2 饮食方法路径说明POST/api/diet/recommend饮食推荐context.today_food_log_text等POST/api/diet/reflect是否按推荐执行及原因闭环记忆GET/api/diet/users/{user_id}/runs饮食运行历史GET/api/diet/users/{user_id}/reflect_history反馈历史GET/api/diet/runs/{run_id}单次饮食 runGET/api/diet/runs/{run_id}/observability可观测性视图POST/api/diet/runs/{run_id}/replay同输入重跑新run_id推荐请求体由DietRecommendRequest约束context字段见 backend/api/routes/diet.py 的DietContext为{ user_id: test-user-a, context: { today_food_log_text: 中午吃了麻辣香锅晚上一盒牛奶, goal: muscle_gain, channels: [convenience_store, delivery], activity_context: 晚上力量训练 60 分钟, free_notes: 只能去便利店 } }goal取值限定muscle_gain/fat_loss/maintainchannels为可购买渠道标签默认[convenience_store, delivery]today_food_log_text必填48000 字符。返回体包含run_id、degraded、errors、stages各阶段ok/fallback_used/output、meal_plan、food_parse、nutrition_summary、react_trace流水线追踪、reflect_memory_used、retrieved_memory与rag_debug一次请求即可看到完整的多阶段证据链。Reflect 请求体为{user_id, diet_run_id, followed, reason_code, reason_detail}若followedtrue且未传reason_code后端自动置为executed_ok。replay接口用历史 run 落库的input重跑流水线生成新run_id并通过replayed_from_run_id溯源实现见 backend/service/diet_recommend_service.py 的replay_diet_run。六、可观测性设计项目把能看见 Agent 内部发生了什么作为一等公民体现在三个层面健康分析每个 Agent 通过BaseAgent.trace()记录LLM CALL / LLM RESPONSE / STATE CHANGE等事件backend/agents/base.pyHealthAnalysisService._bundle_agent_traces()在运行结束后把每个 Agent 最近 80 条 trace 落库到report_runs.agent_trace_jsonGET /api/health/report_runs/{task_id}/observability默认返回各 Agent 的event_count与最近事件标题摘要include_raw_tracetrue时才返回完整 trace避免响应过大。饮食流水线每阶段写入pipeline_trace含phase、fallback_used、attempts、outputGET /api/diet/runs/{run_id}/observability由 backend/service/observability_views.py 构建trace_timeline工具调用次数、LLM 尝试次数、末次是否成功与rag_debug快照并附replay操作说明。错误面饮食流水线的errors[]统一携带stage / code / message / attempt / detail配合degraded标志可精确统计每个阶段的失败模式对应 README 的errors/degraded可观测能力。七、常见问题与排查前端能开但接口报错确认后端已启动且端口为8000或与frontend/app.js里API_BASE一致。RAG 不生效检查RAG_ENABLED、Milvus 进程与嵌入 API响应中的rag_debug.mode可帮助判断当前是milvus还是回退sql_fallback。数据库文件位置默认HealthRecordAgent/data/health_memory.db可通过环境变量HEALTH_MEMORY_DB_PATH覆盖。LLM 调用失败确认backend/.env中OPENAI_API_KEY/OPENAI_BASE_URL正确且 Uvicorn 在backend目录下启动python-dotenv按工作目录加载模型名可通过OPENAI_MODEL_ID切换。八、总结HealthRecordAgent 以HelloAgentsLLM为底座、FastAPI 为服务框架示范了多智能体健康应用从编排、结构化输出、失败降级到记忆闭环的完整工程化路径健康分析走规划 → 指标 → 风险 → 建议 → 报告的 Plan-and-Execute 流水线饮食推荐走解析 → 营养师 → 教练 → 习惯的多阶段 Pydantic 约束流水线二者共享 SQLite 长期记忆并通过 Milvus 语义检索与 Reflect 反馈形成历史经验指导下一次推荐的正循环。其 Pydantic 校验 重试 规则降级、可观测 trace、replay 溯源等设计尤其适合作为学习多智能体工程落地与LLM 输出不可控应对策略的参考案例。需要再次强调的是该项目为健康信息与流程演示用途输出不能替代执业医师的诊断或处方。本文基于仓库 Co-creation-projects/Shawnxyxy-HealthRecordAgent 的 README、backend 源码与 frontend 前端代码整理撰写所有命令与配置以仓库当前内容为准。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考