AgentPlatformBase 双智能体任务平台实战：基于 FastAPI 的毕业项目统一智能体平台搭建指南

AgentPlatformBase 双智能体任务平台实战基于 FastAPI 的毕业项目统一智能体平台搭建指南【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents导读AgentPlatformBase是面向 Hello-Agents 第 16 章毕业项目设计的一个轻量智能体平台位于仓库 Co-creation-projects/huailishang-AgentPlatformBase。它以 FastAPI 提供统一后端、原生 HTML/CSS/JavaScript 构建浏览器工作台并接入两个具备明确业务价值的智能体搜索员deep_research与资讯员rss_digest。读完本文你将掌握如何搭建一个平台层 智能体层分离的多智能体应用理解后台任务执行、增量去重、数据分区与自动清理的完整工程方案并能直接运行与扩展这个平台。一、平台定位与核心功能AgentPlatformBase的核心设计理念是平台只负责编排智能体负责干活。它把如何调用 LLM、如何搜索、如何生成摘要的细节下沉到独立智能体子项目中后端通过适配器Adapter与注册表Registry统一暴露能力。平台提供的核心能力包括统一智能体注册表后端通过AgentRegistry管理所有智能体注册、查询、批量执行均走同一套接口后台任务执行长耗时任务默认在后台线程中运行前端轮询任务状态不阻塞输入框避免 RSS 抓取或深度调研把交互界面卡死搜索员deep_research内置 DeepResearchAgent自动搜索互联网、规划调研子任务并生成研究报告同时保留运行产物和长期笔记资讯员rss_digest拉取 RSS 源、抽取正文、调用 LLM 生成中文摘要最终渲染为 HTML 简报数据分区所有智能体数据统一存放在data/{agent_id}/目录下便于一键清理和提交时整体忽略。二、项目结构与目录规则平台采用后端 / 前端 / 智能体 / 数据四层目录结构完整结构如下agent_platform_base/ backend/ agents/ adapters/ deep_research.py rss_digest.py base.py profiles.py registry.py memory/ tasks/ main.py config.py maintenance.py events.py models.py frontend/ index.html styles.css app.js agents/ deep_research/ README.md src/ agent.py config.py services/ rss_digest/ src/rss_digest/ config/ scripts/ main.py README.md data/ deep_research/ runs/ notes/ rss_digest/ runs/ state/ .env.example requirements.txt smoke_test.py目录规则非常明确这也是保证项目可维护、可提交的关键backend/平台后端只放 API、任务管理、注册表、适配器和平台公共逻辑frontend/单页前端工作台agents/{agent_id}/具体智能体的代码、配置和脚本data/{agent_id}/runs/可清理的运行产物data/{agent_id}/notes/长期保留的知识和笔记仅有需要的智能体才创建如 deep_research 的长期笔记data/{agent_id}/state/持久状态例如 RSS 去重数据库state/articles.json。这种可丢弃产物 / 长期知识 / 持久状态三分的数据策略直接支撑了后文要讲的清理机制runs可以放心删除notes与state必须保留。三、技术栈平台的技术选型以轻量、少依赖为原则Python 3.10FastAPI / UvicornWeb 框架与服务Pydantic数据模型校验hello-agents / OpenAI SDK / Tavily / DDGS智能体框架、LLM 与搜索后端Requests / Python 标准库 RSS 与 HTML 解析原生 HTML、CSS、JavaScript无前端框架依赖清单可查看 requirements.txt其中固定了hello-agents0.2.9并使用tavily-python与ddgs作为可切换的搜索后端。四、快速开始安装依赖并启动服务cd Co-creation-projects\huailishang-AgentPlatformBase python -m pip install -r requirements.txt python main.py启动入口 main.py 实际是调用 Uvicorn 运行backend.main:app端口默认 8016。启动后访问前端工作台http://127.0.0.1:8016/app/API 文档http://127.0.0.1:8016/docs健康检查http://127.0.0.1:8016/health服务启动时backend/main.py 会做三件事构建默认注册表、挂载前端静态目录/app、挂载 RSS 简报静态目录/rss-digests若存在。根路径/会自动重定向到/app/工作台。环境变量与代理处理平台支持通过.env文件配置 LLM 与搜索参数参考backend/config.py中的SettingsAPP_HOST、APP_PORT服务地址与端口默认127.0.0.1:8016LLM_PROVIDER、LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL、LLM_TIMEOUTLLM 配置SEARCH_API、MAX_WEB_RESEARCH_LOOPS、FETCH_FULL_PAGE、ENABLE_NOTES、PERSIST_RUNS、CLEANUP_INTERMEDIATE_FILESdeep_research 相关行为开关NOTES_WORKSPACE、RUN_WORKSPACEdeep_research 笔记与运行产物目录RSS_DIGEST_ROOT、RSS_DIGEST_DATA_ROOTRSS 智能体代码目录与数据目录。一个容易被忽视的细节是backend/config.py中的代理清理逻辑当环境中的代理变量恰好是http://127.0.0.1:9这类无效值时会自动移除避免干扰本地服务。RSS 子项目在agents/rss_digest/src/rss_digest/config.py的_apply_proxy_env中也有类似的代理处理优先读取PROXY_URL未显式配置时默认禁用系统代理。五、使用示例用指定智能体前端输入框采用提及语法指定目标智能体例如deep_research 调研 AI Agent 平台架构 rss_digest 今日简报 rss_digest 强制刷新今日简报RSS 资讯员内置了当日去重与强制刷新逻辑。如果当天已经生成了 HTML 简报普通的rss_digest 今日简报会直接返回已有简报避免重复拉取、重复消耗 LLM只有当输入包含强制重新生成刷新或force/refresh字样时才会重新运行 RSS pipeline。这个逻辑在 backend/agents/adapters/rss_digest.py 中实现_is_force_refresh对输入做小写归一化后匹配关键词_today_digest_path检查data/rss_digest/runs/digests/digest_{YYYY-MM-DD}.html是否已存在。未命中缓存时适配器会通过redirect_stdout捕获 pipeline 运行日志避免逐条 feed、逐篇文章、逐条摘要的过程日志刷爆后台只保留阶段级统计输出。六、运行机制任务模型与后台执行平台的任务生命周期通过 REST API 驱动POST /tasks POST /tasks/{task_id}/run 默认后台启动立即返回 running GET /tasks/{task_id} 前端轮询直到 completed / failed同步调试可以使用POST /tasks/{task_id}/run?backgroundfalse任务完成后artifacts.elapsed_seconds会记录总耗时RSS 和 DeepResearch 适配器还会记录更细的阶段耗时如timings.total_seconds、adapter_total_seconds便于后续做性能优化。源码级实现拆解任务数据模型定义在 backend/models.pyTaskRecord包含task_id默认uuid4().hex、title、input、agent_id、status、output、artifacts、metadata、error、created_at、updated_atTaskStatus枚举定义pending / running / completed / failed四种状态。任务管理器backend/tasks/manager.py 用内存字典 threading.Lock实现线程安全的增删查改提供create / get / list / update_status / complete / fail方法。任务执行器backend/tasks/runner.py 是核心start_background先校验任务未在运行再置为running状态并启动 daemon 线程执行_run_now_run_now中用perf_counter计时成功则调用manager.complete并写入artifacts.elapsed_seconds失败则调用manager.fail记录异常并发射task_failed事件。整个生命周期都会通过 backend/events.py 的EventLogger记录结构化事件task_started、task_completed、task_failed等可通过GET /events查询。批量执行由 backend/tasks/batch.py 的BatchRunner提供接受{agent_id: request}映射并逐个同步执行。为了避免长耗时流程在批量模式下被误触发两个适配器都实现了group_chat守卫deep_research 会提示请单独使用 deep_research 提交明确研究主题rss_digest 若已有简报则直接返回简报路径否则提示单独生成。API 一览backend/main.py 暴露的全部接口方法路径说明GET/health健康检查GET/agents智能体列表含 profilePOST/agents/{agent_id}/run直接同步运行智能体POST/tasks创建任务GET/tasks任务列表GET/tasks/{task_id}查询任务状态POST/tasks/{task_id}/run启动任务?backgroundfalse可同步POST/batch/run批量运行多个智能体GET/events查询事件日志七、智能体注册表与平台契约平台能够新增智能体只需实现适配器并注册 profile依赖两处设计平台契约基类backend/agents/base.pyBaseAgent定义统一契约run方法自动完成三件事——发射agent_started事件、调用子类实现的_run、把输入输出写入memory_store、发射agent_completed事件并返回AgentResponse。子类只需实现_run即可。注册表与配置文件backend/agents/registry.py 的AgentRegistry维护agent_id - BaseAgent的字典build_default_registry()读取 backend/agents/profiles.py 中default_profiles()定义的两个 profiledeep_research搜索员声明工具web_search / notes / summarizer系统提示词为 Coordinate research tasks and produce a report.rss_digest资讯员声明工具rss / article_extractor / translator / html_digest系统提示词为 Collect RSS updates, summarize them in Chinese, and return a daily digest.。每个AgentProfile见 backend/models.py还包含kindchat/planner/research/tool、memory_policy默认session与enabled开关。新增智能体的扩展路径就是实现BaseAgent子类 → 在default_profiles()中注册 profile → 在build_default_registry()中注册适配器。八、搜索员 deep_research调研报告的适配与产物管理搜索员由 backend/agents/adapters/deep_research.py 负责接入。它并不复制调研逻辑而是按需动态加载第 14 章的 DeepResearchAgent 源码通过_load_deep_research_types把CHAPTER14_BACKEND_PATH默认指向agents/deep_research/src会回退到code/chapter14/helloagents-deepresearch/backend/src插入sys.path并importlib导入agent.DeepResearchAgent与config.Configuration。执行流程清理过期产物计时cleanup_seconds通过Configuration.from_env(overrides...)初始化overrides 会将平台.env中的 LLM、搜索配置以及notes_workspace/run_workspace透传给第 14 章智能体调用agent.run(request.input)执行调研用redirect_stdout捕获过程日志将todo_items序列化为结构化字典统计completed / skipped / failed数量连同 Markdown 报告、timingsload / init / run / postprocess / total 各阶段耗时写入artifacts。值得注意的错误兜底若全部调研子任务都未完成且没有报告适配器会明确提示搜索后端无结果、网络 API 调用失败或任务执行阶段没有产出摘要并指引查看data/deep_research/runs目录下的task_*文件。九、资讯员 rss_digest增量抓取与中文简报资讯员适配器 backend/agents/adapters/rss_digest.py 同样以动态加载方式调用 agents/rss_digest 子项目的 pipeline。运行路径检查rss_digest项目路径是否存在不存在则返回ready: Falsedry_run上下文仅做接线验证当日简报已存在且非强制刷新 → 直接返回现有简报与最近文章列表skipped: true否则调用pipeline.run_pipeline(root_dir, data_root)全量执行并把discovered / extracted / summarized / digest_article_count等统计写入run_stats。RSS 默认配置RSS pipeline 的所有关键参数都可以通过环境变量覆盖默认值来自 agents/rss_digest/src/rss_digest/config.py 的build_configRSS_SOURCE_LIMIT10 # 每次最多处理的 RSS 源数量 RSS_ENTRIES_PER_SOURCE5 # 每个源最多读取的条目数 RSS_MAX_NEW_ARTICLES_PER_RUN50 # 每轮最多进入正文抽取的新文章数 RSS_MAX_SUMMARY_ARTICLES_PER_RUN10 # 每轮最多生成 LLM 摘要的文章数 RSS_AI_MAX_CONCURRENCY2 # LLM 摘要的最大并发数 RSS_RELEVANCE_THRESHOLD65 # 文章相关性评分阈值0-100配置时会 clamp 到该范围 RSS_MAX_DIGEST_ARTICLES12 # 单份简报最多收录文章数配置加载时还会做防御性处理rss_fetch_concurrency、rss_source_limit、rss_entries_per_source等均max(1, ...)保证不小于 1rss_relevance_threshold被限制在 0–100 之间。其它可选项还包括TRANSLATION_MODEL_ID、FETCH_FULL_TRANSLATION、RSS_FETCH_TIMEOUT_SECONDS、LLM_TIMEOUT、RSS_FETCH_CONCURRENCY、RSS_AI_BATCH_SIZE、RESUMMARIZE_EXISTING等。RSS 源列表通过config/sources.json加载去重状态持久化在state/articles.jsonSQLite 风格的 JSON 键值数据库见db.py。RSS 后台日志只保留阶段级进度和最终统计discovered/extracted/summarized/digest_articles/seconds逐 feed、逐篇、逐条摘要的过程日志不再打印到后台避免刷屏。十、清理策略惰性触发、按目录区分保留期清理逻辑集中在 backend/maintenance.py由长任务调用时惰性触发_should_run通过内存时间戳限制清理频率间隔取MAINTENANCE_CLEANUP_INTERVAL_HOURS与 1 小时的较大值。相关配置RESEARCH_RUN_RETENTION_DAYS7删除超过 7 天的搜索员运行产物data/deep_research/runs/整目录删除RSS_DIGEST_RETENTION_DAYS7删除超过 7 天的 RSS HTML 简报digests/digest_*.htmlRSS_CACHE_RETENTION_DAYS7删除超过 7 天的 RSS 原始 HTML、正文抽取和翻译缓存runs/raw、runs/extracted、runs/translated不自动删除data/deep_research/notes长期笔记不自动删除data/rss_digest/state/articles.json文章去重状态。清理实现中还有两个严谨的安全细节_is_child_of校验目标路径确实位于待清理根目录之下防止路径穿越误删_directory_size在删除目录前先统计占用字节数便于返回deleted_bytes统计。全局开关为MAINTENANCE_CLEANUP_ENABLED默认开启。十一、自检smoke_test 一键验证项目提供端到端自检脚本cd Co-creation-projects\huailishang-AgentPlatformBase python smoke_test.py通过时输出chapter16 platform smoke test passeds smoke_test.py 使用 FastAPI 自带的TestClient覆盖以下链路/health健康检查/app/前端可访问且包含智能体平台字样/agents返回 2 个智能体且必须包含deep_research、rss_digest同时断言planner不在其中创建deep_research任务并同步运行dry_run元数据断言状态为completed/batch/run批量模式返回两个 agent 的响应验证group_chat守卫下仍能正常响应/events事件查询可用。十二、提交说明与项目亮点按第 16 章要求最终提交版整理在Co-creation-projects/huailishang-AgentPlatformBase/且不包含.env、运行数据、缓存、视频、大模型文件或其它大文件确保项目体积满足 5MB 要求README 记录的提交目录体积约 143KB。项目的主要设计亮点平台层与智能体层分离新增智能体只需实现适配器并注册 profile无需改动平台核心长耗时任务后台执行RSS 抓取或 DeepResearch 调研不会阻塞前端交互RSS 轻量增量策略默认每次最多处理 10 个源、50 篇正文、10 篇摘要避免单次调用过慢数据统一归档运行产物和长期知识统一放入data/{agent_id}/提交时可整体忽略。效果评估方面smoke_test.py覆盖健康检查、智能体列表、dry run、批量保护和任务执行基本链路RSS 后台日志已收敛为阶段级统计避免逐篇文章刷屏。十三、后续演进方向README 中列出的后续计划包括为deep_research增加更完整的前端报告查看页为 RSS 简报增加前端筛选、收藏和历史归档入口将任务事件持久化到 SQLite支持服务重启后的任务历史查询。从源码结构看事件系统目前为内存实现backend/events.py任务管理同样是内存字典backend/tasks/manager.py因此持久化事件与任务历史是当前架构下最自然的增强点而在 backend/agents/profiles.py 中追加第三个 profile、在注册表中注册对应的适配器则是扩展新智能体的标准路径。结语AgentPlatformBase是一个结构清晰、可直接运行的轻量多智能体平台范例它用约十个后端模块就完成了统一注册表、后台任务、双智能体接入、增量抓取、自动清理、端到端自检的完整闭环非常适合作为智能体平台类毕业项目的参考骨架。读者可以在此基础上按需扩展适配器、丰富前端报告页或替换为 SQLite 持久化逐步演进为自己想要的平台形态。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考