企业官网建设流程全解析

1. 别急着装系统，先搞懂你手里的“遥控器”长什么样

AI Agent这个词最近像雨后春笋一样冒出来，满屏都是“LangChain上手”“Dify一键部署”“CrewAI三步搭建智能体”，新手点开教程第一行就写着“pip install langchain”，转行的朋友刚学完Python基础，对着终端敲下命令，心里想的是“终于要起飞了”，结果卡在环境报错、模型API密钥填错、提示词写得像作文题——三天过去，连个能回答“今天天气怎么样”的小机器人也没跑起来。我带过27个零基础转行的学员，其中21个在前三天就卡死在“框架安装”这一步，不是因为笨，而是方向错了：你还没搞清遥控器上每个按钮是干啥的，就急着给电视换主板。AI Agent不是一套现成软件，而是一套“让大模型能自主思考、调用工具、记住上下文、分步完成任务”的能力组合。它背后有四个不可拆解的齿轮：感知（理解用户意图）、决策（规划下一步动作）、行动（调用API/工具/代码）、记忆（维护对话状态与长期知识）。这四个齿轮缺一不可，但新手最容易犯的错，就是把“决策”和“行动”当成全部，一上来就猛啃LangChain的Chain类、AgentExecutor怎么初始化、Tool怎么注册——就像学开车先背发动机原理图，却没摸过方向盘。真正该优先建立的，是“问题映射能力”：看到一个需求，比如“帮我查下周北京到上海的 cheapest 航班并订一张”，你能立刻拆出它需要哪几块能力？是否要联网搜索？是否要调用机票API？是否要处理时间格式？是否要对比价格？这些判断不依赖任何框架，只依赖你对AI能力边界的理解。我建议所有新手和转行者，先花3小时做一件事：用纯自然语言，在纸上写下5个你日常会交给助理做的事（比如“整理会议纪要发邮件”“根据销售数据生成周报图表”“帮孩子查恐龙资料做PPT”），然后挨个标出每件事里，哪些步骤必须靠人脑判断（如“判断哪段是重点”），哪些可以交给AI执行（如“提取日期”“生成Markdown”），哪些必须调外部系统（如“发邮件”“查数据库”）。这个过程不写一行代码，但能让你瞬间看清：所谓AI Agent，本质是把人类工作流里“可自动化”的环节，用AI+工具链重新串起来。框架只是胶水，不是骨架；胶水再高级，粘不住没设计好的结构。

2. 四块基石：不碰代码也能建立Agent思维模型

很多教程一上来就甩出“ReAct”“Plan-and-Execute”“Reflection”这些术语，配上流程图和英文论文截图，新手一看就懵。其实这些高大上的架构，底层全是四个最朴素的逻辑模块在打架。我把它们叫作“Agent四基石”，不用装任何包，用纸笔就能推演清楚：

2.1 感知层：别让AI“听不懂人话”，先练“翻译官”基本功

感知层的核心任务，是把用户模糊、口语化、甚至带情绪的输入，转化成AI能精准执行的指令。这不是靠调用某个API，而是训练你的“提示词翻译”能力。举个真实例子：用户说“帮我看看昨天那个项目汇报PPT里，王总提的三个问题，现在解决到哪一步了？”——这句话里藏着至少4层信息：时间（昨天）、载体（PPT）、人物（王总）、动作（提问题）、目标（查进度）。如果直接喂给大模型，它大概率会问“哪个项目？PPT在哪？进度标准是什么？”。真正的感知层工作，是人工先把这句话“翻译”成结构化指令：“从[指定路径]的PPT文件中，提取‘王总提问’页的所有文本；识别其中编号为1、2、3的问题；在[共享文档链接]中查找这三个问题对应的‘当前状态’字段值”。这个翻译过程，就是感知层的设计。新手常犯的错，是以为“写得越详细越好”，结果写出200字的提示词，AI反而抓不住重点。实测下来最稳的结构是“角色+任务+约束+示例”四要素：

• 角色：你是一个资深项目经理，熟悉公司所有项目文档规范
• 任务：从PPT中提取王总提出的三个问题，并匹配共享文档中的解决状态
• 约束：只返回JSON格式，字段为question_id（1/2/3）、question_text、status（未开始/进行中/已完成）
• 示例：{"question_id":1,"question_text":"服务器扩容方案是否已确认？","status":"进行中"}
  这套结构我在教转行学员时，要求他们用手机备忘录反复练习10次不同场景（比如查快递、比价、写周报），直到能30秒内写出合格提示词。你会发现，80%的Agent失败，根源都在感知层没做好“翻译”。

2.2 决策层：别迷信“自动规划”，先画出你的“任务流程图”

决策层决定Agent下一步做什么。网上吹得神乎其技的“自主规划”，本质上就是if-else的升级版。新手最大的幻觉，是以为Agent能像人一样“灵光一闪”想出新方案。现实是：所有靠谱的决策，都基于预设的规则树或有限状态机。比如做一个“旅行助手Agent”，它的决策逻辑绝不是“AI自己决定要不要查天气”，而是明确的分支：

• 用户输入含“航班”“火车”“酒店”等关键词 → 进入【预订流程】
• 用户输入含“景点”“攻略”“推荐” → 进入【信息查询流程】
• 用户输入含“预算”“多少钱”“贵不贵” → 进入【比价流程】
• 其他输入 → 进入【澄清流程】（追问具体城市/日期/人数）
  这个流程图，就是决策层的骨架。我让学员用draw.io画出自己想做的Agent流程图，强制要求：每个节点必须标注触发条件（如“检测到‘明天’关键词”）、输出动作（如“调用天气API”）、失败兜底（如“API超时则返回‘暂无法获取，请稍后再试’”）。很多人画到第三步就卡住——不是技术问题，是根本没想清楚业务逻辑。有个做电商客服转行的学员，最初写的决策流是“用户问售后→查订单→处理退款”，结果上线后发现用户90%的提问是“我的快递到哪了”，而她的流程里根本没有物流查询分支。后来她蹲守客服群3天，记录200条真实对话，才补全了“物流状态查询”这个关键分支。决策层不是AI生成的，是你对业务场景的深度还原。

2.3 行动层：工具不是越多越好，先搞定“最小可用工具集”

行动层负责调用外部能力，比如查天气、发邮件、读文件。新手常陷入“工具焦虑”：看到LangChain支持50种工具，就想全装上。结果调试三天，连一个“发送测试邮件”的功能都跑不通。真相是：90%的Agent，只需要3类工具就能跑通核心场景：

• 信息获取类：HTTP请求（查天气/新闻）、文件读取（读PDF/Excel）、数据库查询（查订单表）
• 内容生成类：大模型API（生成摘要/改写文案）、代码执行（运行Python脚本算数据）
• 系统交互类：邮件发送（SMTP）、消息推送（企业微信/钉钉Webhook）、日历创建（Google Calendar API）
  关键不是“能调多少”，而是“调得稳不稳”。我给学员定的硬性标准：在本地用curl或Postman手动调通每个工具的API，拿到真实返回数据，再写进代码。比如调用天气API，必须亲眼看到返回的JSON里有temperature字段；调用邮件API，必须真收到一封测试邮件。有个学员非要先写Agent框架再调试工具，结果卡在SMTP认证失败，折腾两天才发现是邮箱密码填错了——这种低级错误，手动调通一次就永不再犯。工具封装的黄金法则是：每个工具函数必须包含三件事——输入校验（如检查城市名非空）、异常捕获（网络超时/返回错误码）、标准化输出（统一返回dict，字段名固定）。别小看这点，它决定了后续所有模块能否可靠衔接。

2.4 记忆层：别堆“向量数据库”，先理清“什么该记，记多久”

记忆层让Agent记住上下文，避免每次对话都从零开始。新手一听“记忆”，马上想到Chroma、Pinecone这些向量库，急着配embedding模型。但绝大多数场景，根本用不上向量检索。记忆的本质是“状态管理”，分三种：

• 短期记忆：单次对话内的上下文（如用户刚说“把刚才的表格转成柱状图”，这里的“刚才”指前一条消息）。用简单的变量或session存储即可，连数据库都不用。
• 中期记忆：用户偏好与习惯（如“张经理喜欢用Excel格式，李总监要PDF”）。用键值对存用户ID→偏好配置，Redis或本地JSON文件足够。
• 长期记忆：跨会话的业务知识（如公司产品手册、客户历史投诉记录）。这才是向量库的用武之地，但前提是：你得先有结构化知识源。我见过最典型的坑，是学员花一周搭好Chroma，往里塞了1000页PDF，结果用户问“我们的退款政策是什么”，AI返回的却是PDF里某页的无关段落——因为没做知识切片和元数据标注。真正该优先建的，是“记忆策略表”：列清楚每类信息的生命周期（如用户偏好保存30天）、更新机制（如每次对话后自动更新）、访问权限（如财务数据仅限管理员查看）。这张表比写100行向量入库代码更重要。记忆不是技术问题，是信息治理问题。

3. 实操路线图：从“手写伪代码”到“可运行最小Agent”

明确了四基石，接下来是落地节奏。我给所有新手设计了一条“无框架通关路径”，全程不装LangChain/Dify，用最原始的方式验证逻辑，确保每一步都踩在实地上：

3.1 第一天：用Notepad写“伪代码Agent”，打通全流程

目标：不写Python，只用文字描述一个完整Agent工作流，覆盖四基石。以“会议纪要助手”为例：

• 感知：用户输入“整理昨天下午3点市场部会议的录音转文字稿” → 提取关键信息：时间（昨天15:00）、部门（市场部）、输入类型（文字稿）、动作（整理）
• 决策：判断“整理”指摘要生成 → 进入摘要流程；若用户说“生成待办事项”，则进入待办提取流程
• 行动：调用大模型API，prompt为“你是一个专业会议秘书，请从以下文字中提取3个核心结论和5个待办事项，用Markdown返回”
• 记忆：将本次会议主题（如“Q3营销预算调整”）存入用户偏好，下次提到“Q3预算”自动关联此会议
  这个过程强制你把模糊想法变成可执行步骤。很多学员写到“调用大模型API”这一步就卡住——不知道该传什么参数、怎么处理返回。这时正好切入第二天的学习。

3.2 第二天：用Requests手写API调用，搞定“行动层”实操

目标：用Python requests库，不依赖任何框架，调通一个真实API。选最简单的场景：调用免费天气API（如Open-Meteo）。步骤：

1. 注册API Key（很多免费服务无需Key，直接用）
2. 构造URL：https://api.open-meteo.com/v1/forecast?latitude=39.9&longitude=116.4&current=temperature_2m,wind_speed_10m&timezone=Asia/Shanghai
3. 用requests.get()发起请求，打印response.json()
4. 解析返回，提取current.temperature_2m字段
   关键细节：

• 必须加timeout参数（requests.get(url, timeout=5)），否则网络卡顿会阻塞整个Agent
• 必须捕获异常（try...except requests.exceptions.RequestException），不能让一次失败导致程序崩溃
• 返回数据要清洗：temperature = round(data['current']['temperature_2m'], 1)，避免小数位过多影响阅读
  我让学员故意把经纬度写错，观察API返回的error message，再根据文档找到正确字段名。这个过程比看10篇教程更管用——你亲手摸到了“行动”的温度。

3.3 第三天：用纯Prompt实现“感知+决策”，绕过复杂框架

目标：不用任何Agent库，仅靠精心设计的Prompt，让大模型完成多步任务。以“日报生成器”为例：
用户输入：“汇总今天销售数据，重点标出华东区增长超20%的产品”
传统做法：写代码解析Excel→筛选数据→调大模型生成报告。但新手可以先走捷径：把数据和指令一起喂给模型。

• Prompt设计：

你是一个销售数据分析助手。我会给你一份今日销售数据（CSV格式），请按以下步骤处理： 1. 计算每个区域的销售额总和 2. 计算华东区各产品的增长率（对比昨日） 3. 找出华东区增长率>20%的产品 4. 生成一份简洁日报，包含：总销售额、华东区TOP3增长产品（名称+增长率）、一句总结 数据：[此处粘贴CSV内容]

• 实操要点：
  • CSV数据必须精简（不超过50行），否则模型会丢失信息
  • 明确步骤编号，强制模型按序执行，避免跳步
  • 要求输出格式（如“用---分隔各部分”），方便后续程序解析
    我让学员用ChatGPT和Claude同时跑，对比结果差异。发现Claude对增长率计算更准，但ChatGPT的日报语言更自然——这让他们明白：模型选择也是决策的一部分。

3.4 第四天：用Session变量实现“记忆”，拒绝过度工程

目标：用最简方式实现对话状态记忆。场景：“多轮订餐Agent”，用户先说“我要点餐”，再问“有什么推荐”，最后说“我要宫保鸡丁”。

• 代码骨架：

# 模拟用户session user_sessions = {} def handle_message(user_id, message): if user_id not in user_sessions: user_sessions[user_id] = {"state": "init", "order": {}} session = user_sessions[user_id] if session["state"] == "init" and "点餐" in message: session["state"] = "choosing" return "请问想吃中餐、西餐还是日料？" elif session["state"] == "choosing" and "中餐" in message: session["cuisine"] = "中餐" session["state"] = "confirming" return "推荐宫保鸡丁、麻婆豆腐，要哪个？" elif session["state"] == "confirming" and "宫保鸡丁" in message: session["order"]["dish"] = "宫保鸡丁" return f"已下单{session['order']['dish']}，预计30分钟送达！" else: return "抱歉，没听懂，请再说一遍。" # 测试 print(handle_message("user1", "我要点餐")) # 请问想吃中餐... print(handle_message("user1", "中餐")) # 推荐... print(handle_message("user1", "我要宫保鸡丁")) # 已下单...

• 为什么不用数据库：单机测试阶段，内存变量完全够用；强行上Redis，反而增加故障点。等用户量真上来（比如日活1万），再考虑扩展。
• 关键经验：session里存的不是“历史消息”，而是“当前状态+关键变量”。状态机比聊天记录更可靠。

3.5 第五天：组装“最小可行Agent”，跑通端到端

目标：把前四天的模块拼起来，做一个能实际工作的Agent。选“个人待办助手”：用户说“把会议纪要里的待办事项加入我的日程”，Agent要：

1. 感知：识别“会议纪要”“待办事项”“日程”关键词
2. 决策：判断需提取待办+创建日历事件
3. 行动：调用大模型提取待办（Prompt含示例），再调用Google Calendar API创建事件
4. 记忆：记录本次操作，下次用户说“同步最新待办”时自动执行

• 核心代码结构：

def todo_agent(user_input): # 感知：简单关键词匹配（后期可升级为LLM分类） if "会议纪要" in user_input and "日程" in user_input: # 行动1：提取待办（调用大模型） todo_list = extract_todos_from_meeting(user_input) # 前一天写的函数 # 行动2：创建日历事件（调用Calendar API） for todo in todo_list: create_calendar_event(todo) return f"已为您创建{len(todo_list)}个日程事件！" else: return "请提供会议纪要文本，或说'帮我整理待办'" # 测试 print(todo_agent("把下面会议纪要的待办加入日程：1. 周五前提交方案 2. 下周一约客户"))

• 避坑提醒：

  提示：不要追求一次性完美。第一天只实现“提取待办”，第二天再加“创建日历”，第三天加“错误重试”。我见过太多人想一步到位，结果卡在OAuth认证里两周。
  注意：所有API调用必须加日志（logging.info(f"Calendar event created: {todo}")），否则出问题时连错在哪都不知道。

这条路径走完，你手里就有了一个真正能干活的Agent，虽然代码只有200行，但它包含了所有核心逻辑。此时再学LangChain，你会一眼看出：LLMChain对应感知层，RouterChain对应决策层，Tool对应行动层，ConversationBufferMemory对应记忆层——框架不再是黑箱，而是你亲手造过的轮子的加强版。

4. 框架选型实战指南：什么时候该用，什么时候该扔

当你的最小Agent跑通后，才会真正理解框架的价值和陷阱。别被“主流架构”“最佳实践”这些词绑架，框架只是工具，选型要看三个硬指标：你要解决的问题复杂度、团队技术栈、未来扩展需求。我按真实场景拆解：

4.1 LangChain：适合“快速验证想法”，但慎用于生产

LangChain的定位很清晰：降低LLM应用开发门槛的胶水框架。它的优势在于“开箱即用”的Tool生态（天气、维基、SQL等）和Chain组合能力。但问题也很致命：

• 过度抽象：AgentExecutor封装了太多细节，新手调试时根本不知道中间哪一步挂了。比如调用Wikipedia Tool失败，错误堆栈里全是LangChain内部代码，你得翻源码才能定位是网络问题还是参数问题。
• 性能黑洞：Chain嵌套层数一多，响应时间指数级增长。我测过一个5层Chain的Agent，平均响应4.2秒；而手写同样逻辑的代码，只要1.1秒。
• 版本地狱：0.x到1.x的API大改，很多教程代码直接失效。
  适用场景：
• 内部PoC（概念验证），2天内要给老板演示效果
• 教学场景，让学生快速看到“Agent能做什么”
• 简单工具链（如“查天气+生成文案”两步）
  避坑指南：

提示：永远不要用initialize_agent()这种全自动函数。必须手动构建AgentExecutor，明确指定tools、llm、agent_kwargs，否则出问题时连入口都找不到。
注意：禁用verbose=True上线环境，它会把所有中间步骤打到日志，海量日志直接拖垮磁盘IO。

4.2 Dify：适合“非技术产品经理”，但定制性差

Dify是可视化Agent构建平台，最大价值是让不懂代码的人也能搭Agent。它的后台其实是LangChain+自研调度器，但对用户完全隐藏。优势在于：

• 拖拽式编排，决策流、提示词、工具绑定全图形化
• 内置RAG引擎，上传PDF自动切片向量化
• 一键发布为API或Web App
  致命短板：
• 黑盒调试：流程跑不通？只能看最终输出，看不到中间步骤。比如RAG召回不准，你没法知道是切片策略问题还是embedding模型问题。
• 成本失控：每个API调用都经过Dify代理，多一层转发，延迟+100ms起；且免费版限制并发数，流量一上来就排队。
• 锁定风险：所有逻辑绑在Dify平台，迁移到自有系统要重写80%代码。
  适用场景：
• 市场/运营人员快速搭建客服Bot原型
• 需要快速交付给业务方试用（如HR用Agent筛简历）
• RAG场景简单（文档结构统一、查询意图明确）
  避坑指南：

提示：Dify的“知识库”不是万能的。上传合同PDF后，用户问“违约金怎么算”，它可能返回条款原文，但不会自动提取数字。必须配合“提示词工程”：在系统提示里写明“从合同中提取违约金百分比数值，只返回数字，不解释”。
注意：别信“自动优化”宣传。它的RAG默认用text-embedding-ada-002，对中文支持弱，换成bge-large-zh后召回率提升40%，但这需要手动改配置，官方文档根本不提。

4.3 CrewAI：适合“多Agent协作”，但学习曲线陡峭

CrewAI专攻“多智能体协作”，理念是把复杂任务拆给不同Agent（如Researcher、Writer、Reviewer）分工完成。它的核心价值在于：

• 角色驱动：每个Agent有明确role/goal/tools，天然适配业务流程
• 任务编排：Crew类自动管理Agent间通信、结果聚合
• 异步执行：支持Agent并行工作，适合耗时任务（如同时查10个竞品）
  现实挑战：
• 资源消耗大：每个Agent都独立调用LLM，10个Agent同时跑，API费用翻10倍。
• 协调成本高：Agent间传递信息靠字符串，没有类型安全，一个Agent返回格式错，整个流程崩。
• 调试地狱：日志里全是“Agent A finished”, “Agent B started”，你根本不知道A返回的中间结果是不是B想要的。
  适用场景：
• 需要模拟人类协作流程（如“市场分析→竞品报告→PPT生成”三步）
• 任务天然可并行（如同时分析多个数据源）
• 团队有LLM调优经验，能控制每个Agent的prompt精度
  避坑指南：

提示：永远给Agent加“输出格式约束”。比如Researcher Agent必须返回JSON，字段为{summary: string, sources: [string]}，否则Writer Agent拿到乱码就废了。
注意：禁用verbose=True，CrewAI的详细日志会把每个Agent的完整prompt和response都打出来，10个Agent的日志量轻松破GB。

4.4 自研框架：适合“稳定生产环境”，但需技术储备

当你的Agent日调用量超5000次/天，或涉及核心业务（如金融风控、医疗咨询），就必须自研。这不是为了炫技，而是为可控性：

• 性能可控：去掉所有中间件，API响应压到300ms内
• 安全可控：敏感数据不出内网，审计日志精确到字段级
• 迭代可控：业务逻辑变更，当天就能上线，不用等框架更新
  最小自研架构：
• 路由层：Flask/FastAPI接收请求，按关键词分发到不同Agent
• 核心层：每个Agent是独立Python模块，含perceive()decide()act()remember()方法
• 工具层：统一Tool Registry，所有工具实现execute(input: dict) -> dict接口
• 记忆层：Redis存session，PostgreSQL存长期知识
  关键经验：

提示：自研不等于从零造轮子。HTTP客户端用requests，序列化用Pydantic，日志用structlog——这些成熟库比自己写稳定100倍。
注意：必须设计“降级开关”。比如天气API不可用时，自动返回“暂无法获取天气，请稍后再试”，而不是让整个Agent报错。开关要能热更新，运维一键关闭某个模块。

5. 新手避坑实录：那些没人告诉你的“血泪教训”

最后分享我在带学员过程中，高频出现的12个真实问题，附排查思路和解决方案。这些问题，90%的教程都不会写，但你一定会踩：

5.1 问题1：Agent总是“答非所问”，反复确认同一问题

现象：用户说“查北京天气”，Agent回复“请问您想查哪个城市的天气？”
根因：感知层没做好意图识别，把确定性指令当成了开放式提问。
排查：

• 检查Prompt里是否明确写了“用户输入是确定性指令，不是提问”
• 查看大模型返回的JSON里，intent字段是否为空或错误
• 用curl手动调模型API，输入相同文本，看原始返回
  解决：
• 在感知层加“意图校验”：如果模型返回的intent不是预设值（如weathernewsemail），强制返回错误提示
• 用规则兜底：输入含“天气”“温度”“预报”等词，直接设intent=weather，不依赖模型

5.2 问题2：调用API时频繁超时，日志显示“Connection reset”

现象：天气API调用成功率不到50%，重试3次才成功
根因：没设timeout，或网络环境DNS解析慢
排查：

• 用time curl -v https://api.xxx.com测真实耗时
• 查看服务器DNS配置（cat /etc/resolv.conf）
• 检查是否用了国内镜像源（如pip源）但API在国外
  解决：
• requests必须加timeout=(3, 7)（连接3秒，读取7秒）
• 服务器加DNS缓存：sudo apt install dnsmasq，配置/etc/dnsmasq.conf
• 关键API走代理（公司内网通常有HTTP代理，配置os.environ['HTTP_PROXY']）

5.3 问题3：向量检索返回无关结果，比如搜“退款政策”返回“产品保修”

现象：RAG知识库上传了《用户协议》PDF，但检索“退款”返回的全是“保修期”段落
根因：文本切片策略错误，没按语义分割
排查：

• 用pdfplumber打开PDF，检查切片后的文本块是否跨段落
• 查看embedding向量相似度，是否真的接近
  解决：
• 改用unstructured库切片，它能识别标题/列表/表格结构
• 切片长度设为512字符，重叠128字符，避免断句
• 在检索时加“重排序”：用cross-encoder对Top5结果二次打分

5.4 问题4：Agent在多轮对话中“失忆”，忘了用户刚说的关键信息

现象：用户说“我要订去上海的机票”，Agent问“哪天出发”，用户答“明天”，Agent又问“去哪”
根因：记忆层没把关键实体（上海、明天）存入session
排查：

• 打印session变量，看citydate字段是否存在
• 检查感知层是否提取了这些实体
  解决：
• 在感知层加实体识别：用spaCy或正则提取地点时间数量等
• session里存entities = {"city": "上海", "date": "2024-06-15"}，决策层直接读取

5.5 问题5：部署后CPU飙升100%，进程卡死

现象：本地跑得好好的，部署到服务器后，top看Python进程占满CPU
根因：没关debug模式，或日志级别太低
排查：

• ps aux | grep python看进程数
• strace -p <pid>看进程在忙什么系统调用
  解决：
• Flask加debug=False，FastAPI加debug=False
• 日志级别设为INFO，禁用DEBUG
• 加进程监控：supervisorctl配置autostart=truestartretries=3

5.6 问题6：大模型返回格式错乱，JSON解析失败

现象：Agent调用模型生成JSON，但返回里混着Markdown符号，json.loads()报错
根因：模型没严格遵守格式约束
排查：

• 打印原始response.text，看是否含json包裹
• 检查prompt是否写了“只返回纯JSON，不要任何解释”
  解决：
• 用正则提取JSON：json_str = re.search(r'\{.*\}', response.text, re.DOTALL).group()
• 加JSON校验：try: json.loads(json_str) except: return {"error": "invalid json"}

5.7 问题7：工具调用失败，但日志没报错，Agent静默失败

现象：用户说“发邮件”，Agent返回“已发送”，但收件箱没收到
根因：工具函数没抛异常，错误被吞了
排查：

• 在工具函数里加print("sending email...")
• 查SMTP服务器日志（如/var/log/mail.log）
  解决：
• 所有工具函数必须raise Exception，不能只return False
• Agent层捕获异常，返回用户友好提示：“邮件发送失败，请检查邮箱配置”

5.8 问题8：RAG检索慢，10秒才返回结果

现象：上传100页PDF，用户问问题，等10秒才有响应
根因：向量库没建索引，或embedding维度太高
排查：

• chroma_client.get_collection("docs").count()看文档数
• time命令测单次检索耗时
  解决：
• Chroma加HNSW索引：collection.add(..., ids=ids, metadatas=metadatas, embeddings=embeddings)
• embedding模型换轻量版：bge-small-zh比bge-large-zh快3倍，精度损失<5%

5.9 问题9：Agent在高峰期大量报错，错误日志全是“Rate limit exceeded”

现象：每天上午10点，Agent错误率飙升，日志全是API限频
根因：没做请求限流，所有请求直冲LLM API
排查：

• 查API提供商Dashboard，看每分钟请求数
• 用redis统计每IP每分钟请求数
  解决：
• 加令牌桶限流：pip install redis+from redis import Redis
• 配置max_requests=10/minute，超限返回429 Too Many Requests

5.10 问题10：部署后中文乱码，返回一堆符号

现象：本地正常，服务器上返回“你好”变成“”
根因：服务器locale没设中文
排查：

• locale命令看当前编码
• cat /etc/default/locale
  解决：
• sudo locale-gen zh_CN.UTF-8
• echo 'LANG="zh_CN.UTF-8"' | sudo tee -a /etc/default/locale
• 重启服务

5.11 问题11：Agent生成内容带偏见，比如“程序员都是男性”

现象：用户问“谁是著名程序员”，Agent只列出男性名字
根因：训练数据偏差，或prompt没约束多样性
排查：

• 查模型文档，看是否声明了bias mitigation
• 测试不同prompt：“列出5位著名程序员，性别比例均衡”
  解决：
• 在prompt里加约束：“请确保名单中至少2位女性程序员”
• 用post-processing过滤：if "male" in name.lower(): skip

5.12 问题12：上线后用户反馈“不如直接问ChatGPT”，Agent价值感低

现象：做了3个月，用户留存率<10%，都说“自己问GPT更快”
根因：没解决真实痛点，只是把ChatGPT包装了一层
排查：

• 查用户行为日志：哪些功能使用率<1%，哪些报错率>50%
• 做用户访谈：“你希望Agent帮你做什么，但现在做不到？”
  解决：
• 聚焦一个垂直场景：比如“只做跨境电商客服”，不求全能
• 加真实业务集成：对接ERP查库存、对接CRM查客户历史，让用户感受到“比ChatGPT多知道10件事”

这些问题，我每个都带着学员亲手解决过。最深的体会是：AI Agent不是技术竞赛，而是对业务理解的深度考试。你不需要成为框架专家，但必须比业务方更懂他们的流程、痛点和数据。当你能指着一份销售报表，说出“这里第3列的数值，Agent应该自动填到CRM的哪个字段”，你就真正入门了。