# Agentic-Systems：可视化 Agent 执行流程的全栈智能系统

> 一个结合 React 前端与 FastAPI + LangGraph 后端的完整 Agentic AI 系统，支持文档上传、向量化存储和实时可视化 Agent 执行流程，通过 Server-Sent Events 流式展示推理步骤。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-20T08:39:21.000Z
- 最近活动: 2026-05-20T08:51:02.275Z
- 热度: 163.8
- 关键词: Agentic AI, LangGraph, RAG, FastAPI, React, Ollama, ChromaDB, 可视化, LLM, 本地部署
- 页面链接: https://www.zingnex.cn/forum/thread/agentic-systems-agent
- Canonical: https://www.zingnex.cn/forum/thread/agentic-systems-agent
- Markdown 来源: ingested_event

---

## 引言：当 AI Agent 需要"被看见"\n\n大型语言模型（LLM）的崛起让 AI Agent 从概念走向实践，但 Agent 的内部运作往往是一个"黑盒"——用户输入问题，Agent 输出答案，中间发生了什么却无从得知。这种不透明性不仅增加了调试难度，也让开发者难以理解和优化 Agent 的行为。\n\nAgentic-Systems 项目正是为了解决这一痛点而生。它是一个全栈 Agentic AI 演示系统，通过可视化的方式将 Agent 的推理步骤、规划过程、记忆更新、工具执行和模型路由完整呈现给用户。本文将深入解析这个项目的架构设计、核心功能和技术实现，帮助读者理解如何构建一个透明、可观测的 Agent 系统。\n\n## 项目概述：全栈架构一览\n\nAgentic-Systems 采用现代化的全栈架构，前端基于 React 18 构建，后端使用 FastAPI 框架，核心 Agent 逻辑由 LangGraph 驱动。整个系统围绕文档问答场景设计，但其架构模式可扩展到更复杂的 Agent 应用场景。\n\n### 技术栈组成\n\n前端层采用 React 18 配合 Vite 构建工具，提供流畅的用户交互体验。后端服务基于 FastAPI 0.1.0 版本，利用 Python 的异步特性处理高并发请求。Agent 核心使用 LangGraph 实现状态机驱动的多节点执行流程，向量存储选用 ChromaDB， embedding 模型通过 Ollama 本地部署。\n\n这种技术选型体现了"本地化优先"的设计理念——整个系统可以在完全离线的环境中运行，无需依赖云服务，既保护了数据隐私，也降低了使用成本。\n\n## 核心功能：不只是聊天，更是可观测的 Agent\n\nAgentic-Systems 的核心价值在于将 Agent 的执行过程从"黑盒"变为"白盒"。系统提供了七大核心功能，每个功能都针对 Agent 可观测性的特定维度。\n\n### 1. 文档摄入与向量化\n\n系统支持上传 .txt、.md 和 .pdf 格式的文档。上传后，后端会自动提取文本内容，使用滑动窗口算法将文本分割为 1000 字符的重叠片段（overlap 200 字符），然后通过 Ollama 调用 nomic-embed-text 模型计算每个片段的 embedding 向量，最后将结果存入 ChromaDB 向量数据库。\n\n这种设计确保了即使是大篇幅文档也能被有效索引和检索，重叠片段的设置避免了关键信息在分割边界处丢失。\n\n### 2. Agentic RAG 查询\n\n当用户提交自然语言查询时，系统会启动 LangGraph 状态机，依次执行三个节点：规划（plan）、检索（retrieve）和综合（synthesize）。规划节点分析查询意图并制定执行策略；检索节点从向量数据库中查找相关文档片段；综合节点基于检索结果生成最终答案。\n\n这种分阶段的处理方式让复杂查询可以被拆解为可管理的步骤，每个步骤的输出都成为下一步的输入，形成清晰的执行链条。\n\n### 3. 实时执行追踪\n\n这是 Agentic-Systems 最具特色的功能。通过 Server-Sent Events（SSE）技术，Agent 的每个执行步骤都会实时推送到浏览器端，包括工具名称、推理思考过程等信息。前端界面会以动画形式展示这些步骤，让用户能够"看见"Agent 是如何一步步得出结论的。\n\n这种实时可视化不仅提升了用户体验，更为开发者调试 Agent 行为提供了 invaluable 的洞察。\n\n### 4. 对话持久化\n\n每个聊天会话都会以 UUID 形式存储在 SQLite 数据库中，包含完整的消息历史、运行记录和每个步骤的审计信息。这种设计支持会话的恢复和审计，对于生产环境中的 Agent 系统尤为重要。\n\n### 5. 交互式演示场景\n\n系统预置了三种演示场景：研究与总结、多步推理、自主任务执行。这些场景通过脚本化的步骤数据展示 Agent 的不同行为模式，非常适合用于技术演示和教学场景。\n\n### 6. Agent 记忆面板\n\n侧边栏的记忆面板会从 SSE 流中提取最近的五条记忆标记的步骤思考，并实时更新。这让用户能够快速了解 Agent 的"短期记忆"状态，理解 Agent 当前的关注焦点。\n\n### 7. 文档库管理\n\n文档库面板会在挂载时和每次上传后自动调用 GET /api/v1/documents 接口，展示所有已索引的文件。这种设计让用户对系统的知识边界有清晰的认知。\n\n## 架构深度解析：LangGraph 状态机驱动\n\nAgentic-Systems 的架构设计体现了现代 Agent 系统的最佳实践。让我们从数据流的角度深入理解其工作原理。\n\n### 数据流全景\n\n用户在前端界面选择文件上传，前端将文件作为 multipart/form-data POST 到 /api/v1/documents/upload 接口。后端验证文件扩展名，生成 UUID 作为文档 ID，将原始字节写入磁盘，然后提取纯文本内容。\n\n文本提取完成后，系统使用滑动窗口算法进行分块，每块 1000 字符，重叠 200 字符。分块结果会同时写入 SQLite 的 chunks 表和 ChromaDB 向量数据库。向量化过程通过调用 Ollama 的 nomic-embed-text 模型完成。\n\n当用户提交查询时，请求被路由到 /api/v1/agent/run 端点。后端创建新线程运行 LangGraph 状态机，通过 StreamingResponse 以 text/event-stream 格式返回 SSE 事件。\n\n### LangGraph 状态机详解\n\nAgentState 是状态机的核心数据结构，它在三个节点间传递：\n\n**规划节点（plan_node）**：接收用户查询，分析任务类型，制定执行计划。计划内容包括需要调用的工具、执行顺序和预期输出格式。\n\n**检索节点（retrieve_node）**：根据规划节点的输出，调用 query_similar() 方法从 ChromaDB 检索最相关的文档片段（默认返回 top-4）。检索结果会被注入到状态中，供综合节点使用。\n\n**综合节点（synthesize_node）**：使用 ChatOllama（llama3.1 模型）基于检索到的文档片段生成最终答案。这个节点也会将推理过程作为记忆事件发射到 SSE 流。\n\n### 存储层设计\n\n系统采用双存储架构：SQLite 负责结构化数据（会话、消息、运行记录、步骤审计、文档元数据），ChromaDB 负责非结构化数据的向量表示。这种分离让系统能够充分利用两种存储引擎的优势——SQLite 的事务性和查询能力，ChromaDB 的相似性搜索能力。\n\n## 部署与使用：五分钟上手\n\nAgentic-Systems 的部署过程设计得非常简洁，遵循"本地优先"原则。\n\n### 环境准备\n\n首先需要启动 Ollama 服务并拉取所需模型：\n\n```bash\nollama serve\nollama pull llama3.1\nollama pull nomic-embed-text\n```\n\n### 启动后端\n\n进入 backend 目录，创建虚拟环境并安装依赖：\n\n```bash\ncd backend\npython -m venv .venv && source .venv/bin/activate\npip install -r requirements.txt\nuvicorn app.main:app --reload --port 8000\n```\n\n### 启动前端\n\n在项目根目录开启新终端：\n\n```bash\nnpm install\nnpm run dev\n```\n\n访问 http://localhost:5173 即可使用系统。后端健康检查地址为 http://localhost:8000/health。\n\n## 应用场景与价值\n\nAgentic-Systems 不仅是一个技术演示项目，更为实际应用提供了有价值的参考模式。\n\n### 教育场景\n系统的可视化特性使其成为教授 Agent 概念的理想工具。学生可以直观地看到 Agent 如何分解任务、如何检索信息、如何综合答案，这种"看见过程"的学习体验远胜于阅读理论文档。\n\n### Agent 开发调试\n对于正在开发 Agent 应用的工程师，Agentic-Systems 展示了如何实现可观测的 Agent 系统。SSE 流式输出、步骤审计、记忆追踪等模式都可以被借鉴到生产系统中。\n\n### 本地知识库构建\n系统的文档摄入和 RAG 实现提供了一个完整的本地知识库解决方案。企业可以将内部文档导入系统，构建私有化的问答助手，数据完全保留在本地环境。\n\n## 技术亮点与最佳实践\n\nAgentic-Systems 在多个方面体现了优秀的工程实践：\n\n**异步架构**：后端使用 FastAPI 的异步特性，SSE 流式输出不会阻塞其他请求，确保了良好的并发性能。\n\n**模块化设计**：系统被清晰地划分为前端、API 层、服务层和数据层，每层职责明确，便于维护和扩展。\n\n**错误处理**：文档上传流程中包含多处验证（文件扩展名、分块结果非空等），确保系统在面对异常输入时能够优雅处理。\n\n**本地优先**：整个架构设计围绕本地部署优化，从 Ollama 的模型管理到 ChromaDB 的持久化存储，都考虑了离线场景的需求。\n\n## 总结与展望\n\nAgentic-Systems 为 Agent 可观测性提供了一个优秀的实现范例。通过将 LangGraph 状态机与 React 可视化层结合，项目成功地将 Agent 的"黑盒"内部展现给用户，这种透明性对于 Agent 技术的普及和应用至关重要。\n\n随着 Agent 技术从实验走向生产，可观测性将成为关键需求。Agentic-Systems 展示的模式——实时执行追踪、记忆管理、审计日志——很可能成为未来 Agent 平台的标准配置。对于希望深入理解 Agent 工作原理或构建自己 Agent 系统的开发者，这个项目提供了宝贵的参考。