做九添菜菜这个项目的时候我一开始就在琢磨大模型API已经这么成熟为什么还要在它外面套一层Agent智能体这其实也是很多做Agent智能体开发实战的人会面临的第一道坎——不是技术不会而是搞不清Agent到底比裸调API多了什么价值。等到需求真正落下来我才意识到问题没这么简单——如果只是单轮问答大模型确实够用可一旦要它自己去查资料、算数据、调用外部工具、分步骤完成任务再靠人工把每个环节拼起来那就太累了。这个时候Agent就不再是锦上添花而是刚需。服范那边给我的要求很明确不仅要能跑通Demo还要能在真实业务里稳住。所以这篇文章我不打算只讲概念而是把整个开发过程按需求定位—技术选型—核心机制—代码实现—模型接入—工程排障—上线优化这条线完整拆开里面所有细节都是被线上环境逼出来的。如果你正在做AI应用开发或者准备从调API往Agent开发转型这篇应该能帮你省下不少试错时间。代码层面我用的是Python Flask模型侧同时兼容云端API和本地Ollama整体架构不复杂但每一层都有值得聊的取舍。1. 需求定位Agent智能体到底解决什么问题1.1 从一条简单需求说起服范那边最初提的需求听起来很简单做一个智能问答系统能对接内部知识库也能调用公司现有的订单查询接口。但真正聊起来才发现用户想要的不是一个聊天机器人而是一个能自己动手干活的数字员工——比如用户问这个月华东区的订单量和退款率是多少系统不能只是背一个知识库答案而要先去查询订单数据、做计算、再组织自然语言回复。这个流程如果靠写死规则来做每个新场景都要开发一套新逻辑根本不具备扩展性。这就是Agent智能体存在的意义把理解意图—规划步骤—调用工具—汇总结果这整条链路交给模型来驱动开发者只需要给Agent提供工具和能力边界。换句话说Agent不是回答问题的是完成任务的。这个定位上的差异直接决定了后续所有设计决策。1.2 和普通大模型调用的区别我后来总结了一个很直白的对比这个表虽然不够严谨但做技术方案已经够用普通大模型调用Agent智能体输入Prompt输出文字输入目标输出决策过程行动结果无状态每次独立有上下文、有记忆可多轮迭代不能主动调用工具通过Function Calling调用外部API、数据库、代码遇到复杂任务只会硬答会把任务拆解成子步骤逐步执行如果你的场景只是摘要、翻译、润色那直接调大模型就好没必要上Agent但凡涉及多步骤、多工具、动态规划Agent就比裸调API靠谱太多。这个认知帮我避开了很多团队容易犯的方向性错误一上来就堆框架结果根本不知道自己解决的是什么问题。1.3 项目边界哪些功能必须做哪些先不做做项目最怕一开始就铺太大。九添菜菜第一版我只圈了三个核心能力。第一多轮对话与上下文管理。用户可以在一个会话里连续追问Agent记得之前说过什么。第二工具调用。对接至少两个真实接口订单查询、知识库检索验证Function Calling的完整闭环。第三实时输出。因为Agent多步执行耗时较长必须让用户立刻看到进度所以流式输出是硬指标。至于多智能体协作、模型微调、复杂记忆向量化我全部放到第二阶段。这个决策后来被证明很正确——先打通主链路再谈锦上添花。一个很常见的开发悲剧是第一个版本就想着什么都要有最后连最核心的完成任务都没跑通。2. 技术选型为什么是Flask SSE 大模型API2.1 选型的第一性原理技术选型我不太喜欢追新。团队里有人提议上FastAPIWebSocket有人提议直接买一套RAG框架但我的判断是核心价值在Agent的编排逻辑不在网络框架。项目第一版甚至不需要数据库会话状态先放内存就好。所以我选了Flask。可能有朋友觉得Flask老但Flask的好处恰恰是少。它没有太多框架层面的约束所有请求处理逻辑都暴露在你自己手里。对于Agent这种需要高度自定义控制流的应用反而是优点。FastAPI的异步性能确实更好但我们当时所有上游大模型API都是同步阻塞的异步优势发挥不出来。等以后某个环节真的变成I/O密集瓶颈再单独抽出服务也不迟。2.2 SSE和WebSocket怎么选Agent的执行过程和聊天机器人不一样它不是一次response就结束的而是要经历多轮思考—行动—观察每一步都值得给用户一点反馈。如果全憋到最后才返回用户体验会非常崩溃因为大模型推理可能动辄十几秒。这里我选了SSEServer-Sent Events而不是WebSocket。原因有三个。第一SSE是单向的服务端往客户端推流正好符合模型—后端—前端的数据方向Agent内部虽然要多次调用上游但对浏览器而言只需要接收结果。第二SSE基于普通HTTP天然支持断线重连浏览器原生EventSource直接可用不需要额外库。第三WebSocket虽然也能做但要处理连接状态、心跳、消息帧复杂度高出不少对当前需求属于过度设计。2.3 前端中断abort与连接断开处理SSE有个很现实的坑用户等得不耐烦点停止前端怎么通知后端EventSource的默认行为是关闭连接但服务端不一定马上感知到如果后端还在傻傻地调大模型接口token就白烧了。我们最后采用了双保险前端用一个AbortController来主动断开连接同时向后端发一个HTTP POST的取消接口。后端收到取消请求后设置一个全局取消标记Agent在执行每个步骤前检查该标记一旦发现就立刻终止后续调用。这个方法比单纯依赖连接断开来得可靠因为某些代理环境下连接断开事件非常不可靠。后面代码示例里我会把这个机制完整贴出来。3. Agent核心机制提示词、Function Calling和记忆3.1 ReAct范式让模型学会循环Agent智能体的核心模式并不神秘思想源自ReAct——让模型交替执行推理和行动。用一句话概括不是让模型一次性吐出答案而是让它边想边做。我实现时用的是LangChain框架偷个懒不重复造轮子。但即使不用LangChain核心逻辑也可以手写维护一个消息列表每次循环把当前状态发给模型由模型决定是调用工具还是输出最终答案如果调用工具就把工具返回结果追加进消息列表然后开始下一轮。这个循环一直跑到模型认为任务完成。刚开始写这个循环时我的直觉是把调用工具和生成回答分成两个接口来做后来发现其实可以合并成一次模型请求让模型在响应里结构化地声明我要调用哪个工具、传什么参数后端解析这个声明执行工具再把结果塞回上下文。这样循环次数更少响应速度也更快。3.2 Function Calling的接口设计模型怎么知道有哪些工具可用靠的是Function Calling机制。OpenAI系的API支持在请求里传tools参数里面描述每个函数的名称、参数和用途。Qwen、DeepSeek等国产模型也兼容这套规范这造就了Agent开发的一个巨大便利——工具定义一次跨模型复用。我们第一版设计了三类工具订单查询接收日期、区域等参数返回汇总数据。知识库检索接收查询字符串返回文档片段。计算器处理一些简单数值计算避免模型算错数。工具定义最需要注意的是参数描述。模型不是人它不会猜参数含义所以每个参数的description要写清楚取值范围和格式。比如订单查询的start_date不能只写开始日期而要写成格式为YYYY-MM-DD表示查询范围的起始日期包含当天。这个细节决定了工具调用的成功率而且不需要微调模型——只改描述就能提升效果性价比极高。3.3 记忆管理从列表到裁剪Agent的记忆本质就是消息列表。第一版我只做了最简单的滑动窗口User Assistant Tool这三类消息按时间顺序排列超过窗口上限就把最老的删掉。这个办法很粗糙但对多数业务场景已经够用。真正麻烦的是工具返回内容过大。比如用户问华东区订单工具返回的可能是一张几百行的明细表这些内容全塞进上下文两三轮就把窗口烧完了。我后来加了一个摘要压缩把工具返回的明细先用模型做一次精简只抽取关键统计信息再进入长期上下文。这一步虽然多消耗一次模型调用但换来的是对话轮数大幅提升。这个思路有点像人脑的记忆机制——不是记住全部原始经历而是记住这件事大概发生了什么。4. 实战代码从后端到前端的Agent闭环4.1 服务端骨架与Agent调度我先把Flask的骨架写出来结构上分成两层API层和Agent核心层。API层负责接收HTTP请求和推送SSE事件Agent核心层负责和模型对话、调用工具。这样分离的好处是以后换WebSocket或者加消息队列核心逻辑不用动。简化版的后端结构是这样from flask import Flask, request, Response, stream_with_context from agent import run_agent import json app Flask(__name__) app.route(/chat, methods[POST]) def chat(): session_id request.json.get(session_id) user_input request.json.get(message) def event_stream(): for event in run_agent(session_id, user_input): yield fdata: {json.dumps(event, ensure_asciiFalse)}\n\n return Response( stream_with_context(event_stream()), mimetypetext/event-stream, headers{Cache-Control: no-cache, X-Accel-Buffering: no} )run_agent函数是一个生成器每产生一个事件就yield一次。SSE里每个事件以data:开头以两个换行符结尾浏览器端解析起来非常方便。我用的是状态码200因为某些代理环境对非200响应处理得不好而这个接口本来就该返回事件流不需要依赖状态码表达语义。4.2 事件格式让前端知道发生了什么Agent在运行过程中会产生多种类型的事件开始思考、调用工具、工具返回、最终答案。如果全部丢给前端前端就不知道该渲染什么。所以事件必须有统一的type字段。我定义了一套简单的规范{type: status, data: {stage: planning}} {type: tool_call, data: {name: query_order, args: {...}}} {type: tool_result, data: {name: query_order, summary: ...}} {type: token, data: {content: ...}} {type: done, data: {answer: ...}}前端拿到事件后根据type决定UI行为。这种自定义事件协议是SSE开发里最容易忽略的一环——很多教程只教你把大模型token推给前端但Agent场景远不止token必须提前设计好事件模型。一旦事件协议定清楚后面加新功能比如展示思考过程、显示置信度就只需要加新type不用动整个消息链路。4.3 前端EventSource与AbortController前端我用的是原生JavaScript没有引框架。这里有个坑必须先说明原生EventSource只支持GET请求而我们的接口需要POST传消息内容。所以我换了一种方式用fetch发起POST请求读取response.body的流手动解析SSE格式。这个方法比EventSource更灵活还能配合AbortController实现取消。核心代码大概是这样const controller new AbortController(); const response await fetch(/chat, { method: POST, headers: {Content-Type: application/json, Accept: text/event-stream}, body: JSON.stringify({session_id: sessionId, message: userInput}), signal: controller.signal }); const reader response.body.getReader(); const decoder new TextDecoder(); let buf ; while (true) { const {done, value} await reader.read(); if (done) break; buf decoder.decode(value, {stream: true}); const events buf.split(\n\n); buf events.pop(); for (const evt of events) { // 解析 data: 字段并分发到UI } }用户点取消按钮时调用controller.abort()。前端的请求断了服务端的stream_with_context会因为客户端断开而产生GeneratorExit异常我们在异常处理里中止Agent执行。加上前面说的POST取消接口做双保险基本能保证token不浪费。4.4 Agent核心循环run_agent的伪代码大概是这样的def run_agent(session_id, user_input): history sessions.get(session_id, []) history.append({role: user, content: user_input}) while True: if is_cancelled(session_id): yield {type: status, data: {stage: cancelled}} break response llm.chat(history, toolsTOOLS) if response.tool_calls: yield {type: tool_call, data: ...} for call in response.tool_calls: result execute_tool(call) history.append({ role: tool, tool_call_id: call.id, content: result }) yield {type: tool_result, data: ...} else: answer response.content yield {type: done, data: {answer: answer}} break这里最关键的是把取消检查放在循环最前面。因为Agent外部接口调用是先做简短token级流式输出再做工具调用每一步之间都是有间隔的——取消标记必须在这时候被读到否则用户点了停止还要等整个工具执行完。我自己实际写的代码比这个复杂一些但主干逻辑就是上面这段读起来非常直观。5. 接入真实模型云端API与Ollama本地部署5.1 模型选型的兼容性第一版我用的是OpenAI兼容接口也就是base_url可以任意切换。这里有个很实际的技巧写代码时永远用openai这个SDK然后把base_url换成目标服务的地址。国内很多模型服务商都提供OpenAI兼容端点用这种方式可以做到一套代码切换模型不伤筋动骨。这样做最大的好处是模型层可以随时替换。一开始用云端的大模型跑通全链路后面想换更便宜的小模型或者切到本地私有化部署只需要改一行配置。Agent核心逻辑、工具调用、事件协议完全不受影响。5.2 Ollama部署要点后来项目要往私有化方向走服范那边提了一个要求模型必须部署在内网不能把业务数据发送到云端。这时候Ollama就上场了。Ollama的安装非常简单下载安装包或者一条curl命令就能搞定。重点是模型选择。我们在内网部署的时候没有直接上最大的模型而是选了量化版Qwen2.5-7B-Instruct。7B参数量是目前性价比最高的档位量化之后显存占用大概6GB左右单张消费级显卡就能跑。启动命令是这样ollama serve ollama pull qwen2.5:7b-instruct-q4_K_M如果你要挂在后台常驻可以加个systemd服务或者直接用docker。有一点必须提醒OpenAI兼容接口在Ollama里默认是关闭的需要设置环境变量OLLAMA_HOST0.0.0.0而且新版Ollama会用另一个端口暴露OpenAI兼容接口别搞混了。我当时就因为端口配对错排查了快一个小时才发现是文档里默认端口变了。5.3 云端与本地模型的输出差异本地模型跑起来之后最大的感受是速度有时甚至比云端快省了网络延迟但推理质量和指令遵循能力有明显差距。具体表现在工具调用率上——同一个Function Calling格式Qwen2.5-7B偶尔会漏参数或者把参数类型传错。这不是模型笨而是小参数量模型对JSON Schema的容忍度就是不如大模型。务实一点的解决方案有两个一是把工具描述写得更死板用示例值而不是抽象描述二是在Agent循环里加一道参数合法性校验发现缺失参数就重新问模型要一次最多重试三次。这个后处理逻辑虽然不优雅但在真实项目里非常有效比盲目微调模型省事多了。本地部署的价值在于数据安全和离线可用如果对推理质量有极致要求云端大模型仍然是最优解。6. 流式输出、取消与并发三个必须正视的工程问题6.1 流式输出被缓冲反向代理的坑SSE实测中最常见的幺蛾子就是前端等了很久什么都没显示。我在本地用Flask开发调试还好一放到Nginx后面就出问题。查了很久才发现Nginx默认开了proxy_buffering会把后端响应攒到一定大小才发给客户端。解决方案有两处。Nginx配置里显式关闭缓冲location /chat { proxy_buffering off; proxy_cache off; proxy_set_header Connection ; proxy_http_version 1.1; chunked_transfer_encoding off; }同时Flask那边响应头里加上Cache-Control: no-cache和X-Accel-Buffering: no。如果你用的是云厂商的网关可能还要在网关侧关掉缓冲。这个问题不解决不管Agent做得再好用户看到的就是一个转圈半天的假死页面。6.2 abort之后上游请求怎么收前文说过取消标记的原理但这里还有一个更细的坑如果Agent正在调用大模型API而且这个调用是阻塞的、没有传timeout那么即使取消标记已经置位代码也要等当前那个HTTP请求返回才能进入下一轮循环。所以我在所有上游模型调用里都加了timeout参数并且用带超时的future来兜底from concurrent.futures import ThreadPoolExecutor, TimeoutError executor ThreadPoolExecutor(max_workers1) future executor.submit(llm.chat, history, toolsTOOLS) try: response future.result(timeout30) except TimeoutError: future.cancel() yield {type: status, data: {stage: timeout}} return这种设计牺牲了一点点每次调用的等待上限但换来了系统的确定性。线上Agent最怕的就是不知道它在干嘛所以所有外部调用必须设定时限。顺带说一句获取大模型响应时建议在流式模式下边读边判断取消标记这样能更早中断。6.3 并发与会话隔离会话状态如果直接放内存并发一高就会串号。所以我在内存态里给每个session_id单独维护一个消息列表和取消标记同时用一个Lock保证同一个session的串行访问。不同session之间互不干扰这个方案能扛住小规模的并发。如果要做成企业级服务建议把会话状态迁到Redis。数据库方案其实很简单给每个消息列表一个keykey里存JSON数组取消标记单独一个短过期key。主要收益是重启不丢会话以及多实例部署时能共享状态。这个我们是在第二阶段上的第一版内存方案验证了业务逻辑足够了。7. 优化与迭代从能用到好用的三次调整7.1 提示词的系统化改写第一次跑通Demo后我们发现了一个典型问题用户问查一下昨天华东区的订单Agent确实调了订单查询工具但它把昨天翻译成了当前自然时间——这没问题可如果用户问对比上个月和这个月它就蒙了因为单次工具调用不支持对比两个时间段的数据。这个问题本质上不是模型智商问题而是提示词和工具设计的缺陷。我把工具参数从month改成start_date和end_date同时System Prompt里明确要求将这个月/上个月/最近一周翻译成具体的日期范围之后才能调用工具。改完之后这类查询的失败率直接降了一个数量级。这个案例说明了一个道理Agent的优化很多时候不是调模型而是调工具描述和编排逻辑。先花时间把输入数据的边界想清楚比盲目增加工具数量有用得多。很多团队为了看起来智能堆了二十多个工具结果模型每次都在纠结该选哪个最后效果反而不如五个精挑细选过的工具。7.2 输出格式稳定化另一个常见痛点是最终回答格式不稳定。让模型自然输出容易跑题。后来我在System Prompt末尾加了明确的输出约束要求最终回答必须包含结论数据来源下一步建议三部分缺一不可。并且在解析端做兜底如果Agent直接返回了纯文本而没有结构化后端自动把它转成标准格式。这其实涉及一个取舍要不要在Agent循环里强制输出JSON我的建议是对外部API和下游系统用JSON对前端用户展示用自然语言。不能让用户看到一串JSON后再自己去理解那是反人性的。这个原则贯穿了整个项目也体现在事件协议设计上——tool_call事件里可以传结构化参数但token事件就只传人类可读的文本。7.3 微调尝试与结论项目中期我们确实尝试过一次模型微调目标是提升工具调用成功率。当时用大概几百条脚本生成的输入-工具调用对对Qwen2.5-7B做了LoRA微调。训练本身很顺利但效果提升有限最后工具调用成功率只涨了两三个百分点。我的结论是在Agent场景里除非你是垂直领域的数据分布特别特殊否则提示词工程和工具编排的杠杆远大于微调。微调成本高、周期长更适合模型原生能力不够的情况。对于大多数业务Agent先把提示词、工具描述、编排逻辑打磨到位效果已经能打到90分。微调应该是最后的手段而不是一开始就铺开的路径。8. 上线之后的运维与现实问题8.1 日志怎么记才能排障Agent系统要比普通Web服务难排查得多因为一个请求背后可能有十几步内部调用。上线第一天我们就遇到一个客户问了一个问题系统答非所问的投诉查问题的时候光有HTTP access log根本没用必须能看到每一步的输入输出。所以我把Agent的日志设计成按session聚合的结构每个步骤一行记录时间、session_id、模型请求/响应摘要、工具调用名、其实参、工具返回摘要、耗时。为了方便检索还会在每行打上trace_id。形式不重要关键是要能回放整个思考链路。没有这种日志Agent调试就是盲人摸象连复现问题都做不到。8.2 成本与限流的平衡Agent的token消耗比普通聊天高出一个数量级因为一次任务可能要来回调用模型五六次。我们做过一次统计一次完整Agent任务的平均token消耗大约是一次普通问答的8-12倍。这也意味着如果不对用户的请求做限流和配额控制成本会失控。我加了一个非常朴素的配额策略按session统计每分钟调用次数超过阈值就返回操作太频繁提示同时用token预估器在调用前估算本轮预计消耗超额直接拒绝。这套方案虽然土但非常有效——它把成本从事后看账单变成了事前拦一把。如果你用的是云端API还要记得给接口设置月度预算上限防止某天流量异常把账单打爆。8.3 延迟的预期管理最后聊一个产品层面的事。即使技术全部到位Agent任务依然可能有几十秒的延迟。用户对延迟的容忍度很低想让用户不焦虑光靠技术优化不够还要做预期管理。我们在前端做了三个层面的反馈一开始显示正在分析任务进入工具阶段显示正在查询订单数据最后才显示正在组织答案。甚至在工具执行阶段我们会把工具名和关键参数也显示在界面上。用户看到正在查询订单数据(2025-06-01~2025-06-30)焦虑程度大幅下降还会觉得这个系统很透明、很智能。这个体验细节成本最低但回报非常直观。最后再分享一个小经验Agent智能体开发这个方向技术迭代太快今天的最佳实践可能三个月后就过时。但如果让我提炼一条不变的原则那就是永远先用最朴素的方式把链路跑通再逐步加机制。很多团队一上来就设计完善的记忆系统、多智能体协作框架结果主链路还没通先把问题复杂化了。我自己的习惯是任何Agent项目都先拿消息列表工具循环SSE推送这个最小闭环起步跑通了再考虑要不要上向量记忆、要不要拆分多Agent、要不要做模型微调。每加一层复杂度都要问自己一句这一层真的在解决当前的真实问题吗如果不是就果断砍掉。做Agent和做所有软件工程一样最难的不是学会新框架而是克制住什么都想要的冲动。