林俊旸这个名字关注国内大模型发展的开发者应该不陌生。作为千问Qwen前期的核心负责人之一他离开大众视野一段时间后最近带着新公司重新回到牌桌方向直指 Agent腾讯跟投。这则新闻在行业里引发讨论不是因为它又是一笔明星创业融资而是因为它把一条已经被很多人感知到的技术主线摆到了明面上模型层的竞争开始收敛Agent 层正在成为大模型价值兑现的主战场。这件事对普通开发者意味着什么我的判断是千问这类开源模型已经把“模型能力”的门槛拉到了很低的位置接下来的竞争并不在“谁的模型更聪明”而在“谁能用模型真正解决业务问题”。而 Agent正是把模型能力变成生产力的那层“最后一公里”。这篇文章不打算重复融资新闻本身而是帮大家解决三件事Agent 到底是什么它和大模型、ChatBot 的本质区别在哪里一个最小可运行的 Agent 怎么写如何用千问的 API 或本地模型跑通“工具调用”闭环从 Demo 到工程化落地真正容易出问题的地方在哪里有哪些工程规范和面试考点值得提前掌握。1. 这则新闻背后为什么 Agent 成了大模型的下半场1.1 模型平权之后价值开始上移过去两年大模型行业的主旋律是“能力竞赛”。各家拼命训练更大、更强的底座模型跑分、榜单、参数规模成了核心叙事。但从 2024 年下半年开始一个很明显的变化出现了以千问为代表的开源模型能力已经足够支撑大量真实业务场景很多团队不再纠结“用 GPT 还是用国产大模型”而是直接基于开源模型部署私有化服务。模型能力的“平权”带来一个连锁反应如果底座模型大家都有靠什么拉开差距答案是应用层。一个企业不可能只靠“能聊天”的模型产生业务价值。它需要模型去查数据库、读文档、操作业务系统、根据流程做判断最后把结果反馈给用户。这些能力的组合就是 Agent。从公开信息看林俊旸的新公司把方向放在 Agent腾讯跟投本质上是在押注同一个判断模型是基础设施Agent 才是应用入口。1.2 谁是这波 Agent 浪潮的主角很多人以为 Agent 是 AI 从业者的专属话题其实不然。今天做 Java 后端、Python 爬虫、前端开发的工程师都有机会接触到 Agent 开发。举几个身边的场景运维同学想做一个“查日志、定位报错、给出修复建议”的助手后端同学想做一个“根据用户提问自动查订单、调用退款接口”的客服系统数据同学想做一个“用自然语言查数据库、生成报表”的问答机器人前端同学想做一个“根据产品需求自动写页面、调接口、预览效果”的开发助手。这些需求背后都有一个共同点不是让模型“说”答案而是让模型“做”事情。这就是 Agent 的意义。所以这篇文章的读者不只是算法工程师而是所有想用大模型解决实际问题的开发者。2. 先分清大模型、ChatBot 与 Agent 的边界2.1 一句话差别经常有同学把“接入了大模型 API”和“做了 Agent”划等号这是目前 Agent 开发里最常见的误区。三者的关系可以这样理解大模型LLM是一个会“思考”的能力底座。它只负责接收文本输出文本。ChatBot是围绕大模型做的“问答界面”。用户问一句模型答一句没有自主执行能力。Agent是围绕大模型做的“自主执行系统”。它能理解目标、拆解步骤、调用外部工具、观察结果、修正计划直到完成任务。用一个类比大模型是大脑ChatBot 是只会回答问题的顾问Agent 则是拿了你家钥匙、能出门办事的助理。助理不只是“想”他还要“动”。2.2 Agent 的三大核心组件一个典型的 Agent 包含三个核心组件规划Planning把大目标分解成小步骤。比如“帮我订一张明天去北京的机票”Agent 不会直接生成一个 JSON 就完事它需要先查用户身份、查航班、确认价格、下单、通知用户。工具调用Tool Use / Function Calling让模型把“想法”变成“动作”。模型本身不能查数据库、不能发 HTTP 请求但它可以输出一个结构化的调用指令由程序去执行真实函数再把结果返回给模型继续处理。记忆Memory让 Agent 在多次交互中保持状态。短期记忆是上下文窗口里的对话历史长期记忆通常需要外部存储比如向量数据库、KV 存储或配置文件。三者的关系可以整理成一张表组件解决什么问题没有它时会发生什么规划把任务拆成可执行步骤模型直接给结果无法处理复杂流程工具调用让 Agent 影响真实世界模型只会空谈不能查数、不能操作记忆保持对话状态和任务上下文每轮都像失忆无法完成多步任务2.3 Harness、Skill、Memory 这些词到底指什么在阅读 Agent 相关资料时经常会看到 Harness、Skill、Scope 这些术语。这里做一个通俗解释Harness可以理解为 Agent 运行时的“调度控制器”。它负责组织模型调用、工具执行、记忆更新、异常处理这一整套循环。类比汽车的话Harness 是引擎控制系统Agent 是整车。Skill是 Agent 可复用的“技能包”。一个技能通常封装了一个或多个工具以及对应的使用说明。比如“订单查询技能”包含订单表结构、查询接口、参数说明。Agent Scope指 Agent 可以操作的资源边界。比如它能读哪些表、能调用哪些接口、能不能写文件。设置 Scope 的目的是控制风险避免 Agent 乱操作。Agent Memory指 Agent 的状态存储。广义上包含对话历史、业务状态、用户偏好、任务进度。理解这些词不是为了背概念而是为了在阅读框架文档时能快速定位。比如你在某个 Agent 框架里看到memory配置就知道该去哪里接向量库看到scope配置就知道该去哪里收紧权限。3. 千问开源如何降低了 Agent 开发门槛3.1 可私有化部署数据与成本可控千问Qwen系列模型的开源对 Agent 开发的推动是实实在在的。做 Agent 项目时很多团队的第一顾虑是数据不出域。业务数据、用户信息、内部日志直接调用云端大模型 API在合规上不一定过得了即使过了团队内心也常常不踏实。有了开源模型团队可以把模型部署到自己的 GPU 服务器或内网环境请求全部走内网。这样数据链路完全可控调用成本也从“按 token 计费”变成“按自己机器的算力折旧”对高频调用场景会更友好。这也是为什么很多人搜索“千问本地部署”“ollama 千问”“LM Studio 千问本地模型”的原因。用 Ollama、LM Studio 这类工具可以把千问模型拉下来在本机跑成一个 OpenAI 兼容的本地服务然后 Agent 程序直接通过 HTTP 调用。整个过程比想象中简单。3.2 推理与工具调用能力成熟Agent 对模型的硬要求不只是“会聊天”更关键的是“能按格式输出工具调用指令”。如果模型不擅长 Function Calling经常输出不合法 JSONAgent 的程序就会频繁解析失败整体体验很难受。千问系列模型在工具调用上的表现经过大量社区验证已经比较稳定。同时它提供了 OpenAI 兼容的 API意味着现有生态里的框架、SDK、客户端很多都能直接接入不需要重新造轮子。3.3 对开发者选型的启示对开发者来说选模型的逻辑正在改变。以前大家纠结“哪个模型聪明”现在更常见的思考方式是需要私有化、数据敏感选开源千问本地部署需要快速验证、不想管 GPU选云端千问 API需要在 IDE 里写代码可以用支持千问的编程插件需要 Java 技术栈可以用 Spring AI 等框架连接千问。模型本身变成了一个可替换的组件。真正的差异化在于你围绕模型搭建的 Agent 系统是否稳定、可控、能解决业务问题。4. Agent 的典型架构与常见分类4.1 单体 Agent、多 Agent 与 Workflow很多新手一上来就问“多 Agent 怎么做”其实单体 Agent 都没有跑通之前谈多 Agent 为时过早。先看三种常见形态Workflow工作流步骤是预先写死的。比如“用户输入 - 调用接口 A - 判断条件 - 调用接口 B - 输出结果”。每一步做什么开发者在代码里定好模型只负责某个节点上的局部判断。单体 Agent模型在循环里自主决定下一步做什么。系统给它一堆工具它根据用户目标动态选择工具、调整步骤。灵活度高但不确定性也高。多 Agent 系统由多个 Agent 组成团队分别承担不同角色。比如一个负责理解需求一个负责查资料一个负责写代码互相之间通过消息协作。从工程稳定性来说Workflow 最可控单体 Agent 最灵活多 Agent 最复杂。实际项目里最稳的做法是能用 Workflow 解决的不要强行上 Agent必须用 Agent 的先做单体再考虑拆多角色。4.2 一个 Agent 运行时的完整循环不管用哪种框架单体 Agent 的核心循环基本一致接收用户任务把任务、历史消息、可用工具描述一起发给模型模型返回两种结果之一直接回答或者请求调用某个工具如果模型请求调用工具程序执行对应函数把工具结果返回给模型模型基于工具结果继续推理可能再次调用工具也可能给出最终回答循环直到模型给出最终回答或者达到最大迭代次数。这个机制在 OpenAI 生态里叫 Function Calling在其他框架里叫 Tool Calling。本质上都是让模型从“自由输出文本”变成“结构化输出动作指令”。理解了这一层Agent 开发就不再神秘了。接下来我们用千问 API 写一个最小示例。5. 最小可运行示例用千问写一个会查天气的 Agent这一节的目标是跑通一个最小闭环用户问“北京天气如何”模型不直接回答而是先调用一个天气查询工具拿到结果后再组织成自然语言回复。5.1 环境准备本示例使用 Python 编程语言通过千问的 OpenAI 兼容接口完成。需要准备Python 3.9 及以上版本一个可用的千问 API Key云端模式安装 openai SDK。pip install openai如果你更倾向本地部署可以先安装 Ollama并拉取一个千问模型ollama pull qwen3:8b ollama serve本地模式下千问模型会提供一个 OpenAI 兼容的本地服务地址通常是http://localhost:11434/v1。两种模式的核心代码是一致的只是base_url和model不同。5.2 定义工具在 Function Calling 机制里我们需要用 JSON Schema 描述“有哪些工具可用、参数是什么、什么时候用”。这里定义一个查询天气的工具{ type: function, function: { name: get_weather, description: 查询指定城市的实时天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名例如北京、上海 } }, required: [city] } } }注意这段 JSON 不是给程序直接执行的而是给模型看的“工具说明书”。模型看到这个描述后如果觉得需要查天气就会输出一个类似“调用 get_weather参数 city 为北京”的结构化指令。5.3 实现 Agent 主循环新建一个agent_demo.py文件代码逻辑如下# 文件路径agent_demo.py import json from openai import OpenAI # 云端千问模式以 DashScope 的 OpenAI 兼容模式为例 # 本地 Ollama 模式base_url 改为 http://localhost:11434/v1 client OpenAI( api_keyYOUR_API_KEY, base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) MODEL qwen-plus # 请以你账号实际可用的模型名为准 tools [ { type: function, function: { name: get_weather, description: 查询指定城市的实时天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名} }, required: [city] } } } ] def get_weather(city: str): 真实的工具函数。实际项目中应替换为天气服务 API。 return f{city}今日晴气温18~25℃东南风3级 def run_agent(user_task: str, max_iterations: int 5): messages [{role: user, content: user_task}] for step in range(max_iterations): response client.chat.completions.create( modelMODEL, messagesmessages, toolstools, tool_choiceauto, ) assistant_message response.choices[0].message messages.append(assistant_message) # 如果模型没有请求调用工具说明它已经可以直接回答 if not assistant_message.tool_calls: print(最终回答, assistant_message.content) return # 否则逐个执行模型请求的工具调用 for tool_call in assistant_message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) print(f[step {step}] 调用工具{fn_name}参数{fn_args}) if fn_name get_weather: result get_weather(fn_args[city]) else: result f未注册的工具{fn_name} # 关键把工具执行结果以 tool 角色消息返回给模型 messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps({result: result}, ensure_asciiFalse) }) print(达到最大迭代次数强制结束) if __name__ __main__: run_agent(北京今天需要带伞吗)5.4 如何验证运行命令python agent_demo.py预期输出大致为[step 0] 调用工具get_weather参数{city: 北京} 最终回答 北京今天晴气温18~25℃东南风3级不需要带伞。如果程序成功打印出工具调用再基于工具结果给出回答说明整个 Agent 循环已经跑通。这一步里最容易出的问题有两个模型没有返回tool_calls而是直接硬答。此时应检查工具描述是否清晰或者在model上换用工具调用能力更强的模型版本消息顺序拼错。OpenAI 兼容接口要求工具调用后必须以tool角色消息把结果回传并且tool_call_id必须和模型输出的一致否则接口会直接报错。6. 从 Demo 到工程化Agent 必须跨过的五道坎跑通最小 Demo 后你会发现“让模型调用一次工具”并不难难的是让 Agent 在真实业务里稳定工作。下面这五道坎是每个 Agent 项目都会遇到的。6.1 规划与任务拆解真实用户不会像 Demo 里那样只问一句话他们可能会说“帮我看看昨天订单为什么失败然后给用户发一封道歉邮件。”这个任务至少需要三步查订单、分析原因、写邮件并发送。如果所有步骤都让模型在单次循环里自由发挥很容易乱。更稳的做法是设计一个明确的规划层简单任务直接用工具调用自动完成中等任务先让模型输出一个计划Plan再由程序逐个执行复杂任务由人工设定关键节点模型只负责节点内的局部决策。工程上常见的模式是 Plan-and-Execute。先让模型生成步骤清单然后 Agent 按清单逐步执行每一步都可以校验结果。这样即使某一步失败了也能定位到具体环节。6.2 工具层设计Agent 的能力上限取决于工具设计的质量。工具不是越细越好也不是越粗越好。建议遵循几个原则命名清晰工具名要能直接表达职责比如query_order、refund_request参数收敛每个工具的参数尽量少能用一个字段表达清楚就不要设计五个字段结果标准化工具返回值统一用结构化 JSON方便模型引用异常兜底工具内部要捕获异常返回给模型的应该是“错误描述”而不是直接抛栈统一注册用一个工具注册表维护所有工具避免在代码里写满 if-else。在稍大一点的系统里建议把工具注册表设计成如下形式TOOL_REGISTRY { get_weather: get_weather, query_order: query_order, refund_request: refund_request }模型要调用工具时先查注册表找不到就返回“工具不存在”。这样新增一个工具只需要注册一次不需要改动 Agent 主循环。6.3 记忆管理Agent 跑多轮之后上下文会越来越长。这里要区分两种记忆短期记忆就是当前会话的对话历史。它是模型推理的上下文但窗口有限塞太多历史会让响应变慢、成本变高、注意力分散。长期记忆需要持久化的关键信息比如用户偏好、订单编号、历史决策。通常存到外部存储按需检索。在工程上比较实用的做法是每轮对话结束后对“关键信息”做摘要历史摘要存到 KV 或向量数据库新任务开始时只把和当前任务相关的记忆注入上下文设置上下文长度阈值超过后先摘要、后截断。很多 Agent 项目“跑着跑着就变笨”往往不是模型问题而是上下文里堆满了无关历史。6.4 错误恢复与熔断Agent 的每一步都可能出错模型超时、工具异常、返回格式非法、步骤超过上限。工程上要建立一个“三层兜底”单步超时一次模型调用或工具调用超过 N 秒直接中断整体迭代上限Agent 最多执行多少轮防止死循环失败回退工具执行失败后把错误信息返回给模型让它换一种方式重试而不是直接崩溃。# 文件路径agent-config.yml示意配置 agent: max_iterations: 8 single_step_timeout_seconds: 30 global_timeout_seconds: 120 retry_times: 2这个配置表达了一个核心思想Agent 系统要像对待微服务一样对待模型调用和工具调用超时、限流、熔断、重试一个都不能少。6.5 安全边界与权限控制Agent 能调工具意味着它能影响真实世界。如果一个 Agent 可以连数据库、发消息、改配置那它的权限边界就是整个系统的安全边界。这里给出几条硬性建议最小权限Agent 默认只能执行只读操作写操作需要明确授权高危操作审批涉及退款、删除、下单、群发等操作必须由人工确认工具白名单不是所有函数都能给 Agent 调用只有显式注册的工具才允许执行提示注入防护模型读取外部数据时可能被文本中的恶意指令影响。不要盲目相信工具返回内容里的“指令”必要时要对返回内容做脱敏和过滤。安全不是最后一刻才考虑的事情。从第一个工具接入开始就应该把权限设计写进代码。7. 常见问题与排查思路做 Agent 开发时下面这些问题是高频出现的可以按表格快速排查问题现象可能原因排查方式解决方案模型不按格式返回工具调用工具描述不清晰或使用的小模型能力不足打印模型完整返回检查tool_calls字段优化工具描述切换工具调用能力更强的模型Agent 进入死循环缺少最大迭代限制查看日志中重复调用序列限制max_iterations增加熔断逻辑上下文越来越长响应越来越慢历史消息未做摘要或截断统计每次请求的 token 占用引入记忆管理定期摘要、裁剪上下文工具执行后模型仍然“说错了”工具结果没有正确回传检查消息中是否存在assistant到tool的完整链路确认tool_call_id匹配工具结果使用 JSON 返回本地部署千问模型后推理很慢模型量化、显存或部署方式不合适查看推理吞吐日志观察 GPU 显存占用调整并发数换用适合硬件的量化版或改用云端 APIAgent 误操作了不被允许的功能工具权限范围过大复盘工具调用日志定位越权操作收紧 Agent Scope高危操作加入人工审批8. Agent 开发的最佳实践与工程建议8.1 最小闭环先行很多人一上来就想搭“多 Agent 知识库 长期记忆”的大系统结果一个月过去还在调框架。更务实的路线是先用 3 到 5 个工具跑通一个最小 Agent 闭环验证“模型能不能稳定调用工具、工具结果能不能正确回传、用户体感是否可用”再逐步加能力。8.2 日志与可观测性Agent 是非常典型的“黑盒系统”。你不知道它为什么突然调用了一个奇怪工具也不知道是哪一步导致结果错误。所以日志是刚需。每次请求至少记录用户的原始输入发送给模型的消息列表可脱敏模型返回的完整对象每个工具调用的参数和结果每一步的耗时和 token 消耗。没有日志Agent 项目的排错基本靠猜。8.3 版本管理与配置管理模型有版本Prompt 有版本工具 Schema 也有版本。尤其要注意模型升级后工具调用格式可能有变化需要回归测试Prompt 改动不要直接上生产建立版本记录工具 Schema 变更时要兼容历史会话中的旧调用记录。一套简单的做法是把系统提示词、工具定义、Agent 配置都放到专门的目录或配置中心管理走版本评审后再发布。配置示例如下# 文件路径agent-config.yml agent: system_prompt_version: v2.3 model: qwen-plus temperature: 0.3 max_tokens: 1024 tools: - name: query_order version: v1.2 - name: refund_request version: v1.0 need_approval: true注意这里的need_approval不是虚构功能而是表达一种常见设计对高危工具单独打标记由程序在调用前拦截并请求人工确认。8.4 面向生产的选型建议如果团队是 Java 技术栈可以考虑用 Spring AI 接入千问。Spring AI 提供了 OpenAI 兼容客户端的抽象可以连接云端千问 API也可以连接本地 Ollama 服务。核心概念和 Python 示例一致定义工具 Bean、配置模型客户端、在 Agent 循环里调用。如果团队需要图形化编排很多 Agent 框架也提供了可视化组件。但我的建议是先用代码把原理跑通再引入框架。框架虽然能省事但也会隐藏很多细节一旦出问题不懂原理会很难排查。9. Agent 开发的学习路径与面试考点9.1 学习路线给想系统学习 Agent 开发的读者一条参考路线掌握 Function Calling 机制理解模型如何输出工具调用指令写一个最小 Agent 循环一个任务、两个工具、最多五轮迭代加入记忆管理用会话历史和向量检索改善多轮体验加入规划和多工具协作实现 Plan-and-Execute 模式做工程化改造超时、重试、日志、权限控制再考虑多 Agent拆角色、定通信协议、处理冲突关注安全提示注入、权限边界、审计。这个顺序是围绕一个 Agent 从“概念”到“生产可用”的自然演进。跳过前面直接做后面通常会翻车。9.2 典型面试题最近 Agent 相关岗位的面试题很多都围绕下面几个方向什么是 Function Calling它是如何实现的Agent 和普通 ChatBot 的边界在哪里如何设计 Agent 的长期记忆如何防止 Agent 在读取外部数据时被提示注入攻击你负责设计一个工单自动处理 Agent需要考虑哪些点Agent 陷入死循环时你如何定位问题并解决多 Agent 之间是如何通信和协调的这些问题没有标准答案但如果能结合自己写过的代码和排查过的真实问题来回答会比背概念有说服力得多。9.3 起步建议回到开头那则新闻。林俊旸的新公司选择 Agent 方向腾讯跟投本质上是行业对“模型能力必须通过 Agent 落地”这一判断的认可。对普通开发者来说真正重要的不是去追逐哪家创业公司而是尽快把 Agent 开发当成一项基础技能来掌握。建议从今天开始选一个极小的任务比如“让千问通过工具调用查实时天气”写一个不超过 10 行核心循环的 Agent跑通一次工具调用再故意制造一次工具报错观察模型如何应对。这个动作的价值胜过刷十篇 Agent 架构文章。 Agent开发实战：从千问工具调用到工程化落地
林俊旸这个名字关注国内大模型发展的开发者应该不陌生。作为千问Qwen前期的核心负责人之一他离开大众视野一段时间后最近带着新公司重新回到牌桌方向直指 Agent腾讯跟投。这则新闻在行业里引发讨论不是因为它又是一笔明星创业融资而是因为它把一条已经被很多人感知到的技术主线摆到了明面上模型层的竞争开始收敛Agent 层正在成为大模型价值兑现的主战场。这件事对普通开发者意味着什么我的判断是千问这类开源模型已经把“模型能力”的门槛拉到了很低的位置接下来的竞争并不在“谁的模型更聪明”而在“谁能用模型真正解决业务问题”。而 Agent正是把模型能力变成生产力的那层“最后一公里”。这篇文章不打算重复融资新闻本身而是帮大家解决三件事Agent 到底是什么它和大模型、ChatBot 的本质区别在哪里一个最小可运行的 Agent 怎么写如何用千问的 API 或本地模型跑通“工具调用”闭环从 Demo 到工程化落地真正容易出问题的地方在哪里有哪些工程规范和面试考点值得提前掌握。1. 这则新闻背后为什么 Agent 成了大模型的下半场1.1 模型平权之后价值开始上移过去两年大模型行业的主旋律是“能力竞赛”。各家拼命训练更大、更强的底座模型跑分、榜单、参数规模成了核心叙事。但从 2024 年下半年开始一个很明显的变化出现了以千问为代表的开源模型能力已经足够支撑大量真实业务场景很多团队不再纠结“用 GPT 还是用国产大模型”而是直接基于开源模型部署私有化服务。模型能力的“平权”带来一个连锁反应如果底座模型大家都有靠什么拉开差距答案是应用层。一个企业不可能只靠“能聊天”的模型产生业务价值。它需要模型去查数据库、读文档、操作业务系统、根据流程做判断最后把结果反馈给用户。这些能力的组合就是 Agent。从公开信息看林俊旸的新公司把方向放在 Agent腾讯跟投本质上是在押注同一个判断模型是基础设施Agent 才是应用入口。1.2 谁是这波 Agent 浪潮的主角很多人以为 Agent 是 AI 从业者的专属话题其实不然。今天做 Java 后端、Python 爬虫、前端开发的工程师都有机会接触到 Agent 开发。举几个身边的场景运维同学想做一个“查日志、定位报错、给出修复建议”的助手后端同学想做一个“根据用户提问自动查订单、调用退款接口”的客服系统数据同学想做一个“用自然语言查数据库、生成报表”的问答机器人前端同学想做一个“根据产品需求自动写页面、调接口、预览效果”的开发助手。这些需求背后都有一个共同点不是让模型“说”答案而是让模型“做”事情。这就是 Agent 的意义。所以这篇文章的读者不只是算法工程师而是所有想用大模型解决实际问题的开发者。2. 先分清大模型、ChatBot 与 Agent 的边界2.1 一句话差别经常有同学把“接入了大模型 API”和“做了 Agent”划等号这是目前 Agent 开发里最常见的误区。三者的关系可以这样理解大模型LLM是一个会“思考”的能力底座。它只负责接收文本输出文本。ChatBot是围绕大模型做的“问答界面”。用户问一句模型答一句没有自主执行能力。Agent是围绕大模型做的“自主执行系统”。它能理解目标、拆解步骤、调用外部工具、观察结果、修正计划直到完成任务。用一个类比大模型是大脑ChatBot 是只会回答问题的顾问Agent 则是拿了你家钥匙、能出门办事的助理。助理不只是“想”他还要“动”。2.2 Agent 的三大核心组件一个典型的 Agent 包含三个核心组件规划Planning把大目标分解成小步骤。比如“帮我订一张明天去北京的机票”Agent 不会直接生成一个 JSON 就完事它需要先查用户身份、查航班、确认价格、下单、通知用户。工具调用Tool Use / Function Calling让模型把“想法”变成“动作”。模型本身不能查数据库、不能发 HTTP 请求但它可以输出一个结构化的调用指令由程序去执行真实函数再把结果返回给模型继续处理。记忆Memory让 Agent 在多次交互中保持状态。短期记忆是上下文窗口里的对话历史长期记忆通常需要外部存储比如向量数据库、KV 存储或配置文件。三者的关系可以整理成一张表组件解决什么问题没有它时会发生什么规划把任务拆成可执行步骤模型直接给结果无法处理复杂流程工具调用让 Agent 影响真实世界模型只会空谈不能查数、不能操作记忆保持对话状态和任务上下文每轮都像失忆无法完成多步任务2.3 Harness、Skill、Memory 这些词到底指什么在阅读 Agent 相关资料时经常会看到 Harness、Skill、Scope 这些术语。这里做一个通俗解释Harness可以理解为 Agent 运行时的“调度控制器”。它负责组织模型调用、工具执行、记忆更新、异常处理这一整套循环。类比汽车的话Harness 是引擎控制系统Agent 是整车。Skill是 Agent 可复用的“技能包”。一个技能通常封装了一个或多个工具以及对应的使用说明。比如“订单查询技能”包含订单表结构、查询接口、参数说明。Agent Scope指 Agent 可以操作的资源边界。比如它能读哪些表、能调用哪些接口、能不能写文件。设置 Scope 的目的是控制风险避免 Agent 乱操作。Agent Memory指 Agent 的状态存储。广义上包含对话历史、业务状态、用户偏好、任务进度。理解这些词不是为了背概念而是为了在阅读框架文档时能快速定位。比如你在某个 Agent 框架里看到memory配置就知道该去哪里接向量库看到scope配置就知道该去哪里收紧权限。3. 千问开源如何降低了 Agent 开发门槛3.1 可私有化部署数据与成本可控千问Qwen系列模型的开源对 Agent 开发的推动是实实在在的。做 Agent 项目时很多团队的第一顾虑是数据不出域。业务数据、用户信息、内部日志直接调用云端大模型 API在合规上不一定过得了即使过了团队内心也常常不踏实。有了开源模型团队可以把模型部署到自己的 GPU 服务器或内网环境请求全部走内网。这样数据链路完全可控调用成本也从“按 token 计费”变成“按自己机器的算力折旧”对高频调用场景会更友好。这也是为什么很多人搜索“千问本地部署”“ollama 千问”“LM Studio 千问本地模型”的原因。用 Ollama、LM Studio 这类工具可以把千问模型拉下来在本机跑成一个 OpenAI 兼容的本地服务然后 Agent 程序直接通过 HTTP 调用。整个过程比想象中简单。3.2 推理与工具调用能力成熟Agent 对模型的硬要求不只是“会聊天”更关键的是“能按格式输出工具调用指令”。如果模型不擅长 Function Calling经常输出不合法 JSONAgent 的程序就会频繁解析失败整体体验很难受。千问系列模型在工具调用上的表现经过大量社区验证已经比较稳定。同时它提供了 OpenAI 兼容的 API意味着现有生态里的框架、SDK、客户端很多都能直接接入不需要重新造轮子。3.3 对开发者选型的启示对开发者来说选模型的逻辑正在改变。以前大家纠结“哪个模型聪明”现在更常见的思考方式是需要私有化、数据敏感选开源千问本地部署需要快速验证、不想管 GPU选云端千问 API需要在 IDE 里写代码可以用支持千问的编程插件需要 Java 技术栈可以用 Spring AI 等框架连接千问。模型本身变成了一个可替换的组件。真正的差异化在于你围绕模型搭建的 Agent 系统是否稳定、可控、能解决业务问题。4. Agent 的典型架构与常见分类4.1 单体 Agent、多 Agent 与 Workflow很多新手一上来就问“多 Agent 怎么做”其实单体 Agent 都没有跑通之前谈多 Agent 为时过早。先看三种常见形态Workflow工作流步骤是预先写死的。比如“用户输入 - 调用接口 A - 判断条件 - 调用接口 B - 输出结果”。每一步做什么开发者在代码里定好模型只负责某个节点上的局部判断。单体 Agent模型在循环里自主决定下一步做什么。系统给它一堆工具它根据用户目标动态选择工具、调整步骤。灵活度高但不确定性也高。多 Agent 系统由多个 Agent 组成团队分别承担不同角色。比如一个负责理解需求一个负责查资料一个负责写代码互相之间通过消息协作。从工程稳定性来说Workflow 最可控单体 Agent 最灵活多 Agent 最复杂。实际项目里最稳的做法是能用 Workflow 解决的不要强行上 Agent必须用 Agent 的先做单体再考虑拆多角色。4.2 一个 Agent 运行时的完整循环不管用哪种框架单体 Agent 的核心循环基本一致接收用户任务把任务、历史消息、可用工具描述一起发给模型模型返回两种结果之一直接回答或者请求调用某个工具如果模型请求调用工具程序执行对应函数把工具结果返回给模型模型基于工具结果继续推理可能再次调用工具也可能给出最终回答循环直到模型给出最终回答或者达到最大迭代次数。这个机制在 OpenAI 生态里叫 Function Calling在其他框架里叫 Tool Calling。本质上都是让模型从“自由输出文本”变成“结构化输出动作指令”。理解了这一层Agent 开发就不再神秘了。接下来我们用千问 API 写一个最小示例。5. 最小可运行示例用千问写一个会查天气的 Agent这一节的目标是跑通一个最小闭环用户问“北京天气如何”模型不直接回答而是先调用一个天气查询工具拿到结果后再组织成自然语言回复。5.1 环境准备本示例使用 Python 编程语言通过千问的 OpenAI 兼容接口完成。需要准备Python 3.9 及以上版本一个可用的千问 API Key云端模式安装 openai SDK。pip install openai如果你更倾向本地部署可以先安装 Ollama并拉取一个千问模型ollama pull qwen3:8b ollama serve本地模式下千问模型会提供一个 OpenAI 兼容的本地服务地址通常是http://localhost:11434/v1。两种模式的核心代码是一致的只是base_url和model不同。5.2 定义工具在 Function Calling 机制里我们需要用 JSON Schema 描述“有哪些工具可用、参数是什么、什么时候用”。这里定义一个查询天气的工具{ type: function, function: { name: get_weather, description: 查询指定城市的实时天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名例如北京、上海 } }, required: [city] } } }注意这段 JSON 不是给程序直接执行的而是给模型看的“工具说明书”。模型看到这个描述后如果觉得需要查天气就会输出一个类似“调用 get_weather参数 city 为北京”的结构化指令。5.3 实现 Agent 主循环新建一个agent_demo.py文件代码逻辑如下# 文件路径agent_demo.py import json from openai import OpenAI # 云端千问模式以 DashScope 的 OpenAI 兼容模式为例 # 本地 Ollama 模式base_url 改为 http://localhost:11434/v1 client OpenAI( api_keyYOUR_API_KEY, base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) MODEL qwen-plus # 请以你账号实际可用的模型名为准 tools [ { type: function, function: { name: get_weather, description: 查询指定城市的实时天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名} }, required: [city] } } } ] def get_weather(city: str): 真实的工具函数。实际项目中应替换为天气服务 API。 return f{city}今日晴气温18~25℃东南风3级 def run_agent(user_task: str, max_iterations: int 5): messages [{role: user, content: user_task}] for step in range(max_iterations): response client.chat.completions.create( modelMODEL, messagesmessages, toolstools, tool_choiceauto, ) assistant_message response.choices[0].message messages.append(assistant_message) # 如果模型没有请求调用工具说明它已经可以直接回答 if not assistant_message.tool_calls: print(最终回答, assistant_message.content) return # 否则逐个执行模型请求的工具调用 for tool_call in assistant_message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) print(f[step {step}] 调用工具{fn_name}参数{fn_args}) if fn_name get_weather: result get_weather(fn_args[city]) else: result f未注册的工具{fn_name} # 关键把工具执行结果以 tool 角色消息返回给模型 messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps({result: result}, ensure_asciiFalse) }) print(达到最大迭代次数强制结束) if __name__ __main__: run_agent(北京今天需要带伞吗)5.4 如何验证运行命令python agent_demo.py预期输出大致为[step 0] 调用工具get_weather参数{city: 北京} 最终回答 北京今天晴气温18~25℃东南风3级不需要带伞。如果程序成功打印出工具调用再基于工具结果给出回答说明整个 Agent 循环已经跑通。这一步里最容易出的问题有两个模型没有返回tool_calls而是直接硬答。此时应检查工具描述是否清晰或者在model上换用工具调用能力更强的模型版本消息顺序拼错。OpenAI 兼容接口要求工具调用后必须以tool角色消息把结果回传并且tool_call_id必须和模型输出的一致否则接口会直接报错。6. 从 Demo 到工程化Agent 必须跨过的五道坎跑通最小 Demo 后你会发现“让模型调用一次工具”并不难难的是让 Agent 在真实业务里稳定工作。下面这五道坎是每个 Agent 项目都会遇到的。6.1 规划与任务拆解真实用户不会像 Demo 里那样只问一句话他们可能会说“帮我看看昨天订单为什么失败然后给用户发一封道歉邮件。”这个任务至少需要三步查订单、分析原因、写邮件并发送。如果所有步骤都让模型在单次循环里自由发挥很容易乱。更稳的做法是设计一个明确的规划层简单任务直接用工具调用自动完成中等任务先让模型输出一个计划Plan再由程序逐个执行复杂任务由人工设定关键节点模型只负责节点内的局部决策。工程上常见的模式是 Plan-and-Execute。先让模型生成步骤清单然后 Agent 按清单逐步执行每一步都可以校验结果。这样即使某一步失败了也能定位到具体环节。6.2 工具层设计Agent 的能力上限取决于工具设计的质量。工具不是越细越好也不是越粗越好。建议遵循几个原则命名清晰工具名要能直接表达职责比如query_order、refund_request参数收敛每个工具的参数尽量少能用一个字段表达清楚就不要设计五个字段结果标准化工具返回值统一用结构化 JSON方便模型引用异常兜底工具内部要捕获异常返回给模型的应该是“错误描述”而不是直接抛栈统一注册用一个工具注册表维护所有工具避免在代码里写满 if-else。在稍大一点的系统里建议把工具注册表设计成如下形式TOOL_REGISTRY { get_weather: get_weather, query_order: query_order, refund_request: refund_request }模型要调用工具时先查注册表找不到就返回“工具不存在”。这样新增一个工具只需要注册一次不需要改动 Agent 主循环。6.3 记忆管理Agent 跑多轮之后上下文会越来越长。这里要区分两种记忆短期记忆就是当前会话的对话历史。它是模型推理的上下文但窗口有限塞太多历史会让响应变慢、成本变高、注意力分散。长期记忆需要持久化的关键信息比如用户偏好、订单编号、历史决策。通常存到外部存储按需检索。在工程上比较实用的做法是每轮对话结束后对“关键信息”做摘要历史摘要存到 KV 或向量数据库新任务开始时只把和当前任务相关的记忆注入上下文设置上下文长度阈值超过后先摘要、后截断。很多 Agent 项目“跑着跑着就变笨”往往不是模型问题而是上下文里堆满了无关历史。6.4 错误恢复与熔断Agent 的每一步都可能出错模型超时、工具异常、返回格式非法、步骤超过上限。工程上要建立一个“三层兜底”单步超时一次模型调用或工具调用超过 N 秒直接中断整体迭代上限Agent 最多执行多少轮防止死循环失败回退工具执行失败后把错误信息返回给模型让它换一种方式重试而不是直接崩溃。# 文件路径agent-config.yml示意配置 agent: max_iterations: 8 single_step_timeout_seconds: 30 global_timeout_seconds: 120 retry_times: 2这个配置表达了一个核心思想Agent 系统要像对待微服务一样对待模型调用和工具调用超时、限流、熔断、重试一个都不能少。6.5 安全边界与权限控制Agent 能调工具意味着它能影响真实世界。如果一个 Agent 可以连数据库、发消息、改配置那它的权限边界就是整个系统的安全边界。这里给出几条硬性建议最小权限Agent 默认只能执行只读操作写操作需要明确授权高危操作审批涉及退款、删除、下单、群发等操作必须由人工确认工具白名单不是所有函数都能给 Agent 调用只有显式注册的工具才允许执行提示注入防护模型读取外部数据时可能被文本中的恶意指令影响。不要盲目相信工具返回内容里的“指令”必要时要对返回内容做脱敏和过滤。安全不是最后一刻才考虑的事情。从第一个工具接入开始就应该把权限设计写进代码。7. 常见问题与排查思路做 Agent 开发时下面这些问题是高频出现的可以按表格快速排查问题现象可能原因排查方式解决方案模型不按格式返回工具调用工具描述不清晰或使用的小模型能力不足打印模型完整返回检查tool_calls字段优化工具描述切换工具调用能力更强的模型Agent 进入死循环缺少最大迭代限制查看日志中重复调用序列限制max_iterations增加熔断逻辑上下文越来越长响应越来越慢历史消息未做摘要或截断统计每次请求的 token 占用引入记忆管理定期摘要、裁剪上下文工具执行后模型仍然“说错了”工具结果没有正确回传检查消息中是否存在assistant到tool的完整链路确认tool_call_id匹配工具结果使用 JSON 返回本地部署千问模型后推理很慢模型量化、显存或部署方式不合适查看推理吞吐日志观察 GPU 显存占用调整并发数换用适合硬件的量化版或改用云端 APIAgent 误操作了不被允许的功能工具权限范围过大复盘工具调用日志定位越权操作收紧 Agent Scope高危操作加入人工审批8. Agent 开发的最佳实践与工程建议8.1 最小闭环先行很多人一上来就想搭“多 Agent 知识库 长期记忆”的大系统结果一个月过去还在调框架。更务实的路线是先用 3 到 5 个工具跑通一个最小 Agent 闭环验证“模型能不能稳定调用工具、工具结果能不能正确回传、用户体感是否可用”再逐步加能力。8.2 日志与可观测性Agent 是非常典型的“黑盒系统”。你不知道它为什么突然调用了一个奇怪工具也不知道是哪一步导致结果错误。所以日志是刚需。每次请求至少记录用户的原始输入发送给模型的消息列表可脱敏模型返回的完整对象每个工具调用的参数和结果每一步的耗时和 token 消耗。没有日志Agent 项目的排错基本靠猜。8.3 版本管理与配置管理模型有版本Prompt 有版本工具 Schema 也有版本。尤其要注意模型升级后工具调用格式可能有变化需要回归测试Prompt 改动不要直接上生产建立版本记录工具 Schema 变更时要兼容历史会话中的旧调用记录。一套简单的做法是把系统提示词、工具定义、Agent 配置都放到专门的目录或配置中心管理走版本评审后再发布。配置示例如下# 文件路径agent-config.yml agent: system_prompt_version: v2.3 model: qwen-plus temperature: 0.3 max_tokens: 1024 tools: - name: query_order version: v1.2 - name: refund_request version: v1.0 need_approval: true注意这里的need_approval不是虚构功能而是表达一种常见设计对高危工具单独打标记由程序在调用前拦截并请求人工确认。8.4 面向生产的选型建议如果团队是 Java 技术栈可以考虑用 Spring AI 接入千问。Spring AI 提供了 OpenAI 兼容客户端的抽象可以连接云端千问 API也可以连接本地 Ollama 服务。核心概念和 Python 示例一致定义工具 Bean、配置模型客户端、在 Agent 循环里调用。如果团队需要图形化编排很多 Agent 框架也提供了可视化组件。但我的建议是先用代码把原理跑通再引入框架。框架虽然能省事但也会隐藏很多细节一旦出问题不懂原理会很难排查。9. Agent 开发的学习路径与面试考点9.1 学习路线给想系统学习 Agent 开发的读者一条参考路线掌握 Function Calling 机制理解模型如何输出工具调用指令写一个最小 Agent 循环一个任务、两个工具、最多五轮迭代加入记忆管理用会话历史和向量检索改善多轮体验加入规划和多工具协作实现 Plan-and-Execute 模式做工程化改造超时、重试、日志、权限控制再考虑多 Agent拆角色、定通信协议、处理冲突关注安全提示注入、权限边界、审计。这个顺序是围绕一个 Agent 从“概念”到“生产可用”的自然演进。跳过前面直接做后面通常会翻车。9.2 典型面试题最近 Agent 相关岗位的面试题很多都围绕下面几个方向什么是 Function Calling它是如何实现的Agent 和普通 ChatBot 的边界在哪里如何设计 Agent 的长期记忆如何防止 Agent 在读取外部数据时被提示注入攻击你负责设计一个工单自动处理 Agent需要考虑哪些点Agent 陷入死循环时你如何定位问题并解决多 Agent 之间是如何通信和协调的这些问题没有标准答案但如果能结合自己写过的代码和排查过的真实问题来回答会比背概念有说服力得多。9.3 起步建议回到开头那则新闻。林俊旸的新公司选择 Agent 方向腾讯跟投本质上是行业对“模型能力必须通过 Agent 落地”这一判断的认可。对普通开发者来说真正重要的不是去追逐哪家创业公司而是尽快把 Agent 开发当成一项基础技能来掌握。建议从今天开始选一个极小的任务比如“让千问通过工具调用查实时天气”写一个不超过 10 行核心循环的 Agent跑通一次工具调用再故意制造一次工具报错观察模型如何应对。这个动作的价值胜过刷十篇 Agent 架构文章。