聊 Agent 的话题很难绕开过去这一年里过山车般的行情。去年夏天几乎每个技术社区都在聊“用 Agent 重构一切”能自动写代码的编程助手、能替你做数据分析的研发助理、能根据一句话生成完整方案的多智能体系统。各种 Demo 视频刷屏看起来“取代程序员”只是时间问题。然而一个夏天过去很多当时高调上线的 Agent 项目悄悄下线或回退成了普通的工作流脚本。这个落差不是技术不行而是我们一度把 Agent 的能力边界想得太简单了。本文不从行业八卦的角度聊这次“回落”而是站在开发者的视角做一次工程复盘Agent 到底是什么它和传统工具链的差异在哪里开发一个可用的 Agent 系统需要解决哪些模型层、工程层和安全层的问题以及为什么很多项目会从“惊艳 Demo”走向“难产”。最后我会给出一套可以直接照着搭的 Agent 工程示例配合高频问题排查思路希望能帮你在下一轮 Agent 落地时少踩一些坑。1. 一个夏天Agent 经历了什么1.1 从热闹到冷静的必然过程过去一段时间里Agent 开发几乎成了后端和 AI 方向工程师的必修话题。招聘岗位在提 Agent开源社区在提 Agent甚至面试环节也出现了一些“Agent 八股”什么是 ReAct、什么是 Plan-and-Execute、怎么设计 Tool Calling、多 Agent 之间怎么通信。这种热度快速推高了大家的预期很多人以为只要接一个大模型 API再写几个工具函数就能交付一个“智能体”。等到真正进入业务流程之后问题开始浮现。Demo 里的一次成功调用放到生产环境里变成了十次里有三次失败精心设计的提示词在换了一个模型版本之后表现明显退化Agent 为了完成一个小任务可能连续调用十几个工具成本高得惊人更麻烦的是Agent 出错时的行为比较难预测可能反复执行写操作也可能在一个错误分支里打转。团队不得不投入大量精力去做超时控制、重试、日志追踪、权限收敛和人工兜底。开发成本并没有因为“智能”而下降反而在可预期性上增加了不少负担。1.2 “坠落”的本质是预期错位与其说 Agent 坠落了不如说它正从“概念狂热期”进入“工程冷静期”。大模型本身的能力还在提升工具调用也变得越来越稳定但一个可交付的 Agent 系统涉及的远不止模型推理模型要在正确的时机选择正确的工具工具要提供足够清晰、无歧义的接口描述系统要能处理模型返回的错误格式多轮调用中要控制上下文长度和记忆每个动作都要有权限、审计和回滚机制。这些恰恰都是传统软件工程一直在解决的老问题。Agent 把“智能决策”交给模型之后并没有让其他部分消失反而因为决策的不可穷举让工程控制变得更加重要。这也是为什么业内开始讨论 Agent 安全、Agent 测试、Agent 可观测性——这些内容在过去经常被忽略现在却成了落地绕不开的关键词。对于开发者来说这次“降温”不完全是坏事。它让我们把目光从“模型能不能做到”拉回到“系统怎么稳定做到”。文章后续部分我会围绕一套实际的 Agent 最小工程展开重点讲清楚 Agent 的组成、编码方式、调试手段和上线注意事项。2. Agent 的本质先分清几个容易混淆的概念2.1 什么是 Agent用一个通俗的说法来理解Agent 是一个让大模型不仅“会说话”而且“会办事”的系统。传统聊天机器人只是生成文本回复Agent 则会在收到一个目标后自己拆解步骤、调用外部工具、观察结果、调整下一步动作直到任务完成或达到终止条件。以一个客服工单处理场景为例。过去的对话机器人只能告诉用户“你的问题已经记录”。而一个完整 Agent 可以主动查询工单状态、关联历史订单、调用售后接口创建补偿方案最后把处理结果整理成自然语言回复给用户。区别不在于是否用到了大模型而在于系统里是否存在一条“模型决策—工具执行—结果反馈—模型再决策”的闭环。Agent 的关键能力可以拆成四个部分规划把复杂任务拆成子步骤决定先做什么工具调用通过函数调用或 API 与外部系统交互记忆保存短期对话上下文和长期业务知识反思根据中间结果修正不合理的执行路径。这四个能力不一定都要做得很重但一个可用的 Agent 通常至少要具备前两项。2.2 Agent、Workflow、Function Calling 与 ChatBot 的区别很多时候我们连概念都没有对齐就开始争论 Agent 的优劣这导致了不少无意义的内耗。下面是我在实际开发中理解到的区分方式概念核心特征适合场景ChatBot单轮或多轮生成回复不主动执行外部动作问答、客服对话、知识库问答Function Calling模型能输出结构化调用指令但流程仍由开发者驱动表单填充、信息抽取、简单查询Workflow开发者预定义执行链路每个节点做什么是确定的定时报表、审批流、固定数据处理Agent模型可动态规划步骤并调用工具执行路径不固定开放式任务、需要探索和试错的场景从执行路径来看Workflow 是“铁轨”Agent 是“越野车”。铁轨稳定、可控、出问题容易定位越野车灵活但可能跑偏。比较理想的工程策略不是二选一而是先判断任务是否真的需要“越野”。如果业务流程是固定的比如拉取数据、清洗、写入报表用工作流更划算只有任务目标开放、执行路径可能动态变化时Agent 的灵活性才有价值。2.3 Skill 和 Agent、Harness 和 Agent 是什么关系最近社区里经常讨论 Skill 和 Agent 的区别、Harness 和 Agent 的区别。简单来说Skill 是“能力单元”Agent 是“决策主体”。Skill 可以是一个写好的提示词模板、一段 Python 代码或者一个包装好的 API 调用Agent 负责判断当前任务应该启用哪个 Skill。类似地Harness 是承载 Agent 运行的环境负责管理模型交互、上下文窗口、工具注册、错误恢复等底层逻辑。Agent 可以理解成“大脑”Harness 则是“身体和神经系统”。当我们在说“Agent 框架”时很多时候指的其实是 Harness。理解这一点特别重要因为很多 Agent 项目失败并不是模型不够聪明而是承载它的 Harness 不够健壮——工具的返回值没有结构化、日志缺少 trace_id、模型输出 JSON 字段偶尔错误却没有兜底。这些都不是靠“换一个更强的模型”能解决的。3. Agent 的核心架构与运行原理3.1 ReAct 模式让模型边思考边行动目前大多数 Agent 框架的底层逻辑是 ReAct也就是交替进行 Reasoning推理和 Acting行动。模型先根据用户目标生成一段思考说明下一步计划然后输出一个工具调用请求系统执行工具后把结果返回给模型模型基于新信息更新思考再决定下一步动作如此循环直到任务结束。ReAct 模式的优势在于它把不可预测的模型决策过程暴露成了可观察的中间步骤。开发者可以从日志里看到模型为什么选这个工具、工具返回了什么、模型如何调整策略。排错体验比一个“黑盒生成最终结果”的模式友好很多。典型流程如下用户输入任务系统将初始消息发送给模型模型输出思考内容并可能给出工具调用参数系统执行工具调用工具结果以 tool 角色消息返回模型重复 3~5 步直到模型不再请求工具输出最终答案。3.2 Plan-and-Execute先规划再执行ReAct 适合步骤相对简单、反馈足够快的任务。如果任务本身很复杂每走一步都要让模型重新推理容易导致上下文膨胀和成本上升。Plan-and-Execute 的思路是先把大目标拆成一份计划然后逐步执行每个子任务最后汇总结果。这种模式更接近人类的项目管理方式先开会排计划再按里程碑推进。缺点是如果执行过程中发现计划不合理需要额外引入“重新规划”机制。因此实际系统经常是 ReAct 和 Plan 的结合——先从计划开始但每一步仍然允许模型根据当前语义动态调整。在设计 Agent 时不必一开始就追求非常复杂的规划算法。更推荐的做法是先跑通一个最小的 ReAct 循环拿到真实数据之后再看是否存在“决策次数太多”“上下文太长”“关键分支考虑不全”的问题再决定要不要引入更重的规划模块。3.3 多 Agent 协作到底在解决什么问题当单个 Agent 需要掌握的知识太多、工具太多时提示词会变得臃肿模型也容易在工具选择上出错。多 Agent 模式的核心动机不是“多个模型比一个模型更聪明”而是通过拆分职责让每个子 Agent 只关注一个小领域从而降低单次决策的复杂度。关于多 Agent 的架构业内有一个很值得思考的观点最新的多 Agent 设计里主从模式在本质上可以看作是把 subagent 当成另一种 Tool 来调用。主 Agent 并不真正感知子 Agent 内部的详细状态它只需要知道“这个子 Agent 能完成什么任务、输入是什么、输出是什么”。这种抽象方式和管理工具调用如出一辙只是子 Agent 的执行成本更高、行为更不可预测。这种视角对工程实现很有帮助。你不需要把多 Agent 想成一套全新的分布式系统只需要在工具注册表里增加一项然后为这个“特殊工具”加上自己的系统提示词、内部工具和独立的上下文环境。3.4 一个最小的 ReAct Agent 伪代码理解原理之后通过一段伪代码串联整个循环会更直观。for step in range(max_steps): response call_llm(messages, toolstools) message response.choices[0].message messages.append(message) if message.tool_calls is None: return message.content for tool_call in message.tool_calls: result execute_tool( tool_call.function.name, tool_call.function.arguments ) messages.append({ role: tool, tool_call_id: tool_call.id, content: result })代码里每次循环都在执行同一个逻辑问模型要下一步动作如果有工具调用需要就执行并回填否则说明任务已经完成。后续所有复杂功能包括记忆管理、人机协同、多 Agent 路由、权限限制本质上都是在这个循环上增加控制逻辑。4. 完整实战搭建一个带工具调用的 Agent 项目为了把前面的概念落到具体代码里下面我从零搭建一个可运行的 Agent 示例。这个示例不会依赖某个重量级框架只用 Python 和一个支持 OpenAI 兼容接口的推理服务便于理解底层原理。4.1 项目结构先规划项目文件布局agent-demo/ ├── agent/ │ ├── __init__.py │ ├── core.py # Agent 主循环 │ ├── tools.py # 工具定义与执行器 │ └── llm.py # 模型访问封装 ├── main.py # 入口脚本 ├── requirements.txt └── .env.example # 配置模型连接信息这种结构虽然小但已经把模型层、工具层和调度层分开了。后续如果要接具体框架也能比较方便地迁移。4.2 环境准备与依赖说明本文的代码以 Python 3.10 为例需要安装 requests 库用于调用 HTTP 接口requests2.31.0 python-dotenv1.0.0你可以使用云端支持 OpenAI 兼容接口的模型服务也可以使用本地方案体验。如果你在本地运行推荐使用 Ollama 这类工具启动一个兼容 /v1/chat/completions 的服务再选择一个支持工具调用的模型。不同模型的 tool calling 支持程度差异很大实验时建议优先选择对工具调用支持较好的模型。在项目根目录创建一个 .env 文件写入你的模型连接信息。这里不写死具体服务商请根据实际可用的 API 地址填写MODEL_BASE_URLhttp://localhost:11434/v1 MODEL_NAMEqwen2.5:7b API_KEYlocal-test-key需要说明的是不同模型服务商可能在请求格式、超时时间上有差异。如果遇到兼容性问题请优先查看对应服务商文档。4.3 模型访问封装在 agent/llm.py 中实现一个基础的模型调用函数# 文件路径agent/llm.py import json import requests def call_llm(messages, toolsNone, base_urlNone, api_keyNone, modelNone): 调用 OpenAI 兼容的 chat/completions 接口。 url f{base_url}/chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: model, messages: messages, temperature: 0.2, } if tools: payload[tools] tools payload[tool_choice] auto response requests.post(url, headersheaders, jsonpayload, timeout120) response.raise_for_status() return response.json()这个模块做了几件事拼装请求地址、设置鉴权头、把 tools 参数透传给模型接口、最后返回完整响应。temperature 设置为 0.2是为了让 Agent 的动作选择更稳定一些不让它在工具选择上过于“天马行空”。4.4 工具定义与执行器在 agent/tools.py 中定义两个足够直观的工具一个是加法运算一个是获取当前时间。# 文件路径agent/tools.py import datetime import json TOOL_SPECS [ { type: function, function: { name: add, description: 计算两个整数的和当用户需要加法时使用, parameters: { type: object, properties: { a: {type: integer, description: 第一个加数}, b: {type: integer, description: 第二个加数}, }, required: [a, b], }, }, }, { type: function, function: { name: get_current_time, description: 获取当前系统时间当用户询问时间时使用, parameters: { type: object, properties: {}, }, }, }, ] def execute_tool(name: str, arguments: str): 根据工具名和参数执行对应函数。 if name add: args json.loads(arguments) return {result: args[a] args[b]} if name get_current_time: return {time: datetime.datetime.now().isoformat()} raise ValueError(f未知工具: {name})注意 TOOL_SPECS 里的 description 写得很重要。模型并不“理解”底层代码它判断该调用哪个工具时主要依据就是工具的描述和参数约束。描述越明确参数列表越清晰模型选择错误的概率就越低。4.5 Agent 主循环在 agent/core.py 中实现最关键的 ReAct 循环# 文件路径agent/core.py import json from agent.llm import call_llm from agent.tools import TOOL_SPECS, execute_tool SYSTEM_PROMPT 你是一个有用的智能助手。 你可以通过调用工具来帮助用户完成任务。 如果工具返回结果请根据结果继续回答用户。 def run_agent(user_input: str, base_url: str, api_key: str, model: str, max_steps: int 10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_steps): response call_llm( messagesmessages, toolsTOOL_SPECS, base_urlbase_url, api_keyapi_key, modelmodel, ) message response[choices][0][message] messages.append(message) tool_calls message.get(tool_calls) if not tool_calls: return message.get(content, ) for tool_call in tool_calls: function tool_call[function] result execute_tool(function[name], function[arguments]) messages.append({ role: tool, tool_call_id: tool_call[id], content: json.dumps(result, ensure_asciiFalse), }) return 已达到最大执行步数任务可能未完成。这段代码最核心的节点是每次拿到模型回复后先判断它是否请求调用工具如果请求了就执行工具并把结果以 tool 角色消息放回消息列表如果没有请求工具就把它当作最终答案返回。max_steps 是用来防止模型陷入死循环的保险丝。即便这样在真实系统里也不能只依赖步数限制还需要配合每一步的执行耗时和成本统计。4.6 入口脚本与运行验证在 main.py 中串联整个过程# 文件路径main.py import os from dotenv import load_dotenv from agent.core import run_agent load_dotenv() if __name__ __main__: base_url os.getenv(MODEL_BASE_URL) api_key os.getenv(API_KEY) model os.getenv(MODEL_NAME) question 请问现在几点了另外帮我计算一下 23 加 19 的结果。 answer run_agent(question, base_url, api_key, model) print(Agent 回复, answer)运行前先在项目根目录执行pip install -r requirements.txt python main.py如果一切正常Agent 应该会先调用 get_current_time 获取时间再调用 add 计算加法最后把两个结果整理成一段自然语言回复。你可以在控制台日志里增加对 messages 的打印观察模型每一步的请求和工具返回内容这是理解 Agent 行为最快的方式。如果你的本地模型对工具调用的支持不稳定可能输出的工具调用参数是字符串而不是 JSON 对象或者无法正确识别多工具场景。遇到这类情况时不要急着改代码可以先单独用一段文本让模型生成 tool call确认服务端能力之后再调整参数格式和后端模型。5. Agent 系统的高频故障排查从“能运行的 Demo”到“稳定的系统”之间会有大量问题浮出水面。下面整理了几类我在实践中见过的高频故障以及对应的排查思路。5.1 Agent 执行超时或无响应Agent 项目里最常见的报错之一是“执行提供方没有及时响应”。从现象看可能是模型长时间没有返回内容也可能是某个外部工具调用 API 迟迟不结束。很多初学者会下意识调大超时时间但更合理的做法是先定位瓶颈到底在哪一环。建议按下面顺序排查确认是模型接口超时还是工具执行超时在代码中加入耗时统计分别打印模型请求耗时和工具执行耗时查看大模型服务端的并发负载和排队情况单独测试工具接口排除网络或权限问题在 Agent 循环外层设置总超时时间避免无限等待。代码上可以给 requests 调用增加更细分的超时参数response requests.post(url, headersheaders, jsonpayload, timeout(10, 120))第一个参数是连接超时第二个参数是读超时。把连接超时设得短一些、读超时设得长一些有助于快速识别网络不通和模型推理慢这两种不同问题。5.2 模型返回了不合法的工具调用参数工具调用的返回格式并不总是严格符合 JSON Schema。模型偶然会返回缺失字段的参数也可能在 arguments 字段里夹带前后反引号或多余的解释文字。解析失败时Agent 通常就只能抛异常退出。解决思路不是盲目重试而是把参数解析变成一个可恢复的环节try: args json.loads(function[arguments]) except json.JSONDecodeError: args extract_json_from_text(function[arguments])更稳妥的方案是如果解析失败就把错误信息回传给模型让它修正格式。比如messages.append({ role: tool, tool_call_id: tool_call[id], content: 工具参数格式错误请检查 arguments 是否为合法 JSON。, })模型看到这个错误反馈后通常会自己纠正表达。这种方法比前端硬编码正则拆解更通用也展示了 Agent 系统里“反馈闭环”的威力。5.3 Agent 陷入死循环或频繁调用同一个工具当任务的子步骤比较模糊时模型可能反复调用同一个工具得到的中间结果也一直不满足自身设定的结束条件。再加上带工具循环的交互成本并不低这类问题会造成明显的资源浪费。参考的治理方法包括为循环设置最大步数对同一工具设置单位时间内的调用频率上限当模型连续使用同一个工具且参数高度相似时主动触发人工介入在系统提示词里明确写入“不要重复做已经完成的事情”。这些策略没有哪个是绝对通用的但组合使用可以显著降低风险。5.4 记忆丢失与上下文膨胀上下文的长度是有限资源。当任务执行了很多轮之后早期的重要信息可能被截断Agent 会表现得像“失忆”。这也是为什么聊天记录不能在每一轮都原封不动地拼进去需要考虑摘要、滑动窗口或向量检索。工程上可以先做一个最简单的改进把工具调用结果做摘要而不是把原始返回内容全部塞回模型。比如查询数据库返回了 100 行数据Agent 其实只关注聚合后的结果完全可以把记录截断成统计信息。这个优化既控制了成本又减少了模型被无关信息干扰的概率。5.5 多 Agent 协作时信息不一致在主从模式的 Agent 架构里主 Agent 把一个任务交给子 Agent 后通常只能拿到一个最终结果未必知道子 Agent 内部经历了什么。这可能导致主子 Agent 之间的上下文对不上尤其是当子 Agent 返回的内容缺少关键细节时。与其依赖模型“聪明地总结”不如在子 Agent 的返回结果里定义结构化字段强制它输出执行状态、关键结论、使用的工具、未解决问题等。这样主 Agent 或其他上层系统才能可靠地依赖子 Agent 的输出。下面是一张排查速查表供日常开发参考故障现象常见原因解决思路整个 Agent 长时间无响应模型服务排队或工具 API 挂起拆分连接超时与读超时增加总超时和熔断工具参数解析失败模型输出非标准 JSON将错误回传模型二次修正或增加健壮解析器工具选择错误工具描述不清晰重写 description给出使用示例和边界条件Agent 重复执行同一动作缺少判断任务完成的条件增加步数限制和重复调用检测上下文越往后越乱关键步骤或工具结果过多截断和摘要工具返回控制消息列表长度主从 Agent 信息不一致子 Agent 返回内容不结构化约定子 Agent 的结构化返回字段6. Agent 开发的最佳实践与工程建议6.1 先思考“该不该用 Agent”一个容易被忽略的事实是很多场景根本不需要 Agent。如果业务流程是确定的工作流脚本不仅更稳定成本也更低。一个通用判断标准是“路径是否开放”。任务的完成方式可能存在多种合理路径并且需要根据中间反馈调整时Agent 才是合适的工具如果步骤已经固定把它写成代码或配置化流程会更好。对于团队来说比较稳妥的路线是先让 Agent 在受限场景里做“辅助者”而不是一开始就让它全权处理核心生产动作。比如先让它在沙箱环境里生成 SQL由人工确认后再执行这比直接开放数据库写权限安全得多。6.2 权限收敛与安全边界Agent 最大的安全隐患通常不是模型本身“邪恶”而是工具权限过大。当 Agent 可以访问生产数据库、对象存储或支付接口时一次错误的工具选择就可能造成不可逆影响。建议遵循最小权限原则为 Agent 分配独立账号只授予完成任务所需的最小权限所有危险操作尽量先进入“待确认”状态由人工审批后执行工具执行记录必须包含用户、任务、调用参数、执行时间和返回结果方便事后审计在测试环境充分验证后再放开生产权限。6.3 引入评测与回归机制没有评测集的 Agent 项目很难判断“模型升级了、提示词改好了”到底让系统变好还是变坏。建议维护一组覆盖典型场景的评测用例每个用例写成 JSON 或 YAML记录输入、期望工具调用序列或期望最终输出然后通过脚本批量验证。不必等系统很成熟才做评测。收集线上真实用户输入和 Agent 产生的中间轨迹定期人工标注出“好的决策”和“坏的决策”本身就是为后续改进积累数据资产。6.4 可观测性设计Agent 和普通请求接口的一个显著区别是一次用户提问可能触发内部多次工具调用。如果日志里没有请求链路标识排错时会非常痛苦。在设计 Agent 系统时至少要在每次会话开始生成一个 trace_id并把它贯穿到模型调用、工具调用、外部 API 请求的日志中。6.5 控制成本和资源消耗单轮工具调用可能只是毫秒级成本但 ReAct 循环叠加之后一次任务可能会产生几十万 token 的消耗。成本控制需要从多个方向同时入手控制最大步数、精简消息上下文、对工具返回结果做摘要、允许用户中途打断、把部分简单步骤下沉到确定性代码。这些优化叠加起来往往比单纯换一个更便宜的模型更有效。6.6 人工兜底与人机协同在当前阶段比较好的 Agent 产品形态通常是人机协同。Agent 负责提效人工负责兜底和审核。系统设计上建议预留“人工接管”通道当 Agent 连续失败、执行超时或触发风险规则时可以快速把它拉回人工处理。这既是对用户的负责也能避免 Agent 在生产环境里造成不必要的损失。7. 写在最后Agent 没有消失它正在换一种方式成长回到最初的标题。一个夏天过去Agent 确实没有像最初想象的那样迅速替代我们完成所有工作但这并不等于这条路走错了。更准确地说Agent 正在从“一个令人兴奋的玩具”变成“需要认真设计的软件系统”。模型是 Agent 的发动机但不是全部稳定性、权限、可观测性、评测和成本控制才是决定这套系统能不能长期跑在生产环境里的关键变量。对于开发者来说未来一段时间最值得投入的方向可能不是追逐新概念而是把 Agent 工程中的每个模块做扎实理解模型什么时候该调用工具学会设计结构化的工具接口懂得为不可预测的决策留出边界并建立一套能让系统持续迭代的测试和观测流程。Agent 的开发学习路线并不会消失它只是从“模型应用”的分支演化为更完整的工程学科。如果这篇文章对你有帮助不妨先从搭建一个最小 Agent 开始把 ReAct 循环、工具调用、日志追踪跑通。等你亲手处理过几次模型乱调工具、上下文溢出和权限失控的问题再看 Agent 的发展方向时会比看任何 Demo 都更清楚。
Agent工程实践指南：从概念原理到落地避坑
聊 Agent 的话题很难绕开过去这一年里过山车般的行情。去年夏天几乎每个技术社区都在聊“用 Agent 重构一切”能自动写代码的编程助手、能替你做数据分析的研发助理、能根据一句话生成完整方案的多智能体系统。各种 Demo 视频刷屏看起来“取代程序员”只是时间问题。然而一个夏天过去很多当时高调上线的 Agent 项目悄悄下线或回退成了普通的工作流脚本。这个落差不是技术不行而是我们一度把 Agent 的能力边界想得太简单了。本文不从行业八卦的角度聊这次“回落”而是站在开发者的视角做一次工程复盘Agent 到底是什么它和传统工具链的差异在哪里开发一个可用的 Agent 系统需要解决哪些模型层、工程层和安全层的问题以及为什么很多项目会从“惊艳 Demo”走向“难产”。最后我会给出一套可以直接照着搭的 Agent 工程示例配合高频问题排查思路希望能帮你在下一轮 Agent 落地时少踩一些坑。1. 一个夏天Agent 经历了什么1.1 从热闹到冷静的必然过程过去一段时间里Agent 开发几乎成了后端和 AI 方向工程师的必修话题。招聘岗位在提 Agent开源社区在提 Agent甚至面试环节也出现了一些“Agent 八股”什么是 ReAct、什么是 Plan-and-Execute、怎么设计 Tool Calling、多 Agent 之间怎么通信。这种热度快速推高了大家的预期很多人以为只要接一个大模型 API再写几个工具函数就能交付一个“智能体”。等到真正进入业务流程之后问题开始浮现。Demo 里的一次成功调用放到生产环境里变成了十次里有三次失败精心设计的提示词在换了一个模型版本之后表现明显退化Agent 为了完成一个小任务可能连续调用十几个工具成本高得惊人更麻烦的是Agent 出错时的行为比较难预测可能反复执行写操作也可能在一个错误分支里打转。团队不得不投入大量精力去做超时控制、重试、日志追踪、权限收敛和人工兜底。开发成本并没有因为“智能”而下降反而在可预期性上增加了不少负担。1.2 “坠落”的本质是预期错位与其说 Agent 坠落了不如说它正从“概念狂热期”进入“工程冷静期”。大模型本身的能力还在提升工具调用也变得越来越稳定但一个可交付的 Agent 系统涉及的远不止模型推理模型要在正确的时机选择正确的工具工具要提供足够清晰、无歧义的接口描述系统要能处理模型返回的错误格式多轮调用中要控制上下文长度和记忆每个动作都要有权限、审计和回滚机制。这些恰恰都是传统软件工程一直在解决的老问题。Agent 把“智能决策”交给模型之后并没有让其他部分消失反而因为决策的不可穷举让工程控制变得更加重要。这也是为什么业内开始讨论 Agent 安全、Agent 测试、Agent 可观测性——这些内容在过去经常被忽略现在却成了落地绕不开的关键词。对于开发者来说这次“降温”不完全是坏事。它让我们把目光从“模型能不能做到”拉回到“系统怎么稳定做到”。文章后续部分我会围绕一套实际的 Agent 最小工程展开重点讲清楚 Agent 的组成、编码方式、调试手段和上线注意事项。2. Agent 的本质先分清几个容易混淆的概念2.1 什么是 Agent用一个通俗的说法来理解Agent 是一个让大模型不仅“会说话”而且“会办事”的系统。传统聊天机器人只是生成文本回复Agent 则会在收到一个目标后自己拆解步骤、调用外部工具、观察结果、调整下一步动作直到任务完成或达到终止条件。以一个客服工单处理场景为例。过去的对话机器人只能告诉用户“你的问题已经记录”。而一个完整 Agent 可以主动查询工单状态、关联历史订单、调用售后接口创建补偿方案最后把处理结果整理成自然语言回复给用户。区别不在于是否用到了大模型而在于系统里是否存在一条“模型决策—工具执行—结果反馈—模型再决策”的闭环。Agent 的关键能力可以拆成四个部分规划把复杂任务拆成子步骤决定先做什么工具调用通过函数调用或 API 与外部系统交互记忆保存短期对话上下文和长期业务知识反思根据中间结果修正不合理的执行路径。这四个能力不一定都要做得很重但一个可用的 Agent 通常至少要具备前两项。2.2 Agent、Workflow、Function Calling 与 ChatBot 的区别很多时候我们连概念都没有对齐就开始争论 Agent 的优劣这导致了不少无意义的内耗。下面是我在实际开发中理解到的区分方式概念核心特征适合场景ChatBot单轮或多轮生成回复不主动执行外部动作问答、客服对话、知识库问答Function Calling模型能输出结构化调用指令但流程仍由开发者驱动表单填充、信息抽取、简单查询Workflow开发者预定义执行链路每个节点做什么是确定的定时报表、审批流、固定数据处理Agent模型可动态规划步骤并调用工具执行路径不固定开放式任务、需要探索和试错的场景从执行路径来看Workflow 是“铁轨”Agent 是“越野车”。铁轨稳定、可控、出问题容易定位越野车灵活但可能跑偏。比较理想的工程策略不是二选一而是先判断任务是否真的需要“越野”。如果业务流程是固定的比如拉取数据、清洗、写入报表用工作流更划算只有任务目标开放、执行路径可能动态变化时Agent 的灵活性才有价值。2.3 Skill 和 Agent、Harness 和 Agent 是什么关系最近社区里经常讨论 Skill 和 Agent 的区别、Harness 和 Agent 的区别。简单来说Skill 是“能力单元”Agent 是“决策主体”。Skill 可以是一个写好的提示词模板、一段 Python 代码或者一个包装好的 API 调用Agent 负责判断当前任务应该启用哪个 Skill。类似地Harness 是承载 Agent 运行的环境负责管理模型交互、上下文窗口、工具注册、错误恢复等底层逻辑。Agent 可以理解成“大脑”Harness 则是“身体和神经系统”。当我们在说“Agent 框架”时很多时候指的其实是 Harness。理解这一点特别重要因为很多 Agent 项目失败并不是模型不够聪明而是承载它的 Harness 不够健壮——工具的返回值没有结构化、日志缺少 trace_id、模型输出 JSON 字段偶尔错误却没有兜底。这些都不是靠“换一个更强的模型”能解决的。3. Agent 的核心架构与运行原理3.1 ReAct 模式让模型边思考边行动目前大多数 Agent 框架的底层逻辑是 ReAct也就是交替进行 Reasoning推理和 Acting行动。模型先根据用户目标生成一段思考说明下一步计划然后输出一个工具调用请求系统执行工具后把结果返回给模型模型基于新信息更新思考再决定下一步动作如此循环直到任务结束。ReAct 模式的优势在于它把不可预测的模型决策过程暴露成了可观察的中间步骤。开发者可以从日志里看到模型为什么选这个工具、工具返回了什么、模型如何调整策略。排错体验比一个“黑盒生成最终结果”的模式友好很多。典型流程如下用户输入任务系统将初始消息发送给模型模型输出思考内容并可能给出工具调用参数系统执行工具调用工具结果以 tool 角色消息返回模型重复 3~5 步直到模型不再请求工具输出最终答案。3.2 Plan-and-Execute先规划再执行ReAct 适合步骤相对简单、反馈足够快的任务。如果任务本身很复杂每走一步都要让模型重新推理容易导致上下文膨胀和成本上升。Plan-and-Execute 的思路是先把大目标拆成一份计划然后逐步执行每个子任务最后汇总结果。这种模式更接近人类的项目管理方式先开会排计划再按里程碑推进。缺点是如果执行过程中发现计划不合理需要额外引入“重新规划”机制。因此实际系统经常是 ReAct 和 Plan 的结合——先从计划开始但每一步仍然允许模型根据当前语义动态调整。在设计 Agent 时不必一开始就追求非常复杂的规划算法。更推荐的做法是先跑通一个最小的 ReAct 循环拿到真实数据之后再看是否存在“决策次数太多”“上下文太长”“关键分支考虑不全”的问题再决定要不要引入更重的规划模块。3.3 多 Agent 协作到底在解决什么问题当单个 Agent 需要掌握的知识太多、工具太多时提示词会变得臃肿模型也容易在工具选择上出错。多 Agent 模式的核心动机不是“多个模型比一个模型更聪明”而是通过拆分职责让每个子 Agent 只关注一个小领域从而降低单次决策的复杂度。关于多 Agent 的架构业内有一个很值得思考的观点最新的多 Agent 设计里主从模式在本质上可以看作是把 subagent 当成另一种 Tool 来调用。主 Agent 并不真正感知子 Agent 内部的详细状态它只需要知道“这个子 Agent 能完成什么任务、输入是什么、输出是什么”。这种抽象方式和管理工具调用如出一辙只是子 Agent 的执行成本更高、行为更不可预测。这种视角对工程实现很有帮助。你不需要把多 Agent 想成一套全新的分布式系统只需要在工具注册表里增加一项然后为这个“特殊工具”加上自己的系统提示词、内部工具和独立的上下文环境。3.4 一个最小的 ReAct Agent 伪代码理解原理之后通过一段伪代码串联整个循环会更直观。for step in range(max_steps): response call_llm(messages, toolstools) message response.choices[0].message messages.append(message) if message.tool_calls is None: return message.content for tool_call in message.tool_calls: result execute_tool( tool_call.function.name, tool_call.function.arguments ) messages.append({ role: tool, tool_call_id: tool_call.id, content: result })代码里每次循环都在执行同一个逻辑问模型要下一步动作如果有工具调用需要就执行并回填否则说明任务已经完成。后续所有复杂功能包括记忆管理、人机协同、多 Agent 路由、权限限制本质上都是在这个循环上增加控制逻辑。4. 完整实战搭建一个带工具调用的 Agent 项目为了把前面的概念落到具体代码里下面我从零搭建一个可运行的 Agent 示例。这个示例不会依赖某个重量级框架只用 Python 和一个支持 OpenAI 兼容接口的推理服务便于理解底层原理。4.1 项目结构先规划项目文件布局agent-demo/ ├── agent/ │ ├── __init__.py │ ├── core.py # Agent 主循环 │ ├── tools.py # 工具定义与执行器 │ └── llm.py # 模型访问封装 ├── main.py # 入口脚本 ├── requirements.txt └── .env.example # 配置模型连接信息这种结构虽然小但已经把模型层、工具层和调度层分开了。后续如果要接具体框架也能比较方便地迁移。4.2 环境准备与依赖说明本文的代码以 Python 3.10 为例需要安装 requests 库用于调用 HTTP 接口requests2.31.0 python-dotenv1.0.0你可以使用云端支持 OpenAI 兼容接口的模型服务也可以使用本地方案体验。如果你在本地运行推荐使用 Ollama 这类工具启动一个兼容 /v1/chat/completions 的服务再选择一个支持工具调用的模型。不同模型的 tool calling 支持程度差异很大实验时建议优先选择对工具调用支持较好的模型。在项目根目录创建一个 .env 文件写入你的模型连接信息。这里不写死具体服务商请根据实际可用的 API 地址填写MODEL_BASE_URLhttp://localhost:11434/v1 MODEL_NAMEqwen2.5:7b API_KEYlocal-test-key需要说明的是不同模型服务商可能在请求格式、超时时间上有差异。如果遇到兼容性问题请优先查看对应服务商文档。4.3 模型访问封装在 agent/llm.py 中实现一个基础的模型调用函数# 文件路径agent/llm.py import json import requests def call_llm(messages, toolsNone, base_urlNone, api_keyNone, modelNone): 调用 OpenAI 兼容的 chat/completions 接口。 url f{base_url}/chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: model, messages: messages, temperature: 0.2, } if tools: payload[tools] tools payload[tool_choice] auto response requests.post(url, headersheaders, jsonpayload, timeout120) response.raise_for_status() return response.json()这个模块做了几件事拼装请求地址、设置鉴权头、把 tools 参数透传给模型接口、最后返回完整响应。temperature 设置为 0.2是为了让 Agent 的动作选择更稳定一些不让它在工具选择上过于“天马行空”。4.4 工具定义与执行器在 agent/tools.py 中定义两个足够直观的工具一个是加法运算一个是获取当前时间。# 文件路径agent/tools.py import datetime import json TOOL_SPECS [ { type: function, function: { name: add, description: 计算两个整数的和当用户需要加法时使用, parameters: { type: object, properties: { a: {type: integer, description: 第一个加数}, b: {type: integer, description: 第二个加数}, }, required: [a, b], }, }, }, { type: function, function: { name: get_current_time, description: 获取当前系统时间当用户询问时间时使用, parameters: { type: object, properties: {}, }, }, }, ] def execute_tool(name: str, arguments: str): 根据工具名和参数执行对应函数。 if name add: args json.loads(arguments) return {result: args[a] args[b]} if name get_current_time: return {time: datetime.datetime.now().isoformat()} raise ValueError(f未知工具: {name})注意 TOOL_SPECS 里的 description 写得很重要。模型并不“理解”底层代码它判断该调用哪个工具时主要依据就是工具的描述和参数约束。描述越明确参数列表越清晰模型选择错误的概率就越低。4.5 Agent 主循环在 agent/core.py 中实现最关键的 ReAct 循环# 文件路径agent/core.py import json from agent.llm import call_llm from agent.tools import TOOL_SPECS, execute_tool SYSTEM_PROMPT 你是一个有用的智能助手。 你可以通过调用工具来帮助用户完成任务。 如果工具返回结果请根据结果继续回答用户。 def run_agent(user_input: str, base_url: str, api_key: str, model: str, max_steps: int 10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_steps): response call_llm( messagesmessages, toolsTOOL_SPECS, base_urlbase_url, api_keyapi_key, modelmodel, ) message response[choices][0][message] messages.append(message) tool_calls message.get(tool_calls) if not tool_calls: return message.get(content, ) for tool_call in tool_calls: function tool_call[function] result execute_tool(function[name], function[arguments]) messages.append({ role: tool, tool_call_id: tool_call[id], content: json.dumps(result, ensure_asciiFalse), }) return 已达到最大执行步数任务可能未完成。这段代码最核心的节点是每次拿到模型回复后先判断它是否请求调用工具如果请求了就执行工具并把结果以 tool 角色消息放回消息列表如果没有请求工具就把它当作最终答案返回。max_steps 是用来防止模型陷入死循环的保险丝。即便这样在真实系统里也不能只依赖步数限制还需要配合每一步的执行耗时和成本统计。4.6 入口脚本与运行验证在 main.py 中串联整个过程# 文件路径main.py import os from dotenv import load_dotenv from agent.core import run_agent load_dotenv() if __name__ __main__: base_url os.getenv(MODEL_BASE_URL) api_key os.getenv(API_KEY) model os.getenv(MODEL_NAME) question 请问现在几点了另外帮我计算一下 23 加 19 的结果。 answer run_agent(question, base_url, api_key, model) print(Agent 回复, answer)运行前先在项目根目录执行pip install -r requirements.txt python main.py如果一切正常Agent 应该会先调用 get_current_time 获取时间再调用 add 计算加法最后把两个结果整理成一段自然语言回复。你可以在控制台日志里增加对 messages 的打印观察模型每一步的请求和工具返回内容这是理解 Agent 行为最快的方式。如果你的本地模型对工具调用的支持不稳定可能输出的工具调用参数是字符串而不是 JSON 对象或者无法正确识别多工具场景。遇到这类情况时不要急着改代码可以先单独用一段文本让模型生成 tool call确认服务端能力之后再调整参数格式和后端模型。5. Agent 系统的高频故障排查从“能运行的 Demo”到“稳定的系统”之间会有大量问题浮出水面。下面整理了几类我在实践中见过的高频故障以及对应的排查思路。5.1 Agent 执行超时或无响应Agent 项目里最常见的报错之一是“执行提供方没有及时响应”。从现象看可能是模型长时间没有返回内容也可能是某个外部工具调用 API 迟迟不结束。很多初学者会下意识调大超时时间但更合理的做法是先定位瓶颈到底在哪一环。建议按下面顺序排查确认是模型接口超时还是工具执行超时在代码中加入耗时统计分别打印模型请求耗时和工具执行耗时查看大模型服务端的并发负载和排队情况单独测试工具接口排除网络或权限问题在 Agent 循环外层设置总超时时间避免无限等待。代码上可以给 requests 调用增加更细分的超时参数response requests.post(url, headersheaders, jsonpayload, timeout(10, 120))第一个参数是连接超时第二个参数是读超时。把连接超时设得短一些、读超时设得长一些有助于快速识别网络不通和模型推理慢这两种不同问题。5.2 模型返回了不合法的工具调用参数工具调用的返回格式并不总是严格符合 JSON Schema。模型偶然会返回缺失字段的参数也可能在 arguments 字段里夹带前后反引号或多余的解释文字。解析失败时Agent 通常就只能抛异常退出。解决思路不是盲目重试而是把参数解析变成一个可恢复的环节try: args json.loads(function[arguments]) except json.JSONDecodeError: args extract_json_from_text(function[arguments])更稳妥的方案是如果解析失败就把错误信息回传给模型让它修正格式。比如messages.append({ role: tool, tool_call_id: tool_call[id], content: 工具参数格式错误请检查 arguments 是否为合法 JSON。, })模型看到这个错误反馈后通常会自己纠正表达。这种方法比前端硬编码正则拆解更通用也展示了 Agent 系统里“反馈闭环”的威力。5.3 Agent 陷入死循环或频繁调用同一个工具当任务的子步骤比较模糊时模型可能反复调用同一个工具得到的中间结果也一直不满足自身设定的结束条件。再加上带工具循环的交互成本并不低这类问题会造成明显的资源浪费。参考的治理方法包括为循环设置最大步数对同一工具设置单位时间内的调用频率上限当模型连续使用同一个工具且参数高度相似时主动触发人工介入在系统提示词里明确写入“不要重复做已经完成的事情”。这些策略没有哪个是绝对通用的但组合使用可以显著降低风险。5.4 记忆丢失与上下文膨胀上下文的长度是有限资源。当任务执行了很多轮之后早期的重要信息可能被截断Agent 会表现得像“失忆”。这也是为什么聊天记录不能在每一轮都原封不动地拼进去需要考虑摘要、滑动窗口或向量检索。工程上可以先做一个最简单的改进把工具调用结果做摘要而不是把原始返回内容全部塞回模型。比如查询数据库返回了 100 行数据Agent 其实只关注聚合后的结果完全可以把记录截断成统计信息。这个优化既控制了成本又减少了模型被无关信息干扰的概率。5.5 多 Agent 协作时信息不一致在主从模式的 Agent 架构里主 Agent 把一个任务交给子 Agent 后通常只能拿到一个最终结果未必知道子 Agent 内部经历了什么。这可能导致主子 Agent 之间的上下文对不上尤其是当子 Agent 返回的内容缺少关键细节时。与其依赖模型“聪明地总结”不如在子 Agent 的返回结果里定义结构化字段强制它输出执行状态、关键结论、使用的工具、未解决问题等。这样主 Agent 或其他上层系统才能可靠地依赖子 Agent 的输出。下面是一张排查速查表供日常开发参考故障现象常见原因解决思路整个 Agent 长时间无响应模型服务排队或工具 API 挂起拆分连接超时与读超时增加总超时和熔断工具参数解析失败模型输出非标准 JSON将错误回传模型二次修正或增加健壮解析器工具选择错误工具描述不清晰重写 description给出使用示例和边界条件Agent 重复执行同一动作缺少判断任务完成的条件增加步数限制和重复调用检测上下文越往后越乱关键步骤或工具结果过多截断和摘要工具返回控制消息列表长度主从 Agent 信息不一致子 Agent 返回内容不结构化约定子 Agent 的结构化返回字段6. Agent 开发的最佳实践与工程建议6.1 先思考“该不该用 Agent”一个容易被忽略的事实是很多场景根本不需要 Agent。如果业务流程是确定的工作流脚本不仅更稳定成本也更低。一个通用判断标准是“路径是否开放”。任务的完成方式可能存在多种合理路径并且需要根据中间反馈调整时Agent 才是合适的工具如果步骤已经固定把它写成代码或配置化流程会更好。对于团队来说比较稳妥的路线是先让 Agent 在受限场景里做“辅助者”而不是一开始就让它全权处理核心生产动作。比如先让它在沙箱环境里生成 SQL由人工确认后再执行这比直接开放数据库写权限安全得多。6.2 权限收敛与安全边界Agent 最大的安全隐患通常不是模型本身“邪恶”而是工具权限过大。当 Agent 可以访问生产数据库、对象存储或支付接口时一次错误的工具选择就可能造成不可逆影响。建议遵循最小权限原则为 Agent 分配独立账号只授予完成任务所需的最小权限所有危险操作尽量先进入“待确认”状态由人工审批后执行工具执行记录必须包含用户、任务、调用参数、执行时间和返回结果方便事后审计在测试环境充分验证后再放开生产权限。6.3 引入评测与回归机制没有评测集的 Agent 项目很难判断“模型升级了、提示词改好了”到底让系统变好还是变坏。建议维护一组覆盖典型场景的评测用例每个用例写成 JSON 或 YAML记录输入、期望工具调用序列或期望最终输出然后通过脚本批量验证。不必等系统很成熟才做评测。收集线上真实用户输入和 Agent 产生的中间轨迹定期人工标注出“好的决策”和“坏的决策”本身就是为后续改进积累数据资产。6.4 可观测性设计Agent 和普通请求接口的一个显著区别是一次用户提问可能触发内部多次工具调用。如果日志里没有请求链路标识排错时会非常痛苦。在设计 Agent 系统时至少要在每次会话开始生成一个 trace_id并把它贯穿到模型调用、工具调用、外部 API 请求的日志中。6.5 控制成本和资源消耗单轮工具调用可能只是毫秒级成本但 ReAct 循环叠加之后一次任务可能会产生几十万 token 的消耗。成本控制需要从多个方向同时入手控制最大步数、精简消息上下文、对工具返回结果做摘要、允许用户中途打断、把部分简单步骤下沉到确定性代码。这些优化叠加起来往往比单纯换一个更便宜的模型更有效。6.6 人工兜底与人机协同在当前阶段比较好的 Agent 产品形态通常是人机协同。Agent 负责提效人工负责兜底和审核。系统设计上建议预留“人工接管”通道当 Agent 连续失败、执行超时或触发风险规则时可以快速把它拉回人工处理。这既是对用户的负责也能避免 Agent 在生产环境里造成不必要的损失。7. 写在最后Agent 没有消失它正在换一种方式成长回到最初的标题。一个夏天过去Agent 确实没有像最初想象的那样迅速替代我们完成所有工作但这并不等于这条路走错了。更准确地说Agent 正在从“一个令人兴奋的玩具”变成“需要认真设计的软件系统”。模型是 Agent 的发动机但不是全部稳定性、权限、可观测性、评测和成本控制才是决定这套系统能不能长期跑在生产环境里的关键变量。对于开发者来说未来一段时间最值得投入的方向可能不是追逐新概念而是把 Agent 工程中的每个模块做扎实理解模型什么时候该调用工具学会设计结构化的工具接口懂得为不可预测的决策留出边界并建立一套能让系统持续迭代的测试和观测流程。Agent 的开发学习路线并不会消失它只是从“模型应用”的分支演化为更完整的工程学科。如果这篇文章对你有帮助不妨先从搭建一个最小 Agent 开始把 ReAct 循环、工具调用、日志追踪跑通。等你亲手处理过几次模型乱调工具、上下文溢出和权限失控的问题再看 Agent 的发展方向时会比看任何 Demo 都更清楚。
