作者1Lyn-en项目地址github.com/1Lyn-en/AgentForge版权声明本文为博主原创文章遵循 CC 4.0 BY-SA 版权协议转载请附上原文出处链接和本声明。 从零搭建企业级 AI 智能体平台AgentForge 完整架构解析与实战一、写在前面2026 年大模型早已不是「聊天玩具」。企业真正需要的是能理解业务、调用工具、自主决策的 AI 智能体Agent。但在实际落地中你可能会遇到这些问题 想做一个带工具调用的 Agent但 LangChain 文档散乱、版本割裂 需要集成多个 LLMQwen、DeepSeek切换起来手忙脚乱 想让 AI 自动发邮件、查数据库但不知道怎么串联 想接入视频生成能力还要管理资产库 老板要每日数据简报你还在一张张跑 SQL 贴 Excel这些问题AgentForge都给出了答案。本文将从零开始带你看懂一个生产级全栈 AI 智能体平台的完整架构与实现细节。二、项目概览AgentForge 是一个基于LangChain FastAPI Vue.js的企业级多智能体平台v0.3.0 版本实现了五大核心模块模块作用关键技术AI Agent 层4 个智能体各司其职LangChaincreate_agentAgentExecutorTool 工具层8 个工具打通内外系统LangChaintool装饰器LLM 模型层统一工厂多模型热切换ChatOpenAI (DashScope / DeepSeek)REST API 层20 接口前后端分离FastAPI SSE 流式推送前端 SPA 层单页应用开箱即用Vue.js 2 marked.js支持的功能包括✅多模型对话Qwen 3.7 Max / Plus、DeepSeek V4 Pro 无缝切换✅流式 SSE 响应打字机效果实时输出✅邮件验证码登录QQ 邮箱 SMTP Redis 会话管理✅AI 视频生成DashScope Wan2.7-T2V自动下载归档✅视频资产管理搜索、播放、分页✅CEO 数据简报从 MySQL 自动提取业务数据邮件推送✅对话历史管理Redis 存储30 天保留✅暗色/亮色主题CSS 自定义属性方案三、系统架构深度解析3.1 整体架构图┌──────────────────────────────────────────────────────────────┐ │ Vue.js SPA (chat.html) │ │ 登录页 · 聊天页 · 视频库 · 主题切换 · Markdown 渲染 │ └──────────────────────────┬───────────────────────────────────┘ │ HTTP / SSE ┌──────────────────────────▼───────────────────────────────────┐ │ FastAPI (port 9000) │ │ CORS · 静态文件挂载 · 20 REST 端点 · 路由分发 │ └──────────────────────────┬───────────────────────────────────┘ │ ┌──────────────────────────▼───────────────────────────────────┐ │ AI Agent 层 (LangChain) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ │ │ ChatAgent│ │LoginAgent│ │VideoAgent│ │PersonalAssist │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───────┬────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ 工具层 (8 个 LangChain Tools) │ │ │ │ MySQL · Email · Redis · VideoGen · Download · Archive │ │ │ └───────────┬────────────┬───────────────┬───────────────┘ │ └──────────────┼────────────┼───────────────┼──────────────────┘ ▼ ▼ ▼ ┌────────┐ ┌──────────┐ ┌──────────────┐ │ MySQL │ │ QQ SMTP │ │ Redis │ │ DB │ │ Server │ │ Cache/Session│ └────────┘ └──────────┘ └──────────────┘ ┌──────────────────────────────────┐ │ LLM 后端三选一 │ │ Qwen Max · Qwen Plus · DeepSeek │ │ Wan2.7 T2V (视频生成) │ └──────────────────────────────────┘3.2 核心设计原则AgentForge 的设计遵循3 个关键原则Agent 即服务每个 Agent 封装一个完整业务场景输入问题、输出结果对外屏蔽 LangChain 复杂度工具即插即用每个工具独立、无状态、可复用Agent 只需声明依赖哪些工具配置即代码所有敏感信息走环境变量模型切换通过字符串 key无需改代码四、核心模块代码拆解4.1 ChatAgent通用对话智能体最核心的 Agent掌管所有通用对话。它拥有 4 个工具发邮件、查数据库、生成视频、下载视频。# ai/agent/chat_agent.pyfromai.tool.mysql_toolimportmysql_toolfromai.tool.send_email_toolimportsend_email_toolfromai.tool.generate_video_toolimportgenerate_videofromai.tool.download_video_toolimportdownload_video_toolfromlangchain.agentsimportcreate_agentfromlangchain_openaiimportChatOpenAIclassChatAgent:def__init__(self,model_key:strNone):configMODEL_CONFIG.get(model_key,MODEL_CONFIG[qwen3.7-max])self.modelChatOpenAI(modelconfig[model_name],api_keyconfig[api_key],base_urlconfig[base_url])self.tools[send_email_tool,mysql_tool,generate_video,download_video_tool]self.agentcreate_agent(modelself.model,toolsself.tools,system_prompt你是一个智能助手...,debugTrue)多模型配置支持 3 个模型热切换通过model_key参数选择MODEL_CONFIG{qwen3.7-max:{model_name:os.getenv(QWEN_MODEL_NAME),base_url:os.getenv(QWEN_MODEL_URL),api_key:os.getenv(DASHSCOPE_API_KEY),},qwen3.7-plus:{...},deepseek-v4pro:{model_name:os.getenv(DEEPSEEK_MODEL_NAME),base_url:os.getenv(DEEPSEEK_MODEL_URL),api_key:os.getenv(DEEPSEEK_API_KEY),},}流式 SSE 响应使用astream_events generator 实现打字机效果asyncdefchat_stream(self,question:str):asyncforeventinself.agent.astream_events({messages:[{role:user,content:question}]},versionv2):event_typeevent[event]ifevent_typeon_chat_model_stream:chunkevent[data][chunk]ifhasattr(chunk,content)andchunk.content:yield{type:answer,content:chunk.content}elifevent_typeon_tool_start:yield{type:thinking,content:f正在调用工具{event[name]}}前端通过EventSource接收体验丝滑流畅。4.2 LoginAgent邮件验证码登录这是一个纯 Prompt 驱动的 Agent——没有手写逻辑完全靠系统提示词让 LLM 理解流程并自主调用工具# ai/agent/login_agent.pyLOGIN_SYSTEM_PROMPT 你是一个邮件登录助手 你可以发送邮件你有以下工具 一 send_email_tool 发送邮件 二 mysql_tool 数据库查询工具 三 redis_tool redis 设置数据 四 redis_get_tool redis 获取数据 请严格按照以下步骤执行 一意图识别 如果用户输入只有邮箱请执行发送验证码流程 如果用户输入含有邮箱和验证码请执行登录流程 二发送验证码流程 步骤一 随机生成一个4位数的不规则随机数 步骤二 调用 send_email_tool 发送邮件 步骤三 调用 redis_tool 存入验证码键名格式 code:邮箱 三登录流程 步骤一 调用 redis_get_tool 获取验证码并比对 步骤二 调用 mysql_tool 根据邮箱查询用户名 登录成功后API 层还会生成会话 Token 存入 Redis7 天 TTLtokenstr(uuid.uuid4())redis_client.set(fsession:{token},f{email}|{username}|{user_id},exSESSION_TTL# 604800秒)4.3 VideoAgent文生视频全流程从文字描述到最终视频文件落地一条龙自动化# ai/tool/generate_video_tool.pyimportdashscopetool(args_schemaVideoGenInput)defgenerate_video(prompt:str)-str:根据文本描述生成视频rspdashscope.VideoSynthesis.call(api_keyos.getenv(DASHSCOPE_API_KEY),modelwan2.7-t2v-2026-04-25,# 通义万相 2.7promptprompt,resolution720P,ratio16:9,duration2,watermarkTrue)ifrsp.status_codeHTTPStatus.OK:returnf视频生成成功视频链接{rsp.output.video_url}returnf视频生成失败:{rsp.message}生成后自动下载并归档到 MySQL# ai/tool/download_video_tool.pytool(download_video_tool)defdownload_video_tool(url:str)-Dict[str,Any]:下载视频到本地 static/download 目录并自动归档到数据库filenametime.strftime(%Y%m%d%H%M%S).mp4save_pathos.path.join(static,download,filename)# ... 流式下载逻辑 ...local_urlfhttp://localhost:9000/static/download/{filename}archive_result_archive_video(filename,local_url,total_size)return{type:video,video_url:local_url,status:success,archive_info:archive_result}4.4 PersonalAssistantCEO 每日数据简报自动从 MySQL 的 orders/products 表提取 5 个维度的业务数据并邮件推送# 总订单数与总销售额cursor.execute(SELECT COUNT(*), SUM(total_amount) FROM orders)total_orders,total_amountcursor.fetchone()# 最近 7 天订单趋势cursor.execute(SELECT order_date, COUNT(*), SUM(total_amount) FROM orders GROUP BY order_date ORDER BY order_date DESC LIMIT 7)# 热销商品 TOP 5 (JOIN products 表)cursor.execute(SELECT p.product_name, p.category, SUM(o.quantity), SUM(o.total_amount) FROM orders o JOIN products p ON o.product_id p.product_id GROUP BY o.product_id ORDER BY SUM(o.total_amount) DESC LIMIT 5)# 品类销售额分布 支付方式分布...生成的简报格式 CEO 每日数据简报 总订单数1,286 总销售额¥589,234.00 平均订单金额¥458.20 ── 最近 7 日订单趋势 ── 2026-06-28: 187 单¥85,432.00 ... ── 热销商品 TOP 5 ── 1. 笔记本电脑数码销量 89销售额 ¥534,000.00 ...4.5 工具即插即用LangChain tool 模式每个工具都用tool装饰器定义配合 Pydantic 做参数校验# ai/tool/mysql_tool.pyfrompydanticimportBaseModel,Fieldfromlangchain.toolsimporttoolclassMysqlToolParams(BaseModel):sql:strField(...,descriptionsql语句)tool(mysql_tool,args_schemaMysqlToolParams)defmysql_tool(sql:str)-str:查询sql语句conpymysql.connect(hostos.getenv(DATABASE_HOST),portint(os.getenv(DATABASE_PORT)),useros.getenv(DATABASE_USER),passwordos.getenv(DATABASE_PASSWORD),databaseos.getenv(DATABASE_NAME),)cursorcon.cursor()cursor.execute(sql)rscursor.fetchall()returnstr(rs)Agent 只需声明tools [mysql_tool, send_email_tool, ...]即可获得能力。新增工具只需新建一个tool函数无缝接入。五、API 接口体系系统提供 14 REST 接口覆盖完整业务闭环端点方法功能鉴权/chat_invokeGET同步对话✅/chat_streamGET流式对话 (SSE)✅/sendCodeGET发送验证码❌/loginGET验证码登录❌/logoutGET退出登录✅/check_loginGET检查登录状态✅/save_conversationPOST保存会话✅/get_conversationsGET会话列表✅/get_conversationGET获取特定会话✅/delete_conversationPOST删除会话✅/chat_videoGET视频生成 (SSE)✅/get_video_listGET视频资产列表✅/archive_videoPOST视频归档✅/personal_assistantGETCEO 简报✅流式接口使用StreamingResponsetext/event-stream前端通过EventSource接收// 前端 SSE 接收示例constsourcenewEventSource(/chat_stream?question${encodeURIComponent(msg)}token${token});source.onmessage(event){constdataJSON.parse(event.data);if(data.done){source.close();return;}// data.type: answer | thinking | video// data.data: 文本内容};六、环境搭建与配置6.1 前置依赖组件版本要求用途Python 3.10运行环境MySQL8.0业务数据持久化Redis6.0会话、缓存、验证码DashScope API Key-Qwen 模型 视频生成DeepSeek API Key-DeepSeek 模型可选6.2 配置指南复制.env.example为.env填入真实配置# LLM 模型 DASHSCOPE_API_KEYsk-你的Key DEEPSEEK_API_KEYsk-你的Key可选 # 数据库 DATABASE_HOSTlocalhost DATABASE_PORT3306 DATABASE_USERroot DATABASE_PASSWORD你的密码 DATABASE_NAMEshiyou03 # Redis REDIS_HOST127.0.0.1 REDIS_PORT6379 # SMTP 邮件 SMTP_USER你的QQ邮箱qq.com SMTP_PASSWORD你的QQ邮箱SMTP授权码6.3 数据库表结构-- 用户表CREATETABLEuser_info(user_idINTPRIMARYKEY,user_nameVARCHAR(100),emailVARCHAR(200),departmentVARCHAR(100));-- 订单表CREATETABLEorders(idINTPRIMARYKEYAUTO_INCREMENT,order_dateDATE,product_idINT,quantityINT,total_amountDECIMAL(10,2),payment_methodVARCHAR(50));-- 商品表CREATETABLEproducts(product_idINTPRIMARYKEY,product_nameVARCHAR(200),categoryVARCHAR(100));-- 视频归档表CREATETABLEvideo_archive(idINTPRIMARYKEYAUTO_INCREMENT,video_nameVARCHAR(255),download_timeDATETIME,video_urlVARCHAR(500),file_sizeINT);6.4 启动运行# 1. 克隆项目gitclone https://github.com/1Lyn-en/AgentForge.gitcdAgentForge# 2. 安装依赖pipinstall-rrequirements.txt# 3. 配置环境变量cp.env.example .env# 编辑 .env 填入你的 API Key 和数据库密码# 4. 启动服务uvicorn api.main:app--host0.0.0.0--port9000--reload# 5. 打开浏览器访问# http://localhost:90006.5 启动验证登录流程在登录页输入邮箱 → 点击发送验证码 → 查收邮件 → 输入 4 位验证码登录对话测试选择 Qwen 3.7 Max 模型输入「查询一下 user_info 表的数据」视频生成输入「一只橘猫在阳光下打哈欠特写镜头」CEO 简报点击个人助理功能输入收件邮箱接收业务数据报告七、技术亮点总结7.1 Prompt 即逻辑LoginAgent是一个极佳的例子——零代码的业务流程。传统的登录系统需要手写 if-else 判断、状态机管理而在 Agent 模式下只需一段自然语言 Prompt 就能让 LLM 自主理解并执行“发验证码→存 Redis→验证→查用户”。代码量减少了 80%且修改流程只需改 Prompt无需动代码。7.2 流式交互体验同步 API 在 AI 场景下体验极差用户要等 5-10 秒才有响应。AgentForge 全链路采用SSE (Server-Sent Events)推送工具调用状态实时可见“正在查询数据库…” → “正在生成视频…” → 逐 token 输出回答用户感知延迟从 10 秒降到 0。7.3 Agent Tool 的解耦设计每个 Tool 独立、无状态、只做一件事。新增能力 新建一个tool函数 在 Agent 的tools列表中注册。这种插件式架构让系统极易扩展想接飞书通知写一个send_feishu_tool加上就行。7.4 全栈开箱即用后端 FastAPI 前端 Vue.js SPA单文件无构建步骤部署极其轻量。前端依赖通过 CDN 引入连npm install都不需要。这让项目非常适合企业内部工具或个人开发者快速验证想法的场景。八、踩坑与优化建议8.1 踩过的坑坑解决LangChain 0.x → 1.0 接口不兼容使用create_agent替代initialize_agentSSE 流式乱码确保 FastAPI 返回 UTF-8 ensure_asciiFalseRedis 中文验证码比对失败decode_responsesTrue统一编码视频下载大文件内存溢出使用streamTrueiter_content分块写入8.2 优化方向WebSocket 替代 SSESSE 是单向推送WebSocket 支持双向通信适合更复杂的协作场景Docker 容器化当前依赖手动安装 MySQL/RedisDocker Compose 一键启动体验更好增加测试覆盖项目目前缺乏自动化测试关键 Agent 流的单元测试迫在眉睫敏感信息管理SMTP 密码已从代码迁移到.env建议后续接入密钥管理服务九、总结AgentForge 展示了LangChain Agent 模式在企业场景下的完整落地路径。它不是一个Hello World级别的 Demo而是一个包含认证、对话、视频、数据分析、邮件推送的生产级全栈应用。它所体现的核心理念——用自然语言替代传统代码编写业务流程逻辑——正在重新定义企业应用开发的方式。当 LLM 不再是聊天玩具而是成为能理解业务、调用工具、自主决策的数字员工这正是 AI Agent 的真正价值所在。如果你正在探索如何将 AI Agent 落地到实际业务中希望 AgentForge 的架构思路能给你一些启发。项目地址github.com/1Lyn-en/AgentForge欢迎 Star ⭐、Fork、PR觉得有用的话点个赞再走呗