拒绝“玩具”Demo如何构建生产级 Agent 系统并落地大家好我是你们的老朋友一名在代码堆里摸爬滚打多年的程序员。最近 LLM大语言模型的热度居高不下很多团队都在尝试接入 AI 能力。但我发现一个普遍现象大多数项目还停留在“把 LLM 调通”的 Demo 阶段。一旦试图将其应用到真实的业务场景比如医疗、金融、企业内网问题就接踵而至回答幻觉严重、响应极慢、Token 费用爆炸、甚至因为一次错误的工具调用导致数据事故。今天我想和大家深入聊聊如何自建一个 Agent 系统并将其做到真正的“生产级”落地一句话核心企业级 Agent 系统本质上不是“把 LLM 调通”而是**“围绕 LLM 构建完整的软件工程体系”**。这包括架构设计、工具调用治理、RAG 优化、记忆管理、工作流编排以及可观测性。下面我们将拆解这六大关键步骤。一、宏观视角生产级 Agent 的整体架构很多初学者容易把 Agent 想象成一个简单的while True循环。但在生产环境中我们需要分层解耦。通常我会将架构拆分为以下层级支撑体系用户层Agent Layer / 路由与决策Workflow / Orchestrator / 编排引擎Tools / RAG / Memory / 能力层Model Layer / LLM 基座Observability Evaluation / 监控与评估Guardrails / 安全护栏这个架构的核心在于LLM 只是大脑而周围的工程体系才是身体。二、第一步明确 Agent 边界职责分离很多项目失败的根本原因是Agent 职责不清。如果你试图让一个 Agent 同时负责“理解意图”、“查询数据库”、“撰写报告”和“检查错误”它的上下文会迅速混乱成功率大幅下降。在生产环境中我们通常采用多 Agent 协作模式明确定义每个角色的边界Agent 角色核心职责典型输入/输出Router Agent流量分发判断用户意图用户Query - 目标 Agent IDKnowledge Agent专注知识检索与问答问题 - RAG 结果 答案Data Agent结构化数据分析SQL/Python Code - 图表/结论Report Agent长文本生成与格式化数据片段 - Markdown/PDF报告QA Agent最终输出质量检查草稿 - 修正后的最终稿最佳实践不要迷信“全能型 Agent”。小而专的 Agent 组合远比一个大而全的 Agent 稳定。三、第二步设计健壮的 Tool Calling 体系生产级的 Agent一定不是纯聊天其核心价值在于Tool Use工具使用。无论是查数据库、调 HIS/LIS 接口还是发送 Webhook都需要一个统一的Tool Registry工具注册中心来管理。为什么需要 Tool Registry如果直接在 Prompt 里硬编码工具描述一旦工具参数变更整个系统都要重新调试。我们需要统一管理Tool Schema标准化的 JSON Schema 描述。权限控制谁可以调用这个工具超时与重试网络波动时的兜底策略。参数校验在发给 LLM 之前或之后强制校验参数合法性。代码示例一个简单的工具装饰器我们可以用 Python 装饰器来简化工具的注册和元数据管理importjsonfromtypingimportDict,AnyclassToolRegistry:def__init__(self):self.tools{}defregister(self,name:str,description:str,params_schema:Dict):defdecorator(func):self.tools[name]{function:func,schema:{name:name,description:description,parameters:params_schema}}returnfuncreturndecoratordefexecute(self,tool_name:str,args:Dict[str,Any])-Any:iftool_namenotinself.tools:raiseValueError(fTool{tool_name}not found)# 这里可以加入日志、权限校验、超时控制等逻辑print(f[LOG] Executing tool:{tool_name}with args:{args})returnself.tools[tool_name][function](**args)# 初始化工具注册中心registryToolRegistry()# 注册一个查询患者信息的工具registry.register(nameget_patient_info,description根据患者ID获取基本信息,params_schema{type:object,properties:{patient_id:{type:string,description:患者的唯一标识ID}},required:[patient_id]})defget_patient_info(patient_id:str)-str:# 模拟数据库查询returnjson.dumps({id:patient_id,name:张三,age:30})# 执行工具resultregistry.execute(get_patient_info,{patient_id:P1001})print(result)四、第三步构建高精度的 RAG 系统在企业场景如医疗、法律、金融中没有 RAG检索增强生成Agent 几乎不可落地。因为模型参数里的知识是滞后的且容易产生幻觉。但普通的 RAG 往往效果不佳生产级 RAG 需要关注以下三个关键点1. Chunk Strategy分块策略不要简单地按固定字符数切割推荐做法使用Parent-Child Chunking。Parent Chunk较大的段落保留完整语境。Child Chunk较小的片段用于向量检索匹配。原理检索时命中 Child但返回给 LLM 的是其对应的 Parent从而保证上下文完整性。2. Hybrid Search混合检索企业数据中充满了专有名词如药品名、检验指标缩写。纯向量检索对关键词不敏感纯关键词检索无法理解语义。推荐做法BM25关键词 Vector向量。使用 Reciprocal Rank Fusion (RRF) 算法合并两路搜索结果。3. Rerank重排序这是提升精度的“杀手锏”。向量检索召回 Top 50 个文档片段。使用Cross Encoder 模型如 BGE-Reranker对这 50 个片段与问题进行相关性打分。取 Top 5 高分片段注入 Prompt。原始文档智能分块Embedding向量数据库用户提问混合检索关键词索引候选集 Top 50Rerank 重排序模型最终上下文 Top 5大模型生成五、第四步上下文与 Memory 治理生产系统最大的敌人是Token 爆炸和信息污染。如果不加治理随着对话轮数增加Prompt 会越来越长不仅贵而且会让模型“注意力分散”忽略关键指令。我们需要对 Memory 进行分层治理记忆类型作用实现方式Short-term当前会话的近期交互滑动窗口Sliding Window只保留最近 N 轮Long-term用户画像、偏好存入向量库或 KV 存储按需检索Episodic历史重要事件摘要定期调用 LLM 对旧对话进行总结压缩Semantic领域长期知识固化在 System Prompt 或 RAG 知识库中常见做法Conversation Summary当对话超过一定长度时触发后台任务将早期的对话压缩成一段摘要defcompress_history(messages:list)-str: 将历史消息压缩为摘要 summary_promptf请总结以下对话的关键信息和用户意图\n{messages}# 调用 LLM 生成摘要summaryllm.invoke(summary_prompt)returnsummary.content核心原则不是把所有历史都塞进 Prompt而是按需召回Memory Retrieval。六、第五步Workflow 编排从线性到图状简单的问答可以用AgentExecutor线性执行。但复杂的业务流程如先查数据 - 再分析 - 如果异常则报警 - 最后写报告需要更强大的编排能力。这里强烈推荐使用LangGraph或类似的状态机框架而不是简单的 Chain。为什么选择 LangGraph能力简单 AgentExecutorLangGraph (State Graph)状态管理弱难以追踪中间状态强显式维护 State循环与分支支持有限原生支持DAG 和循环并行执行困难原生支持并行节点Human-in-the-loop难以实现原生支持中断与人工介入容错与恢复弱强可从断点继续执行场景示例带人工审核的报告生成流程需要修改通过GenerateDraftHumanReviewEditApproveSendReport在这种流程中Agent 生成初稿后流程暂停等待人类专家在 UI 上确认或修改。确认后流程继续。这种“人机协同”是生产级落地的标配。七、总结与建议构建生产级 Agent 系统是一场从“魔法”到“工程”的修行。架构先行拆分 Router、Worker、QA 等角色不要试图用一个 Prompt 解决所有问题。工具治理建立统一的 Tool Registry做好权限、日志和异常处理。RAG 精细化混合检索 Rerank 是提升准确率的必经之路。记忆瘦身定期摘要按需召回控制 Token 成本。流程编排使用 LangGraph 等工具处理复杂逻辑和人机协同。可观测性必须记录每一次 LLM 的输入输出、Token 消耗和延迟否则无法优化。最后的一句忠告不要为了用 Agent 而用 Agent。如果一个简单的规则引擎或搜索功能能解决问题那就不要用 LLM。Agent 的价值在于处理非结构化、不确定性和需要推理的复杂任务。希望这篇文章能为你构建企业级 Agent 系统提供清晰的路径。如果有具体的技术细节想探讨欢迎在评论区留言参考资料LangGraph 官方文档LlamaIndex RAG 最佳实践Microsoft AutoGen FrameworkRAGAS: Evaluation framework for RAG
拒绝“玩具”Demo：如何构建生产级 Agent 系统并落地？
拒绝“玩具”Demo如何构建生产级 Agent 系统并落地大家好我是你们的老朋友一名在代码堆里摸爬滚打多年的程序员。最近 LLM大语言模型的热度居高不下很多团队都在尝试接入 AI 能力。但我发现一个普遍现象大多数项目还停留在“把 LLM 调通”的 Demo 阶段。一旦试图将其应用到真实的业务场景比如医疗、金融、企业内网问题就接踵而至回答幻觉严重、响应极慢、Token 费用爆炸、甚至因为一次错误的工具调用导致数据事故。今天我想和大家深入聊聊如何自建一个 Agent 系统并将其做到真正的“生产级”落地一句话核心企业级 Agent 系统本质上不是“把 LLM 调通”而是**“围绕 LLM 构建完整的软件工程体系”**。这包括架构设计、工具调用治理、RAG 优化、记忆管理、工作流编排以及可观测性。下面我们将拆解这六大关键步骤。一、宏观视角生产级 Agent 的整体架构很多初学者容易把 Agent 想象成一个简单的while True循环。但在生产环境中我们需要分层解耦。通常我会将架构拆分为以下层级支撑体系用户层Agent Layer / 路由与决策Workflow / Orchestrator / 编排引擎Tools / RAG / Memory / 能力层Model Layer / LLM 基座Observability Evaluation / 监控与评估Guardrails / 安全护栏这个架构的核心在于LLM 只是大脑而周围的工程体系才是身体。二、第一步明确 Agent 边界职责分离很多项目失败的根本原因是Agent 职责不清。如果你试图让一个 Agent 同时负责“理解意图”、“查询数据库”、“撰写报告”和“检查错误”它的上下文会迅速混乱成功率大幅下降。在生产环境中我们通常采用多 Agent 协作模式明确定义每个角色的边界Agent 角色核心职责典型输入/输出Router Agent流量分发判断用户意图用户Query - 目标 Agent IDKnowledge Agent专注知识检索与问答问题 - RAG 结果 答案Data Agent结构化数据分析SQL/Python Code - 图表/结论Report Agent长文本生成与格式化数据片段 - Markdown/PDF报告QA Agent最终输出质量检查草稿 - 修正后的最终稿最佳实践不要迷信“全能型 Agent”。小而专的 Agent 组合远比一个大而全的 Agent 稳定。三、第二步设计健壮的 Tool Calling 体系生产级的 Agent一定不是纯聊天其核心价值在于Tool Use工具使用。无论是查数据库、调 HIS/LIS 接口还是发送 Webhook都需要一个统一的Tool Registry工具注册中心来管理。为什么需要 Tool Registry如果直接在 Prompt 里硬编码工具描述一旦工具参数变更整个系统都要重新调试。我们需要统一管理Tool Schema标准化的 JSON Schema 描述。权限控制谁可以调用这个工具超时与重试网络波动时的兜底策略。参数校验在发给 LLM 之前或之后强制校验参数合法性。代码示例一个简单的工具装饰器我们可以用 Python 装饰器来简化工具的注册和元数据管理importjsonfromtypingimportDict,AnyclassToolRegistry:def__init__(self):self.tools{}defregister(self,name:str,description:str,params_schema:Dict):defdecorator(func):self.tools[name]{function:func,schema:{name:name,description:description,parameters:params_schema}}returnfuncreturndecoratordefexecute(self,tool_name:str,args:Dict[str,Any])-Any:iftool_namenotinself.tools:raiseValueError(fTool{tool_name}not found)# 这里可以加入日志、权限校验、超时控制等逻辑print(f[LOG] Executing tool:{tool_name}with args:{args})returnself.tools[tool_name][function](**args)# 初始化工具注册中心registryToolRegistry()# 注册一个查询患者信息的工具registry.register(nameget_patient_info,description根据患者ID获取基本信息,params_schema{type:object,properties:{patient_id:{type:string,description:患者的唯一标识ID}},required:[patient_id]})defget_patient_info(patient_id:str)-str:# 模拟数据库查询returnjson.dumps({id:patient_id,name:张三,age:30})# 执行工具resultregistry.execute(get_patient_info,{patient_id:P1001})print(result)四、第三步构建高精度的 RAG 系统在企业场景如医疗、法律、金融中没有 RAG检索增强生成Agent 几乎不可落地。因为模型参数里的知识是滞后的且容易产生幻觉。但普通的 RAG 往往效果不佳生产级 RAG 需要关注以下三个关键点1. Chunk Strategy分块策略不要简单地按固定字符数切割推荐做法使用Parent-Child Chunking。Parent Chunk较大的段落保留完整语境。Child Chunk较小的片段用于向量检索匹配。原理检索时命中 Child但返回给 LLM 的是其对应的 Parent从而保证上下文完整性。2. Hybrid Search混合检索企业数据中充满了专有名词如药品名、检验指标缩写。纯向量检索对关键词不敏感纯关键词检索无法理解语义。推荐做法BM25关键词 Vector向量。使用 Reciprocal Rank Fusion (RRF) 算法合并两路搜索结果。3. Rerank重排序这是提升精度的“杀手锏”。向量检索召回 Top 50 个文档片段。使用Cross Encoder 模型如 BGE-Reranker对这 50 个片段与问题进行相关性打分。取 Top 5 高分片段注入 Prompt。原始文档智能分块Embedding向量数据库用户提问混合检索关键词索引候选集 Top 50Rerank 重排序模型最终上下文 Top 5大模型生成五、第四步上下文与 Memory 治理生产系统最大的敌人是Token 爆炸和信息污染。如果不加治理随着对话轮数增加Prompt 会越来越长不仅贵而且会让模型“注意力分散”忽略关键指令。我们需要对 Memory 进行分层治理记忆类型作用实现方式Short-term当前会话的近期交互滑动窗口Sliding Window只保留最近 N 轮Long-term用户画像、偏好存入向量库或 KV 存储按需检索Episodic历史重要事件摘要定期调用 LLM 对旧对话进行总结压缩Semantic领域长期知识固化在 System Prompt 或 RAG 知识库中常见做法Conversation Summary当对话超过一定长度时触发后台任务将早期的对话压缩成一段摘要defcompress_history(messages:list)-str: 将历史消息压缩为摘要 summary_promptf请总结以下对话的关键信息和用户意图\n{messages}# 调用 LLM 生成摘要summaryllm.invoke(summary_prompt)returnsummary.content核心原则不是把所有历史都塞进 Prompt而是按需召回Memory Retrieval。六、第五步Workflow 编排从线性到图状简单的问答可以用AgentExecutor线性执行。但复杂的业务流程如先查数据 - 再分析 - 如果异常则报警 - 最后写报告需要更强大的编排能力。这里强烈推荐使用LangGraph或类似的状态机框架而不是简单的 Chain。为什么选择 LangGraph能力简单 AgentExecutorLangGraph (State Graph)状态管理弱难以追踪中间状态强显式维护 State循环与分支支持有限原生支持DAG 和循环并行执行困难原生支持并行节点Human-in-the-loop难以实现原生支持中断与人工介入容错与恢复弱强可从断点继续执行场景示例带人工审核的报告生成流程需要修改通过GenerateDraftHumanReviewEditApproveSendReport在这种流程中Agent 生成初稿后流程暂停等待人类专家在 UI 上确认或修改。确认后流程继续。这种“人机协同”是生产级落地的标配。七、总结与建议构建生产级 Agent 系统是一场从“魔法”到“工程”的修行。架构先行拆分 Router、Worker、QA 等角色不要试图用一个 Prompt 解决所有问题。工具治理建立统一的 Tool Registry做好权限、日志和异常处理。RAG 精细化混合检索 Rerank 是提升准确率的必经之路。记忆瘦身定期摘要按需召回控制 Token 成本。流程编排使用 LangGraph 等工具处理复杂逻辑和人机协同。可观测性必须记录每一次 LLM 的输入输出、Token 消耗和延迟否则无法优化。最后的一句忠告不要为了用 Agent 而用 Agent。如果一个简单的规则引擎或搜索功能能解决问题那就不要用 LLM。Agent 的价值在于处理非结构化、不确定性和需要推理的复杂任务。希望这篇文章能为你构建企业级 Agent 系统提供清晰的路径。如果有具体的技术细节想探讨欢迎在评论区留言参考资料LangGraph 官方文档LlamaIndex RAG 最佳实践Microsoft AutoGen FrameworkRAGAS: Evaluation framework for RAG
