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.10+
• FastAPI / Uvicorn（Web 框架与服务）
• Pydantic（数据模型校验）
• hello-agents / OpenAI SDK / Tavily / DDGS（智能体框架、LLM 与搜索后端）
• Requests / Python 标准库 RSS 与 HTML 解析
• 原生 HTML、CSS、JavaScript（无前端框架）

依赖清单可查看 requirements.txt，其中固定了hello-agents==0.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中的Settings）：

• APP_HOST、APP_PORT：服务地址与端口（默认127.0.0.1:8016）；
• LLM_PROVIDER、LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL、LLM_TIMEOUT：LLM 配置；
• SEARCH_API、MAX_WEB_RESEARCH_LOOPS、FETCH_FULL_PAGE、ENABLE_NOTES、PERSIST_RUNS、CLEANUP_INTERMEDIATE_FILES：deep_research 相关行为开关；
• NOTES_WORKSPACE、RUN_WORKSPACE：deep_research 笔记与运行产物目录；
• RSS_DIGEST_ROOT、RSS_DIGEST_DATA_ROOT：RSS 智能体代码目录与数据目录。

一个容易被忽视的细节是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?background=false

任务完成后，artifacts.elapsed_seconds会记录总耗时；RSS 和 DeepResearch 适配器还会记录更细的阶段耗时（如timings.total_seconds、adapter_total_seconds），便于后续做性能优化。

源码级实现拆解

任务数据模型定义在 backend/models.py：

• TaskRecord包含task_id（默认uuid4().hex）、title、input、agent_id、status、output、artifacts、metadata、error、created_at、updated_at；
• TaskStatus枚举定义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 暴露的全部接口：

七、智能体注册表与平台契约

平台能够"新增智能体只需实现适配器并注册 profile"，依赖两处设计：

1. 平台契约基类backend/agents/base.py：BaseAgent定义统一契约，run方法自动完成三件事——发射agent_started事件、调用子类实现的_run、把输入输出写入memory_store、发射agent_completed事件并返回AgentResponse。子类只需实现_run即可。

2. 注册表与配置文件：backend/agents/registry.py 的AgentRegistry维护agent_id -> BaseAgent的字典；build_default_registry()读取 backend/agents/profiles.py 中default_profiles()定义的两个 profile：

   • deep_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）还包含kind（chat/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。

执行流程：

1. 清理过期产物（计时cleanup_seconds）；
2. 通过Configuration.from_env(overrides=...)初始化，overrides 会将平台.env中的 LLM、搜索配置以及notes_workspace/run_workspace透传给第 14 章智能体；
3. 调用agent.run(request.input)执行调研，用redirect_stdout捕获过程日志；
4. 将todo_items序列化为结构化字典，统计completed / skipped / failed数量，连同 Markdown 报告、timings（load / 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: False；
• dry_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_config）：

RSS_SOURCE_LIMIT=10 # 每次最多处理的 RSS 源数量 RSS_ENTRIES_PER_SOURCE=5 # 每个源最多读取的条目数 RSS_MAX_NEW_ARTICLES_PER_RUN=50 # 每轮最多进入正文抽取的新文章数 RSS_MAX_SUMMARY_ARTICLES_PER_RUN=10 # 每轮最多生成 LLM 摘要的文章数 RSS_AI_MAX_CONCURRENCY=2 # LLM 摘要的最大并发数 RSS_RELEVANCE_THRESHOLD=65 # 文章相关性评分阈值（0-100，配置时会 clamp 到该范围） RSS_MAX_DIGEST_ARTICLES=12 # 单份简报最多收录文章数

配置加载时还会做防御性处理：rss_fetch_concurrency、rss_source_limit、rss_entries_per_source等均max(1, ...)保证不小于 1，rss_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.json（SQLite 风格的 JSON 键值数据库，见db.py）。

RSS 后台日志只保留阶段级进度和最终统计（discovered/extracted/summarized/digest_articles/seconds），逐 feed、逐篇、逐条摘要的过程日志不再打印到后台，避免刷屏。

十、清理策略：惰性触发、按目录区分保留期

清理逻辑集中在 backend/maintenance.py，由长任务调用时惰性触发（_should_run通过内存时间戳限制清理频率，间隔取MAINTENANCE_CLEANUP_INTERVAL_HOURS与 1 小时的较大值）。相关配置：

• RESEARCH_RUN_RETENTION_DAYS=7：删除超过 7 天的搜索员运行产物（data/deep_research/runs/整目录删除）；
• RSS_DIGEST_RETENTION_DAYS=7：删除超过 7 天的 RSS HTML 简报（digests/digest_*.html）；
• RSS_CACHE_RETENTION_DAYS=7：删除超过 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 passed

s smoke_test.py 使用 FastAPI 自带的TestClient覆盖以下链路：

1. /health健康检查；
2. /app/前端可访问且包含"智能体平台"字样；
3. /agents返回 2 个智能体，且必须包含deep_research、rss_digest，同时断言planner不在其中；
4. 创建deep_research任务并同步运行（dry_run元数据），断言状态为completed；
5. /batch/run批量模式返回两个 agent 的响应（验证group_chat守卫下仍能正常响应）；
6. /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