从 0 到 1 搭建企业级 AI AgentFastAPI 服务层 工具调用 长时记忆 RAG 学习全栈落地实录摘要本文复盘某互联网平台智能客服 Agent 从 0 到 1 的完整搭建过程FastAPI 四接口服务层、Master 主类设计、tool 工具体系实时搜索/专业 API/本地知识库、Redis 持久化长时记忆、URL 驱动的 RAG 学习能力以及 Docker LangSmith 生产部署附核心代码与真实踩坑记录帮你绕过Demo 能跑、生产就挂的全部经典陷阱。一、先说结论生产级 Agent 确定性流程工具化 非确定性决策 Agent 化 程序化校验兜底先讲一个我们踩过的大坑最初团队用低代码工作流平台搭 AgentV1 版节点之间上下文隔离、无状态用户问今天销售额 → 昨天 → 前天三次追问要重复执行三遍完整链路单次查询动辄 15 秒以上多意图混合查询“查 A 商品昨日销量和 B 商品本周退货率”更是没法并行强行加判断节点又引入额外延迟。后来我们重构为高代码架构V3一句话总结核心思想确定性逻辑 → 用代码封装成原子工具toys杜绝 LLM 幻觉 不确定性逻辑 → 交给 Agent 做轻量语义理解与路径决策 安全兜底 → 用程序化校验Harness替代脆弱的 Prompt 约束重构后追问场景从 15 秒降到 4 秒级多意图查询也能精准并行。下面按完整搭建顺序展开。二、整体架构四层设计职责分明┌─────────────────────────────────────────────┐ │ 应用层Telegram 机器人 / 网页 / 数字人 │ ├─────────────────────────────────────────────┤ │ API层FastAPI/chat /add_urls /add_pdfs │ │ /add_texts WebSocket 流式 │ ├─────────────────────────────────────────────┤ │ 服务层LangChainChain/Memory/Tools/ │ │ Agent 情绪判断链 │ ├─────────────────────────────────────────────┤ │ 资源层Redis记忆 / Qdrant向量库 │ │ 大模型 API / 外部工具 API │ └─────────────────────────────────────────────┘三、API 层FastAPI 四个接口打天下服务端就一个核心文件四个 POST 接口fromfastapiimportFastAPI,WebSocket appFastAPI()app.post(/chat)# 主对话接口asyncdefchat(query:str):resultmaster.run(query)# Master 是 Agent 主类return{response:result}app.post(/add_urls)# 从 URL 学习知识asyncdefadd_urls(url:str):master.learn_from_url(url)return{status:ok}app.post(/add_pdfs)# 从 PDF 学习知识app.post(/add_texts)# 从文本学习知识关键依赖版本锁死这是踩坑换来的fastapi0.108.0 langchain0.1.10 langchain_core0.1.28 langchain_openai0.0.5 langchain_community0.0.25 redis最新 qdrant_client1.7.1 uvicorn0.23.2避坑要点LangChain 0.1 起拆分成了langchain-core、langchain-openai、langchain-community三个包老教程的from langchain.llms import ChatOpenAI写法已经过时。版本不锁三天就报错。四、Agent 主体Master 类 角色 Prompt 设计4.1 主类初始化fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportAgentExecutor,create_openai_tools_agentclassMaster:def__init__(self,tools):self.llmChatOpenAI(modelgpt-3.5-turbo-1106,temperature0,# 铁律严格遵循 PromptstreamingTrue,# WebSocket 流式返回需要)self.promptChatPromptTemplate.from_messages([(system,SYSTEM_PROMPT),# 角色设定(placeholder,{chat_history}),# 记忆占位符(human,{input}),(placeholder,{agent_scratchpad}),])self.agentcreate_openai_tools_agent(self.llm,tools,self.prompt)self.executorAgentExecutor(agentself.agent,toolstools,verboseTrue)避坑要点create_openai_tools_agent要求 tools至少传一个非空工具否则直接报错。开发初期可以先塞一个假工具占位再逐步替换成真工具。4.2 角色 Prompt人设即产品角色设定全部靠 Prompt 注入换一套 Prompt 就是另一个 Agent——这是 Agent 可扩展性的精髓SYSTEM_PROMPT你是陈大师一位精通阴阳五行、紫微斗数、八字测算的资深命理师。 你年约60岁曾是江西一带赫赫有名的江湖人士后因故左眼失明人称陈瞎子。 你性格豁达幽默说话直来直去但句句在理。 你只使用繁体字回复。遇到负面情绪的用户先安抚再解答。4.3 情绪判断链用 Chain 把模糊情绪变成确定性信号独立一个detect_emotion()方法用专用 Prompt 约束 LLM 只输出四类标签defdetect_emotion(self,text:str)-str:chainLLMChain(llmself.llm,promptEMOTION_PROMPT)emotionchain.run(text).strip().lower()self.emotionemotion# friendly / depressed / default / angryreturnemotion实测效果输入你好返回 friendly输入你真是个傻子返回 angry。情绪标签存到self.emotion后续语音合成、回复策略切换都能用——它用 Prompt 工程把模糊情绪转化为确定性信号为后续环节提供原子级控制开关是低成本实现高拟真交互的关键杠杆。4.4 工具调用链路用户视角把前面所有模块串起来一次完整的工具调用是这样的用户请求 → Agent 判断该用哪个工具 → 携带参数调用工具搜索 / 命理 API / 知识库 → 拿到观察结果Observation → Agent 结合结果生成最终回答五、工具体系tool 装饰器三步建一个工具5.1 实时搜索工具SerpAPIfromlangchain_core.toolsimporttoolfromlangchain_community.utilitiesimportSerpAPIWrappertooldefsearch(query:str):只有需要了解实时信息或不知道的事情时才使用这个工具。resultSerpAPIWrapper().run(query)print(实时搜索结果:,result)returnresult工具描述docstring决定 Agent 能不能正确选用工具——描述必须写清楚什么时候该用这是 Agent 与普通函数最本质的区别。5.2 专业 API 工具参数校验不能省Agent 传进来的参数全是字符串调用专业 API八字测算、解梦等前必须做参数提取与校验——用一个小型 LLMChain 把用户输入转成结构化 JSONparam_chainLLMChain(llmllm,promptChatPromptTemplate.from_template(你是参数查询助手根据用户输入提取相关参数按 JSON 格式返回。\n输入{input}))tooldefbazi_calculate(text:str):用户要求测算八字时使用。paramsjson.loads(param_chain.run(text))# 提取年月日时等参数resprequests.post(https://api.example.com/bazi,jsonparams)returnresp.json()5.3 本地知识库工具RAG把专业领域知识企业规范、业务文档向量化存 Qdrant工具内做相似度检索tooldefknowledge_search(query:str):回答企业内部专业知识问题时使用。returnvectorstore.similarity_search(query,k5)避坑要点工具密钥SerpAPI Key 等用环境变量管理千万别写死在代码里。生产环境建议加访问审计和请求频控单点泄露不至于全系统失陷。六、长时记忆Redis 持久化 智能压缩大模型无状态对话记录必须外挂。方案Redis 存历史 超阈值自动摘要压缩fromlangchain_community.chat_message_historiesimportRedisChatMessageHistoryfromlangchain.memoryimportConversationTokenBufferMemorydefget_memory(session_iddefault):historyRedisChatMessageHistory(session_idsession_id,urlredis://localhost:6379/0)# 超过 10 条记录 → LLM 提炼摘要清空旧记录iflen(history.messages)10:summaryllm.invoke(f提炼以下对话的要点\n{history.messages})history.clear()history.add_ai_message(summary)returnConversationTokenBufferMemory(chat_memoryhistory,human_prefix用户,ai_prefix助手,memory_keyhistory,max_token_limit1000)注意记忆要生效Prompt 模板里必须预留{chat_history}占位符见 4.1 节否则记忆注入不进去——这是最隐蔽的坑。七、RAG 学习能力给 Agent 喂 URL不用微调学习的本质是 RAGURL → HTML 转文本 → 切分 → 向量化 → 存库 → 检索。加载器可换PDF 用 PyPDFLoader后续步骤通用fromlangchain_community.document_loadersimportUnstructuredURLLoaderfromlangchain.text_splitterimportRecursiveCharacterTextSplitterfromlangchain_openaiimportOpenAIEmbeddingsfromlangchain_community.vectorstoresimportQdrantdeflearn_from_url(url:str):docsUnstructuredURLLoader(urls[url]).load()textsRecursiveCharacterTextSplitter(chunk_size800,chunk_overlap50).split_documents(docs)Qdrant.from_documents(texts,OpenAIEmbeddings(),collection_namelearning_knowledge)避坑要点同一个向量库内用不同 collection 隔离知识门类物流文档、业务规范各一个集合检索精度明显高于混在一起。80% 以上的场景靠 RAG 就够了不需要微调——微调是最后手段不是默认选项。八、生产部署Docker Compose LangSmith8.1 Docker 保证环境一致version:3services:redis:image:redis:latestvolumes:[redis-data:/data]# 数据卷升级不丢历史ai-server:build:.environment:-REDIS_URLredis://redis:6379/0ports:[9000:9000]depends_on:[redis]volumes:redis-data:避坑要点记忆数据必须挂数据卷volumes否则docker-compose down一次Redis 里的聊天记录全没——这个坑我们上线第一周就踩了。8.2 LangSmith 生产追踪配置三个环境变量即可LANGCHAIN_TRACING_V2true LANGCHAIN_API_KEY你的key LANGCHAIN_PROJECT项目名注意只有invoke()调用会被追踪run()** 不会**。追踪面板能看每次 LLM 调用的耗时、Token 消耗、工具调用链和错误日志——生产环境排障必备。我们靠它定位过一个 30 秒慢响应最后发现是文档摘要链卡住了光靠肉眼猜根本查不出来。8.3 为什么不用 LangServe社区有现成的 LangServeLangChain 官方 Server 方案自带 Playground 调试界面和自动路由生成看着很香。但我们最终坚持手写 FastAPI原因很现实LangServe 是较新的开源项目版本迭代激进不建议直接上生产单体架构耦合度高项目结构会被框架绑架我们只需要 4 个接口手写 20 行代码的事不值得引入依赖。选型原则核心逻辑自主掌控——工具类库可以随便用但服务骨架这种主航道别把控制权交给快速演进的框架。九、扩展从文本到多端接入与 AI 数字人Agent 服务搭好后横向扩展非常快我们实际做了两件事① 多端接入。同一个/chat接口套不同的客户端壳就能换平台——Telegram 机器人用 telebot 包BotFather 申请 Token、网页、企业微信原理完全一致。服务端只管对话客户端只管收发职责解耦。② AI 数字人 Demo。在 Agent 之上叠加 TTS 虚拟形象Agent 生成文本 → 调用语音合成 API → WebRTC 推流 → 前端video播放。架构上是三层拼接LangChain Agent大脑 语音/形象 API表达 WebRTC传输数字人 Demo 验证了一个结论Agent 的能力边界不在模型而在你能接多少表达通道——文本、语音、形象每多一层应用形态就上一个大台阶。十、写在最后这套架构最大的价值是回答了Agent 到底怎么落地别让 LLM 干它不擅长的事确定性计算、权限校验、SQL 生成交给代码只让它干最擅长的语义理解、路径决策、内容生成再用 Harness 程序化校验兜底。低代码工作流平台看着省事但在语义模糊、高并发、强实时场景下抽象层级过高会让你失去对调用链路和状态流转的控制。如果重来一遍我会更早做三件事① 先把所有成熟路径封装成原子工具② 给每个工具写清楚什么时候用③ 用 LangSmith 从第一天就开始埋点。这三件事做对了Agent 的工程化之路会顺畅很多。如果你也在搭生产级 Agent欢迎评论区聊聊你的架构。下面几个方向想看哪个留言告诉我Agent 多工具并行的调度策略与冲突处理Harness 程序化校验的完整落地SQL 安全、权限拦截语音合成 数字人与 Agent 的集成实战
企业级Agent从0到1
从 0 到 1 搭建企业级 AI AgentFastAPI 服务层 工具调用 长时记忆 RAG 学习全栈落地实录摘要本文复盘某互联网平台智能客服 Agent 从 0 到 1 的完整搭建过程FastAPI 四接口服务层、Master 主类设计、tool 工具体系实时搜索/专业 API/本地知识库、Redis 持久化长时记忆、URL 驱动的 RAG 学习能力以及 Docker LangSmith 生产部署附核心代码与真实踩坑记录帮你绕过Demo 能跑、生产就挂的全部经典陷阱。一、先说结论生产级 Agent 确定性流程工具化 非确定性决策 Agent 化 程序化校验兜底先讲一个我们踩过的大坑最初团队用低代码工作流平台搭 AgentV1 版节点之间上下文隔离、无状态用户问今天销售额 → 昨天 → 前天三次追问要重复执行三遍完整链路单次查询动辄 15 秒以上多意图混合查询“查 A 商品昨日销量和 B 商品本周退货率”更是没法并行强行加判断节点又引入额外延迟。后来我们重构为高代码架构V3一句话总结核心思想确定性逻辑 → 用代码封装成原子工具toys杜绝 LLM 幻觉 不确定性逻辑 → 交给 Agent 做轻量语义理解与路径决策 安全兜底 → 用程序化校验Harness替代脆弱的 Prompt 约束重构后追问场景从 15 秒降到 4 秒级多意图查询也能精准并行。下面按完整搭建顺序展开。二、整体架构四层设计职责分明┌─────────────────────────────────────────────┐ │ 应用层Telegram 机器人 / 网页 / 数字人 │ ├─────────────────────────────────────────────┤ │ API层FastAPI/chat /add_urls /add_pdfs │ │ /add_texts WebSocket 流式 │ ├─────────────────────────────────────────────┤ │ 服务层LangChainChain/Memory/Tools/ │ │ Agent 情绪判断链 │ ├─────────────────────────────────────────────┤ │ 资源层Redis记忆 / Qdrant向量库 │ │ 大模型 API / 外部工具 API │ └─────────────────────────────────────────────┘三、API 层FastAPI 四个接口打天下服务端就一个核心文件四个 POST 接口fromfastapiimportFastAPI,WebSocket appFastAPI()app.post(/chat)# 主对话接口asyncdefchat(query:str):resultmaster.run(query)# Master 是 Agent 主类return{response:result}app.post(/add_urls)# 从 URL 学习知识asyncdefadd_urls(url:str):master.learn_from_url(url)return{status:ok}app.post(/add_pdfs)# 从 PDF 学习知识app.post(/add_texts)# 从文本学习知识关键依赖版本锁死这是踩坑换来的fastapi0.108.0 langchain0.1.10 langchain_core0.1.28 langchain_openai0.0.5 langchain_community0.0.25 redis最新 qdrant_client1.7.1 uvicorn0.23.2避坑要点LangChain 0.1 起拆分成了langchain-core、langchain-openai、langchain-community三个包老教程的from langchain.llms import ChatOpenAI写法已经过时。版本不锁三天就报错。四、Agent 主体Master 类 角色 Prompt 设计4.1 主类初始化fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportAgentExecutor,create_openai_tools_agentclassMaster:def__init__(self,tools):self.llmChatOpenAI(modelgpt-3.5-turbo-1106,temperature0,# 铁律严格遵循 PromptstreamingTrue,# WebSocket 流式返回需要)self.promptChatPromptTemplate.from_messages([(system,SYSTEM_PROMPT),# 角色设定(placeholder,{chat_history}),# 记忆占位符(human,{input}),(placeholder,{agent_scratchpad}),])self.agentcreate_openai_tools_agent(self.llm,tools,self.prompt)self.executorAgentExecutor(agentself.agent,toolstools,verboseTrue)避坑要点create_openai_tools_agent要求 tools至少传一个非空工具否则直接报错。开发初期可以先塞一个假工具占位再逐步替换成真工具。4.2 角色 Prompt人设即产品角色设定全部靠 Prompt 注入换一套 Prompt 就是另一个 Agent——这是 Agent 可扩展性的精髓SYSTEM_PROMPT你是陈大师一位精通阴阳五行、紫微斗数、八字测算的资深命理师。 你年约60岁曾是江西一带赫赫有名的江湖人士后因故左眼失明人称陈瞎子。 你性格豁达幽默说话直来直去但句句在理。 你只使用繁体字回复。遇到负面情绪的用户先安抚再解答。4.3 情绪判断链用 Chain 把模糊情绪变成确定性信号独立一个detect_emotion()方法用专用 Prompt 约束 LLM 只输出四类标签defdetect_emotion(self,text:str)-str:chainLLMChain(llmself.llm,promptEMOTION_PROMPT)emotionchain.run(text).strip().lower()self.emotionemotion# friendly / depressed / default / angryreturnemotion实测效果输入你好返回 friendly输入你真是个傻子返回 angry。情绪标签存到self.emotion后续语音合成、回复策略切换都能用——它用 Prompt 工程把模糊情绪转化为确定性信号为后续环节提供原子级控制开关是低成本实现高拟真交互的关键杠杆。4.4 工具调用链路用户视角把前面所有模块串起来一次完整的工具调用是这样的用户请求 → Agent 判断该用哪个工具 → 携带参数调用工具搜索 / 命理 API / 知识库 → 拿到观察结果Observation → Agent 结合结果生成最终回答五、工具体系tool 装饰器三步建一个工具5.1 实时搜索工具SerpAPIfromlangchain_core.toolsimporttoolfromlangchain_community.utilitiesimportSerpAPIWrappertooldefsearch(query:str):只有需要了解实时信息或不知道的事情时才使用这个工具。resultSerpAPIWrapper().run(query)print(实时搜索结果:,result)returnresult工具描述docstring决定 Agent 能不能正确选用工具——描述必须写清楚什么时候该用这是 Agent 与普通函数最本质的区别。5.2 专业 API 工具参数校验不能省Agent 传进来的参数全是字符串调用专业 API八字测算、解梦等前必须做参数提取与校验——用一个小型 LLMChain 把用户输入转成结构化 JSONparam_chainLLMChain(llmllm,promptChatPromptTemplate.from_template(你是参数查询助手根据用户输入提取相关参数按 JSON 格式返回。\n输入{input}))tooldefbazi_calculate(text:str):用户要求测算八字时使用。paramsjson.loads(param_chain.run(text))# 提取年月日时等参数resprequests.post(https://api.example.com/bazi,jsonparams)returnresp.json()5.3 本地知识库工具RAG把专业领域知识企业规范、业务文档向量化存 Qdrant工具内做相似度检索tooldefknowledge_search(query:str):回答企业内部专业知识问题时使用。returnvectorstore.similarity_search(query,k5)避坑要点工具密钥SerpAPI Key 等用环境变量管理千万别写死在代码里。生产环境建议加访问审计和请求频控单点泄露不至于全系统失陷。六、长时记忆Redis 持久化 智能压缩大模型无状态对话记录必须外挂。方案Redis 存历史 超阈值自动摘要压缩fromlangchain_community.chat_message_historiesimportRedisChatMessageHistoryfromlangchain.memoryimportConversationTokenBufferMemorydefget_memory(session_iddefault):historyRedisChatMessageHistory(session_idsession_id,urlredis://localhost:6379/0)# 超过 10 条记录 → LLM 提炼摘要清空旧记录iflen(history.messages)10:summaryllm.invoke(f提炼以下对话的要点\n{history.messages})history.clear()history.add_ai_message(summary)returnConversationTokenBufferMemory(chat_memoryhistory,human_prefix用户,ai_prefix助手,memory_keyhistory,max_token_limit1000)注意记忆要生效Prompt 模板里必须预留{chat_history}占位符见 4.1 节否则记忆注入不进去——这是最隐蔽的坑。七、RAG 学习能力给 Agent 喂 URL不用微调学习的本质是 RAGURL → HTML 转文本 → 切分 → 向量化 → 存库 → 检索。加载器可换PDF 用 PyPDFLoader后续步骤通用fromlangchain_community.document_loadersimportUnstructuredURLLoaderfromlangchain.text_splitterimportRecursiveCharacterTextSplitterfromlangchain_openaiimportOpenAIEmbeddingsfromlangchain_community.vectorstoresimportQdrantdeflearn_from_url(url:str):docsUnstructuredURLLoader(urls[url]).load()textsRecursiveCharacterTextSplitter(chunk_size800,chunk_overlap50).split_documents(docs)Qdrant.from_documents(texts,OpenAIEmbeddings(),collection_namelearning_knowledge)避坑要点同一个向量库内用不同 collection 隔离知识门类物流文档、业务规范各一个集合检索精度明显高于混在一起。80% 以上的场景靠 RAG 就够了不需要微调——微调是最后手段不是默认选项。八、生产部署Docker Compose LangSmith8.1 Docker 保证环境一致version:3services:redis:image:redis:latestvolumes:[redis-data:/data]# 数据卷升级不丢历史ai-server:build:.environment:-REDIS_URLredis://redis:6379/0ports:[9000:9000]depends_on:[redis]volumes:redis-data:避坑要点记忆数据必须挂数据卷volumes否则docker-compose down一次Redis 里的聊天记录全没——这个坑我们上线第一周就踩了。8.2 LangSmith 生产追踪配置三个环境变量即可LANGCHAIN_TRACING_V2true LANGCHAIN_API_KEY你的key LANGCHAIN_PROJECT项目名注意只有invoke()调用会被追踪run()** 不会**。追踪面板能看每次 LLM 调用的耗时、Token 消耗、工具调用链和错误日志——生产环境排障必备。我们靠它定位过一个 30 秒慢响应最后发现是文档摘要链卡住了光靠肉眼猜根本查不出来。8.3 为什么不用 LangServe社区有现成的 LangServeLangChain 官方 Server 方案自带 Playground 调试界面和自动路由生成看着很香。但我们最终坚持手写 FastAPI原因很现实LangServe 是较新的开源项目版本迭代激进不建议直接上生产单体架构耦合度高项目结构会被框架绑架我们只需要 4 个接口手写 20 行代码的事不值得引入依赖。选型原则核心逻辑自主掌控——工具类库可以随便用但服务骨架这种主航道别把控制权交给快速演进的框架。九、扩展从文本到多端接入与 AI 数字人Agent 服务搭好后横向扩展非常快我们实际做了两件事① 多端接入。同一个/chat接口套不同的客户端壳就能换平台——Telegram 机器人用 telebot 包BotFather 申请 Token、网页、企业微信原理完全一致。服务端只管对话客户端只管收发职责解耦。② AI 数字人 Demo。在 Agent 之上叠加 TTS 虚拟形象Agent 生成文本 → 调用语音合成 API → WebRTC 推流 → 前端video播放。架构上是三层拼接LangChain Agent大脑 语音/形象 API表达 WebRTC传输数字人 Demo 验证了一个结论Agent 的能力边界不在模型而在你能接多少表达通道——文本、语音、形象每多一层应用形态就上一个大台阶。十、写在最后这套架构最大的价值是回答了Agent 到底怎么落地别让 LLM 干它不擅长的事确定性计算、权限校验、SQL 生成交给代码只让它干最擅长的语义理解、路径决策、内容生成再用 Harness 程序化校验兜底。低代码工作流平台看着省事但在语义模糊、高并发、强实时场景下抽象层级过高会让你失去对调用链路和状态流转的控制。如果重来一遍我会更早做三件事① 先把所有成熟路径封装成原子工具② 给每个工具写清楚什么时候用③ 用 LangSmith 从第一天就开始埋点。这三件事做对了Agent 的工程化之路会顺畅很多。如果你也在搭生产级 Agent欢迎评论区聊聊你的架构。下面几个方向想看哪个留言告诉我Agent 多工具并行的调度策略与冲突处理Harness 程序化校验的完整落地SQL 安全、权限拦截语音合成 数字人与 Agent 的集成实战
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
