1. 为什么“20+真实场景”才是Agent开发的真正分水岭

1.1 从Demo到生产：Agent开发最大的坑不在模型

我接触AI智能体开发这两年多，见过太多人卡在同一个地方：跟着教程跑通了一个天气查询Agent，兴奋得不行，结果一放到真实业务里就各种翻车。问题出在哪？不是模型不够强，而是真实场景里的边界条件、异常处理、状态管理、并发控制这些东西，教程里根本不会讲。

“AI智能体Agent实战开发：20+真实场景全链路教程”这个标题之所以值得认真拆解，是因为它点出了一个核心矛盾——Agent开发的知识密度，90%集中在场景适配层，而不是模型调用层。你调用一次大模型API可能只需要三行代码，但要让这个Agent在客服场景里稳定处理多轮对话、在数据分析场景里正确编排工具链、在代码审查场景里精准定位问题，那是完全不同的工程量级。

我自己的经验是，第一个Agent Demo大概花了我一个下午，但第一个能上生产的Agent，前后迭代了将近三周。差距就在场景细节里。

1.2 全链路的真正含义：从意图识别到结果交付

所谓“全链路”，很多人理解成“从开发到部署”，这个理解太窄了。在Agent实战语境下，全链路应该拆成五个环节：

• 意图理解层：用户说了一句话，Agent要判断这是任务指令、闲聊、还是需要澄清的模糊需求
• 规划编排层：把复杂任务拆成子步骤，决定哪些用LLM推理、哪些调工具、哪些查知识库
• 工具执行层：实际调用API、查数据库、读写文件、操作浏览器
• 状态管理层：维护对话历史、任务进度、中间结果，处理超时和重试
• 结果交付层：格式化输出、错误兜底、人工接管触发

这五层里，只有第一层和第三层跟“模型能力”强相关，其余三层全是工程问题。而20+真实场景的价值，就是把这五层在不同业务下的具体表现全部摊开给你看。

1.3 适合谁来学：三类人的不同切入点

如果你是后端开发转Agent，你的优势在工程架构，短板在对LLM不确定性的直觉。建议从“工具调用+状态管理”类场景切入，比如订单查询Agent、工单流转Agent。

如果你是前端开发转Agent，你对交互和流式输出天然敏感，建议从“对话式UI+多轮澄清”类场景入手，比如智能客服、表单填写助手。

如果你是产品/运营转Agent，你懂业务痛点，建议先跑通扣子、Dify这类低代码平台的全流程，再回头补Python和API调用的课。

不管哪类人，核心原则是一样的：先跑通一个完整场景的闭环，再横向扩展场景数量。不要一上来就追求“20+”，先把1个场景做到能上生产，后面的19个就是复制和微调。

2. 核心架构拆解：Agent的“大脑-手脚-记忆”怎么设计

2.1 规划模块：ReAct不是唯一解，但是最稳的起点

Agent架构里最核心的就是规划模块。目前主流方案有几种：ReAct（推理+行动交替）、Plan-and-Execute（先规划再执行）、Reflexion（带自我反思）。我实测下来的结论是：ReAct适合80%的场景，Plan-and-Execute适合步骤明确的长任务，Reflexion适合对准确率要求极高的场景但成本翻倍。

ReAct的核心逻辑用伪代码表示就是：

while not task_completed: thought = llm.reason(context, tools_description) if thought.requires_tool: action = thought.tool_name observation = execute_tool(action, thought.params) context.append(observation) else: final_answer = thought.answer break

这个循环看起来简单，但实际写的时候有几个关键决策点。第一，最大迭代次数设多少？我一般设8-10次，超过就强制返回“需要人工介入”。第二，工具描述怎么写？这是最容易被忽视的环节。工具描述不是写给人看的，是写给LLM看的，必须包含：功能说明、参数类型、必填/选填、返回值格式、什么情况下该用这个工具。我见过太多人工具描述就写一句“查询天气”，LLM根本不知道怎么调。

第三，observation太长怎么办？比如工具返回了一个巨大的JSON，直接塞回context会爆token。我的做法是加一个摘要层：如果observation超过500 token，先用小模型压缩成关键信息再回传。

2.2 工具层设计：别把API文档直接丢给LLM

工具层的设计质量直接决定Agent的可用性。我总结了一个“工具设计三原则”：

原则一：一个工具只做一件事。不要设计“用户管理工具”这种大而全的，要拆成“查询用户信息”“修改用户邮箱”“冻结用户账号”三个独立工具。LLM在选工具时，选项越明确，准确率越高。

原则二：参数设计要防呆。比如日期参数，不要只写“date: string”，要写“date: string, 格式YYYY-MM-DD, 例如2026-01-15”。再比如枚举参数，把所有可能值列出来。我实测过，加了格式示例后，工具调用成功率从67%提升到91%。

原则三：返回值要结构化。不要返回一大段自然语言，返回JSON。但JSON的key要用自然语言命名，比如{"temperature": 25, "weather": "晴", "suggestion": "适合户外活动"}，这样LLM后续推理时更容易理解。

工具注册的代码结构大概长这样：

tools = [ { "name": "query_order", "description": "根据订单号查询订单状态和物流信息。当用户询问订单进度、物流位置时使用此工具。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，格式为ORD开头加12位数字，例如ORD202601150001" } }, "required": ["order_id"] } } ]

2.3 记忆模块：短期靠context，长期靠向量库，但别混用

Agent的记忆分两种：短期记忆（当前对话的上下文）和长期记忆（跨对话的用户偏好、历史事实）。

短期记忆的实现相对直接，就是把对话历史按轮次拼进prompt。但这里有个坑：不是所有历史都值得保留。我的做法是保留最近5轮完整对话，更早的做摘要压缩。摘要的prompt大概是“用一句话概括以下对话的核心信息和结论”。

长期记忆就复杂了。常见方案是向量数据库（如Chroma、Milvus）+ embedding模型。但我要提醒一个容易踩的坑：不要把短期记忆和长期记忆混在同一个检索空间里。短期记忆是“刚才说了什么”，长期记忆是“这个用户是谁、有什么偏好”，两者的检索逻辑完全不同。混在一起会导致Agent把当前对话的临时信息当成用户永久偏好。

我的实践方案是分开存储：短期记忆用滑动窗口+摘要，长期记忆用“用户画像”结构，每次对话开始时把用户画像注入system prompt，对话结束时用LLM提取新信息更新画像。

2.4 编排层：多Agent协作的三种模式

当场景复杂到单个Agent搞不定时，就需要多Agent编排。目前主流三种模式：

我大部分项目用的是主从模式。总控Agent负责意图识别和任务分派，执行Agent各自负责一个领域。关键设计点是：总控Agent不执行具体任务，只做路由和结果汇总。这样每个执行Agent的prompt可以写得非常专注，准确率自然高。

3. 20+场景的横向拆解：哪些场景值得优先做

3.1 信息查询类：最容易上手，但别小看异常处理

信息查询类Agent是最常见的入门场景，包括天气查询、订单查询、知识库问答、新闻摘要等。这类场景的技术栈相对简单：意图识别+工具调用+结果格式化。

但我要说的是，这类场景的难点全在异常处理。用户问“我的订单到哪了”，但没给订单号怎么办？订单号给了但查不到怎么办？查到了但物流信息为空怎么办？这些分支如果不在prompt和代码里显式处理，Agent就会胡言乱语。

我的处理模板是：

def handle_query(user_input, context): # 第一步：提取必要参数 params = extract_params(user_input, required=["order_id"]) if not params.get("order_id"): # 尝试从上下文推断 order_id = infer_from_context(context) if not order_id: return "请提供您的订单号，格式为ORD开头加12位数字。" # 第二步：调用工具 try: result = query_order(order_id) except OrderNotFound: return f"未找到订单{order_id}，请确认订单号是否正确。" except TimeoutError: return "查询超时，请稍后重试。" # 第三步：格式化输出 if not result.get("logistics"): return f"订单{order_id}状态为{result['status']}，暂无物流信息。" return format_logistics(result)

这个模板的核心思想是：每个可能失败的点都有明确的兜底话术。不要指望LLM自己处理异常，它处理不了。

3.2 任务执行类：工具链编排是核心难点

任务执行类场景包括：自动填表、邮件发送、日程安排、文件整理、数据录入等。这类场景的特点是步骤多、依赖强、容错低。

以“自动安排会议”为例，完整链路是：解析参会人和时间→查日历找空闲→发邀请→确认回复→更新日历。每一步都可能失败，而且失败后需要回滚。

我的经验是：用状态机管理任务执行。每个步骤是一个状态，状态转移条件明确写出来。不要用LLM自由发挥，LLM只负责“理解用户意图”和“生成最终回复”，中间的步骤执行全部用代码控制。

class MeetingScheduler: states = ["PARSE_INPUT", "CHECK_CALENDAR", "SEND_INVITE", "AWAIT_CONFIRM", "UPDATE_CALENDAR", "DONE"] def transition(self, current_state, result): if current_state == "PARSE_INPUT" and result.success: return "CHECK_CALENDAR" elif current_state == "CHECK_CALENDAR" and result.has_conflict: return "PARSE_INPUT" # 重新协商时间 # ... 其他转移逻辑

3.3 内容生成类：质量控制的三个层次

内容生成类场景包括：文案撰写、代码生成、报告总结、翻译润色等。这类场景的挑战不是“能不能生成”，而是“生成的质量稳不稳定”。

我总结了三层质量控制：

第一层：结构约束。用JSON schema或模板强制输出结构。比如生成周报，先定义好{ "本周完成": [], "下周计划": [], "风险项": [] }，让LLM填充。

第二层：事实校验。生成的内容里如果有数据、日期、人名，必须回查原始资料确认。我一般会加一个校验Agent，专门检查生成内容中的事实性陈述。

第三层：风格对齐。用few-shot示例让LLM模仿特定风格。比如“请参考以下三段历史文案的风格，生成新的产品描述”。

3.4 代码相关类：从代码审查到自动修复

代码类Agent是当前企业级应用的热点。典型场景包括：代码审查、bug定位、单元测试生成、代码重构建议。

这类场景对准确率要求极高，因为错误的建议会浪费开发时间。我的做法是：Agent只做“发现问题”和“给出建议”，不做“自动修改”。自动修改的风险太大，一旦改错，排查成本远高于人工修改。

代码审查Agent的prompt设计要点：

• 明确审查维度：安全性、性能、可读性、边界条件
• 每个问题必须给出：问题位置、问题描述、严重程度、修改建议
• 不确定的问题标注“需人工确认”，不要强行给结论

3.5 多轮对话类：状态追踪和意图漂移

多轮对话类场景包括：智能客服、销售助手、教学辅导等。这类场景最大的挑战是意图漂移——用户说着说着就换话题了，或者在一个话题里不断补充细节。

我的解决方案是维护一个“对话状态对象”：

dialog_state = { "current_intent": "查询订单", "slots": {"order_id": "ORD202601150001"}, "history_intents": ["问候", "查询订单"], "pending_questions": ["是否需要修改收货地址？"] }

每轮对话后更新这个状态对象。当用户输入新消息时，先判断是“继续当前意图”还是“切换新意图”。判断逻辑可以用LLM，也可以用规则引擎，我一般用LLM+规则兜底。

4. 实操全流程：从零搭建一个可上生产的Agent

4.1 环境准备与框架选型

先明确技术栈。我的推荐组合是：

• 语言：Python 3.11+（生态最全）
• 框架：LangChain或LlamaIndex（快速原型），生产环境建议自研轻量框架
• 模型：DeepSeek、通义千问、GLM等国内可用模型
• 向量库：Chroma（开发）、Milvus（生产）
• 部署：Docker + FastAPI

为什么不推荐直接用LangChain上生产？因为LangChain抽象层太厚，出问题时排查困难，而且版本迭代快，升级容易崩。我的做法是用LangChain做原型验证，确认方案可行后，用原生API重写核心逻辑。

环境安装：

pip install openai chromadb fastapi uvicorn pydantic

4.2 第一个Agent：订单查询助手完整实现

我从最经典的订单查询场景开始，把完整代码和设计思路讲清楚。

第一步：定义工具

import json def query_order(order_id: str) -> dict: """模拟订单查询""" # 实际项目中这里调数据库或API mock_db = { "ORD202601150001": { "status": "已发货", "logistics": "顺丰速运 SF1234567890", "estimated_arrival": "2026-01-17" } } return mock_db.get(order_id, {})

第二步：定义工具描述

tools_schema = [ { "type": "function", "function": { "name": "query_order", "description": "根据订单号查询订单状态和物流信息。当用户询问订单进度、物流位置、预计到达时间时使用此工具。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，格式为ORD开头加12位数字，例如ORD202601150001" } }, "required": ["order_id"] } } } ]

第三步：构建Agent循环

from openai import OpenAI client = OpenAI(api_key="your-key", base_url="your-base-url") def run_agent(user_input, max_turns=8): messages = [ {"role": "system", "content": "你是一个订单查询助手。用户询问订单相关问题时，调用query_order工具。如果用户没有提供订单号，礼貌地请用户提供。如果查询不到订单，告知用户并请其确认订单号。"}, {"role": "user", "content": user_input} ] for turn in range(max_turns): response = client.chat.completions.create( model="deepseek-chat", messages=messages, tools=tools_schema, tool_choice="auto" ) msg = response.choices[0].message if msg.tool_calls: for tool_call in msg.tool_calls: if tool_call.function.name == "query_order": args = json.loads(tool_call.function.arguments) result = query_order(args["order_id"]) messages.append(msg) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result, ensure_ascii=False) }) else: return msg.content return "抱歉，处理超时，请稍后重试或联系人工客服。"

这段代码看起来简单，但有几个关键设计点值得展开。

关键点一：system prompt里写了异常处理指令。“如果用户没有提供订单号，礼貌地请用户提供”——这句话让Agent在缺少参数时不会瞎编。“如果查询不到订单，告知用户并请其确认”——这句话让Agent在工具返回空结果时不会硬编一个答案。

关键点二：max_turns=8是安全阀。防止Agent陷入无限循环。超过8轮还没结果，直接返回兜底话术。

关键点三：tool返回空dict时，LLM会看到{}，结合system prompt的指令，它会生成“未找到该订单”的回复。如果你返回的是None或报错，LLM可能会困惑。

4.3 加入记忆和上下文管理

上面的版本是无状态的，每次对话都是全新的。要支持多轮对话，需要加入历史管理：

class ConversationManager: def __init__(self, max_history=10): self.history = [] self.max_history = max_history def add_message(self, role, content): self.history.append({"role": role, "content": content}) if len(self.history) > self.max_history: self.compress_history() def compress_history(self): # 保留最近5轮，更早的做摘要 old = self.history[:-5] recent = self.history[-5:] summary = summarize(old) # 调LLM做摘要 self.history = [{"role": "system", "content": f"历史对话摘要：{summary}"}] + recent def get_messages(self, system_prompt): return [{"role": "system", "content": system_prompt}] + self.history

这里的关键决策是摘要的粒度。太粗会丢信息，太细等于没压缩。我的经验是：摘要保留“用户身份、已确认的事实、未完成的任务”，丢弃“寒暄、重复确认、中间推理过程”。

4.4 并发处理：Agent怎么扛住同时100个请求

这是生产环境和Demo环境最大的区别。Demo里你一个人慢慢聊，生产环境可能同时有几百个用户。

核心思路是无状态化+异步。Agent本身不保存状态，状态存在Redis里。每个请求进来，从Redis加载状态，处理完写回Redis。

import asyncio from fastapi import FastAPI import redis app = FastAPI() r = redis.Redis() @app.post("/chat") async def chat(user_id: str, message: str): # 加载状态 state = r.get(f"agent_state:{user_id}") context = json.loads(state) if state else {"history": []} # 异步处理 result = await process_message(message, context) # 保存状态 r.set(f"agent_state:{user_id}", json.dumps(result["new_context"]), ex=3600) return {"reply": result["reply"]}

几个注意事项：

• Redis的过期时间要设，一般1小时。用户1小时没说话，状态清空，下次重新开始。
• LLM调用要设超时，一般30秒。超时后返回兜底话术，不要让请求一直挂着。
• 并发限流要做，用信号量控制同时调LLM的请求数，防止把API配额打爆。

4.5 部署与监控：上线只是开始

Agent部署后，必须监控几个核心指标：

监控数据要定期review，特别是兜底话术触发率高的场景，说明Agent在这个场景下能力不足，需要优化prompt或补充工具。

5. 常见问题与排查技巧实录

5.1 Agent不调用工具，直接编答案

这是最常见的问题。原因通常是：工具描述不够清晰，或者system prompt没有强调“必须调用工具”。

排查步骤：

1. 检查工具描述是否包含“当用户...时使用此工具”的触发条件
2. 检查system prompt是否写了“不要编造信息，必须通过工具查询”
3. 如果还不行，在工具描述里加一句“此工具是获取该信息的唯一途径”

我遇到过一个极端案例：Agent死活不调用天气工具，后来发现是工具描述里写了“可以查询天气”，LLM理解成“可选”。改成“必须使用此工具查询天气”后，问题解决。

5.2 工具调用参数错误

LLM生成的参数格式不对，比如日期格式、枚举值、必填项缺失。

解决方案：

• 在参数描述里给示例："date": "格式YYYY-MM-DD，例如2026-01-15"
• 在代码里做参数校验和自动修正：比如日期格式不对，尝试用dateutil解析
• 如果参数缺失，不要直接报错，让Agent追问用户

5.3 多轮对话中意图丢失

用户说了三轮，Agent忘了第一轮说的关键信息。

解决方案：

• 每轮对话后，用LLM提取“关键信息”存入状态对象
• 下一轮开始时，把状态对象注入system prompt
• 关键信息包括：用户身份、已确认的事实、未完成的任务

5.4 响应太慢

Agent响应慢通常是因为：工具调用串行、LLM推理时间长、上下文太长。

优化手段：

• 无依赖的工具调用并行执行
• 用流式输出，让用户先看到部分结果
• 压缩上下文，把不必要的历史对话摘要掉
• 用更小的模型做意图识别，大模型只做最终生成

5.5 常见问题速查表

6. 从20+场景中提炼的通用设计模式

6.1 场景分类与对应架构

做了这么多场景后，我发现Agent架构可以按场景类型归纳：

查询类：ReAct + 单工具 + 参数校验。核心是工具描述要清晰，异常处理要全面。

执行类：状态机 + 多工具 + 回滚机制。核心是步骤可控，每步有明确的成功/失败判定。

生成类：模板约束 + 事实校验 + 风格对齐。核心是输出结构化，质量可量化。

对话类：状态对象 + 意图追踪 + 槽位填充。核心是状态管理，防止意图漂移。

协作类：主从编排 + 结果汇总 + 冲突解决。核心是路由准确，汇总逻辑清晰。

6.2 提示词工程的实战心得

写Agent的prompt和写普通对话的prompt完全是两回事。我的几条心得：

心得一：system prompt要写“禁止事项”。比如“禁止编造订单信息”“禁止在未确认用户身份时执行操作”。LLM对禁止性指令的遵循度比鼓励性指令高。

心得二：few-shot示例要覆盖边界情况。不要只给正常流程的示例，要给“参数缺失”“工具返回空”“用户中途换话题”的示例。

心得三：输出格式用JSON schema约束。不要用自然语言描述格式，直接用JSON schema，LLM对结构化约束的遵循度更高。

心得四：prompt要版本管理。每次修改prompt都记录版本号和修改原因，方便回滚和对比效果。

6.3 成本控制：别让Agent烧钱

Agent的成本主要来自LLM调用。一个复杂任务可能调用5-10次LLM，成本是普通对话的10倍。

控制手段：

• 意图识别用小模型，只有最终生成用大模型
• 缓存常见问题的答案，相似问题直接返回缓存
• 设置token上限，单次调用不超过4000 token
• 监控每日消耗，超过预算自动降级到小模型

我实测过一个客服Agent，优化前日均消耗200元，优化后降到60元，核心就是意图识别从大模型换成了小模型+规则引擎。

6.4 安全边界：Agent不能做什么

Agent再智能，也有不能碰的边界：

• 不能执行不可逆操作：删除数据、发送邮件、转账，必须人工确认
• 不能访问敏感数据：用户密码、支付信息，Agent不应该接触
• 不能做医疗/法律建议：这类建议必须由专业人士给出
• 不能绕过权限：Agent的权限应该和当前用户一致，不能提权

我的做法是在工具层加权限校验，Agent调用工具时，工具内部检查当前用户是否有权限执行该操作。Agent本身不做权限判断，它只负责“想做什么”，权限系统负责“能不能做”。

7. 进阶方向：从单Agent到多Agent协作

7.1 什么时候需要多Agent

单Agent搞不定的信号：

• 任务涉及多个专业领域，一个prompt装不下
• 需要不同角色从不同角度审视同一问题
• 任务步骤太多，单Agent的上下文放不下
• 需要并行处理多个子任务

7.2 多Agent通信协议设计

多Agent协作的核心是通信协议。我一般用“消息总线”模式：

class MessageBus: def __init__(self): self.queues = {} def register(self, agent_name): self.queues[agent_name] = asyncio.Queue() async def send(self, to, message): await self.queues[to].put(message) async def receive(self, agent_name): return await self.queues[agent_name].get()

每个Agent有自己的消息队列，Agent之间通过消息总线通信。总控Agent负责分派任务和汇总结果。

7.3 多Agent的常见坑

坑一：无限对话。两个Agent互相发消息，停不下来。解决方案：设最大消息轮次，超过就强制结束。

坑二：责任扩散。每个Agent都以为别人会处理，结果没人处理。解决方案：每个任务必须指定唯一负责人。

坑三：信息不一致。不同Agent拿到的上下文不同，导致结论矛盾。解决方案：维护一个共享的“事实库”，所有Agent从这里读取事实。

8. 学习路线与资源推荐

8.1 分阶段学习路线

第一阶段（1-2周）：跑通单Agent+单工具。推荐从扣子或Dify开始，可视化搭建，快速理解Agent的基本概念。

第二阶段（2-4周）：用Python+LangChain实现多工具Agent。重点理解ReAct循环、工具描述、异常处理。

第三阶段（1-2月）：加入记忆、状态管理、并发处理。开始接触生产级问题。

第四阶段（持续）：多Agent协作、成本优化、安全边界。在实际项目中积累经验。

8.2 值得深入研究的开源项目

• LangChain：生态最全，适合快速原型
• LlamaIndex：RAG场景更强
• AutoGen：多Agent协作框架
• CrewAI：角色扮演式多Agent

我的建议是：不要贪多，选一个深入用。LangChain和LlamaIndex选一个，AutoGen和CrewAI选一个。用熟了再横向对比。

8.3 我个人的踩坑清单

最后分享几个我踩过的坑，希望能帮你省点时间：

• 不要用LangChain的AgentExecutor上生产，抽象层太厚，出问题难排查
• 工具描述一定要写触发条件，不要只写功能
• system prompt里一定要写禁止事项
• 多轮对话一定要维护状态对象，不要只靠历史消息
• 并发一定要做限流，不然API配额分分钟打爆
• 监控一定要做，不然出了问题都不知道
• 成本一定要控制，不然月底账单会让你怀疑人生

这些经验都是在实际项目中一点点积累的，有些坑踩一次就够了，希望你看完能少走弯路。Agent开发这个领域变化很快，但核心的工程思路是稳定的：理解场景、设计架构、处理异常、控制成本、保证安全。把这几点做好，20+场景也好，200+场景也好，都是可以复制的。