企业官网建设流程全解析

1. 为什么说“别一上来就啃框架”是入门的第一课

这两年 AI Agent 这个概念被炒得火热，打开技术社区、招聘网站，满屏都是 Agent 应用、Agent 开发工程师的岗位。很多人一看这势头，尤其是想转行做 AI 的同学，第一反应就是冲去学 LangChain、学 LlamaIndex，想赶紧把这些框架拿下来，好像学会了就能做 Agent 了。但我见了太多这样的例子：下载了教程、跑通了 Demo、觉得自己会了，结果让他自己写一个能真正解决某个具体问题的 Agent，他愣是不知道从哪儿下手，框架里的概念全认识，但串不起来。

我自己也走过这条路。早几年在做一个内部知识库问答的智能化改造时，我的第一想法也是先找一个成熟的 Agent 框架套上去，省得从零搭建。结果折腾了小半个月，工程上能跑，可实际用起来效果非常差——召回的内容不准，模型经常答非所问，日志一堆报错根本不知道问题出在哪层。后来我推倒重来，把框架丢掉，从最基础的 Prompt、模型调用、工具封装一步步做起，反而两个星期就把效果做到了可用。那次之后我就很确定一个道理：Agent 的核心从来不是某个框架，而是你对“模型怎么调、上下文怎么管、工具怎么接”这三件事的理解。框架只是把你已经会的东西包装得方便了一些而已。

所以这篇内容，就是专门写给准备入行或者正在考虑转行的朋友的。我不会推荐你立刻去学某个框架，也不会给你贴一堆让人更焦虑的术语清单。我打算从零讲清楚 AI Agent 到底是什么、做 Agent 真正需要掌握哪些底层能力、怎么不靠框架手搓一个跑得通的 Agent、以及什么时候你才真正需要框架。只要你跟着这篇的思路把基础打扎实了，以后再去看任何框架，你的视角都会完全不一样。

2. 核心思路拆解：Agent 的本质与初学者最常见的“三大误区”

2.1 Agent 到底是什么？先把概念还原成朴实的样子

很多新人被“Agent”这个词吓住了，下意识把它想象成一个很玄的东西。拆穿了看，Agent 不过是一个“能自己决定下一步做什么”的程序。举个最朴素的例子：你做菜的时候，先看看冰箱里有什么材料，决定做哪道菜，然后开始切菜、炒菜，过程中发现盐不够了，就临时决定去楼下超市买一包。这个过程中你在不断地观察、决策、行动、再观察。Agent 干的事情本质上也是这样——它根据你给的目标，结合当前掌握的信息，选择调用合适的工具，执行操作，观察结果，再决定下一步怎么办。直到目标完成或者它认为没法继续了，才停下来。

可以用一个更具体的场景来理解：你做一个“周末出游规划助手”。把它做成 Agent 之后，用户说“帮我安排一个两天一夜的周边游”，这个 Agent 会先拆解任务——查天气、找景点、查酒店、算路线、做预算，然后它自己去调天气查询工具、地图工具、订房网站接口，最后给你一个完整的行程单。传统程序是你把所有逻辑都写在代码里，Agent 程序则是你只给它一个目标和几个工具，剩下的路径它自己摸索。能力更强的 Agent 甚至会在发现某条路走不通时，主动换一个搜索词重新查。

理解到这一层，你就明白学 Agent 不是在学某个神秘技术，而是在学一套协调模型、数据、工具的方法。框架是什么？框架是这套方法论里前人总结出来的标准件。你连标准零件长什么样、为什么要这么设计都还没概念，就先把整套流水线背下来了，这不叫学会，叫死记硬背，稍微换个场景就失灵了。

2.2 误区一：把“学会框架”误当成“学会 Agent”

我面试过不少简历上写着“熟练使用 LangChain”的候选人，结果我问一个很基础的问题：如果你要做一个“定时抓取竞品新闻并总结成周报”的小工具，你觉得这个系统由哪几个核心模块组成？很多人答不上来，或者只会照着框架里的概念拼名词，什么 AgentExecutor、Chain、Tool，但说不清楚这些模块各自是干什么的、数据怎么在这些模块之间流转。

问题就出在很多人是“先会了框架，才来理解概念”。这个顺序对某些技术可能是可行的，但对 Agent 来说是反的。Agent 的底层逻辑非常清晰，大致就那么几步：接收任务、拆解任务、选择工具、执行工具、分析结果、更新计划、直到收尾。框架做的只是把这几步“模板化”了，它在某些场景下帮你少写了代码，但绝不替你理解了你在做什么。

所以我在带新人时有一条铁律：至少先手写一个不依赖任何框架的 Agent Demo，再去看框架。这个门槛不算高，但只要你真写过了，你对 Agent 的掌控感会强非常多。

2.3 误区二：以为做 Agent 就是写好 Prompt 然后调 API

这个误区是另一个极端。有的人把 Agent 想得太难，也有些人想得太简单。在他们的认知里，“AI 写代码 = 发一段 Prompt 然后拿到返回结果”，把 Agent 看成高级版的“问答机器人”，无非是多写几条 Prompt 而已。

但做 Agent 和做普通的问答机器人有一个本质区别：Agent 的行为是“持续性的、多步骤的、需要外部反馈的”。你不能把完整答案一次性算出来，你得一遍一遍地和模型交互，每一次交互它只决定“下一步做什么”，然后你帮它执行这个动作，把结果返回给它看，它再决定“然后呢”。所以除了 Prompt，你还需要认真设计整个循环控制逻辑：什么时候该停止？多次失败之后怎么办？每一步的中间结果怎么存？这些才是 Agent 开发的真正难点，而这些东西是单纯“调 API”学不到的。

2.4 误区三：只关注代码，忽略数据准备和上下文管理

还有一个坑，也是新手最快掉进去的：一上来就研究各种框架的功能编排，完全忽略：你的模型到底能吃哪些数据、能记住多少上下文、中间结果放哪儿。做过实际项目的人都有体会，一个 Agent 的效果好坏，很多时候不取决于模型有多聪明，而是取决于你有没有把决策所需的关键信息在正确的时机喂到模型的窗口里。上下文一长，模型容易“迷失重点”；上下文太短，模型又缺乏足够的背景，给不出合理判断。这种调配能力，是你光看框架文档永远学不到的。

放下框架，先把 Agent 的“骨架”摸熟，把模型交互、上下文整理、工具调用这些地基打牢，后面学框架真的很轻松。下面我挨个拆开讲。

3. 核心基础能力拆解：你入门前真正要先掌握的几件事

3.1 提示词工程：Agent 的“底层操作系统”

如果说做 Agent 只需要认真学一样东西，我会毫不犹豫说：提示词工程。不是那种写“请帮我...”的简单指令，而是真正能设计出可靠、可控的提示词结构。

为什么这件事这么关键？因为模型本身有“不稳定性”——同一个问题，你换一个问法，结果可能差别很大。而在 Agent 系统里，模型要做的决策很多，每一步都用 Prompt 控制。如果 Prompt 写得含糊，模型就可能给出偏离预期的决定。比如你做的是一个客服 Agent，用户说“我上周买的东西坏了”，如果 Prompt 没有明确说明应该“先查订单，再判断是否在保修期”，模型可能直接就道歉并承诺退款了，这在真实业务里是不可接受的。

新手学提示词工程，我建议从以下几个点入手：

• 角色设定：不用写得花哨，核心是明确“你是谁、你在什么场景下、受什么约束”。比如“你是一名智能客服，只负责订单问题，超出范围请引导用户找人工。”
• 任务拆解式表达：在 Prompt 里就把任务拆成有序步骤，而不是含糊地说“处理这个问题”。你把步骤拆得越清楚，模型越不容易跑偏。
• 输出格式锁定：用 JSON 或固定模板约束输出结构。Agent 里模型的每一步输出都是一个输入给后续逻辑看的“消息”，格式乱了你后面代码就难写。
• 加例子：给一个“什么是好回答”的例子比你说一百句“要回答好”都管用。但例子也别太极端，防止模型变得只会模仿而不懂变通。

这里特别提醒一下。你写的每一个 Prompt 都是 Agent 这条生产线上的一道工序，写 Prompt 不是发一条朋友圈，而是有明确产出物、需要反复测试的工程文档。我见过很多新人把 Prompt 写在 Jupyter Notebook 里随手一跑，效果时好时坏也不深究原因。做 Agent 如果这样，后面线上跑起来你能被各种不确定性问题活活累死。

3.2 上下文的管理：你要面对的核心矛盾

模型不是无限的。不管用什么型号，它的上下文窗口总有一个上限。而 Agent 在处理真实任务时，你不可能把所有信息一股脑全塞给模型——成本高不说，模型还会因为信息过载反而表现变差。所以你必须掌握“什么信息该保留、什么信息可以压缩、什么信息可以丢弃”的判断能力。

初学者最容易犯的错是“把每轮对话历史都原样拼进下一次请求”。一开始还行，到第十轮以后你发现 Prompt 变得巨大，一方面响应慢，另一方面模型已经完全不记得最初的目标是什么了。更麻烦的是，有些信息是中间过程的临时状态，模型根本不需要知道，但你全塞给它，它的注意力被分散，最后的决策自然就差。

我做 Agent 时有一个习惯：定义一套清晰的上下文更新规则。哪些信息是任务相关的核心信息，必须全程保留；哪些信息只需要摘要一下，把完整细节存到外部存储里；哪些信息是一次性的，用完就丢。这套规则听起来不复杂，但能不能落地，直接区分你有没有真正理解 Agent。

3.3 工具调用的心智模型：Agent 的“手和脚”

工具调用是实现 Agent 价值的核心通道。一个“只会说不会做”的 Agent 是聊胜于无的，你要给它配上“手和脚”——也就是它能调用的工具。这里的工具可以是一个天气查询 API、一个数据库查询函数、一个计算器、一个爬虫脚本，甚至一个发给某个同事的审批通知。

做 Agent 的你，在“工具调用”这件事上，需要想明白三件事：

1. 工具定义的清晰度。模型不是人，它无法“看一眼就明白”你的工具是干什么的。你必须用自然语言加上明确的输入输出参数描述，把工具的用途写得足够清楚。工具名别取得模棱两可，参数说明要写到具体类型和单位。同一个功能，你叫它“search”还是“search_news_by_keyword”，看起来差别不大，但模型决策时的准确率可能差很多。

2. 错误处理与重试机制。真实世界里没有不出错的工具。网络超时、接口返回异常、参数格式不对，全是常态。Agent 工具能不能“绕过去”，是项目落地成败的关键。比如你的 Agent 调一个天气接口失败了，你是直接报错结束，还是让它换个搜索方式再试一次？这些兜底逻辑需要你设计好，而不是指望模型自己会“灵机一动”。

3. 工具权限边界。给 Agent 的工具能力越强，它“闯祸”的能力也越强。比如你给它一个“执行任意代码”的工具，它可能真的会在某些情况下做出你不想看到的操作。所以我建议给工具设计清晰的权限级别，能只读就别给写入，能返回少量数据就别把整个库导出来给它。安全底线问题，在 Agent 上要格外留心。

这一块是新手容易浅尝辄止的地方。不少人认为“工具调用有啥好学的，无非就是写一个函数然后声明一下”。真到了实际项目中你会知道，工具注册、参数校验、超时管理、日志追踪、权限控制，每一环都有讲究。

3.4 循环机制：Agent 的“大脑皮层”

Agent 的智能来自“循环”。人的思考过程不是一次性的，而是反复进行的。模型的单次输出也类似，Agent 的循环机制就是把它的一次次预测、执行、观察串成一个持续逼近目标的过程。

循环机制听起来高大上，核心就三件事：

• 条件判断：什么时候该继续？什么时候该结束？比如设定最大循环轮次（防止死循环），或者当模型输出“任务完成”标记时就退出。
• 中间状态保存：执行了两三步之后的中间结果放哪儿？怎么传给下一步决策？这是 Agent 能“记住自己做到哪儿了”的关键。
• 错误恢复：某一步执行失败，是跳过、重试，还是直接认输？在新手项目里，这一步只要写好了，效果会有质的提升。

框架里这些东西已经有现成的封装，但如果你自己不亲自写一遍，出了 bug 你连在哪一层出的都定位不了。我见过太多开发者在框架里调 Agent，日志里翻半天，结果发现是底层循环逻辑和工具返回值格式之间出了问题，但因为中间被框架黑盒包住了，排查起来非常痛苦。

3.5 模型选型的务实建议：别盲目追求“最强”

最后说一个很多人忽略的点：模型选型。新手总觉得效果不好就该换更大的模型，但现实是，不同任务的难度差距很大，在 Agent 的每个环节里，你用的模型可以不一样。复杂的决策步骤可以用高能力的模型来保证准确率；一些简单的信息抽取、格式整理之类的机械活，用便宜的小模型就足够了，省下来的成本非常可观。

我在做一个轻量级 Agent 时做过一个对比测试：同一个任务，全部步骤用大模型，单次总成本大概几毛钱；而把其中整理类、抽取类的步骤换到小模型，效果没明显下降，单次总成本却降到了几分钱。这种优化意识，建议尽早培养，它对工程化思维非常有益。

4. 手把手搭建你的第一个 Agent：不依赖框架的实战过程

这一章我们来点实在的。我会带你从一个最简单的“个人助理型 Agent”开始，一步步不走框架，只用基础代码，把整个 Agent 的运作机制跑通。主角是一个文本分析小工具，你可以把它理解成“帮我查资料并做总结”的极简版。只要你把这个 Demo 完整写一遍，你对 Agent 内功的理解会上一个台阶。

4.2 明确需求与准备基础环境

先定一个目标：做一个“问答型 Agent”。用户问它一个技术或常识类问题，它能自己判断是否需要调用工具，需要的话调用工具（比如搜索引擎 API 或一个内置的简单百科查询接口），然后把最终结果整理成一段有条理的回答。

开始前需要准备：

• Python 3.10 或更高版本；
• 一个可用的模型 API 接口（哪家都行，这里用通用的 OpenAI 风格调用方式举例）；
• 一个简单的外部工具（我建议就先写一个本地函数：查某个城市当前的天气，因为数据好伪造，方便调试）。

核心代码结构不复杂，重在理清四件事：模型接口的封装、工具的定义与注册、模型返回结果的解析、循环控制逻辑。

4.3 Handcraft 一个“会调用工具”的最小 Agent

下面我用一个精简到极致的示例，把“模型决策—工具执行—再决策”的循环完整呈现一遍。你先看全貌，我再逐段解释。

import json from openai import OpenAI client = OpenAI( api_key="你的API_KEY", base_url="你的API_BASE_URL" ) # 1. 定义一个模拟的“查天气”工具 def get_weather(city: str) -> str: # 真实场景中这里会去请求外部API，这里先返回固定数据 weather_map = { "北京": "晴，26度，微风", "上海": "小雨，22度，东南风3级", "广州": "雷阵雨，30度，南风2级", } return weather_map.get(city, "暂无该城市天气数据") # 2. 工具注册表：给模型看的“工具说明” TOOLS = [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的实时天气情况。", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，如：北京" } }, "required": ["city"] } } } ] # 3. 工具分发器：把模型想调用的函数名映射到真实函数 def call_tool(name: str, arguments: dict) -> str: if name == "get_weather": return json.dumps({"result": get_weather(arguments["city"])}, ensure_ascii=False) return json.dumps({"error": f"未找到工具: {name}"}, ensure_ascii=False) # 4. 主循环：Agent 的核心逻辑 def run_agent(user_query: str, max_steps: int = 5): messages = [{"role": "user", "content": user_query}] step = 0 while step < max_steps: # 4.1 把当前消息与工具定义发给模型 response = client.chat.completions.create( model="gpt-4o-mini", # 换成你实际能用的模型 messages=messages, tools=TOOLS, tool_choice="auto" ) msg = response.choices[0].message # 4.2 模型没有要求调用工具，说明它认为可以直接回答了 if not msg.tool_calls: print("最终回答:", msg.content) break # 4.3 模型要求调用工具：把工具调用加入消息列表 messages.append(msg) for tool_call in msg.tool_calls: tool_name = tool_call.function.name tool_args = json.loads(tool_call.function.arguments) tool_result = call_tool(tool_name, tool_args) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": tool_result }) print(f"Step {step + 1}: 调用 {tool_name}({tool_args}) -> {tool_result}") step += 1 if step >= max_steps: print("达到最大循环轮次，强制停止") if __name__ == "__main__": run_agent("北京今天天气怎么样？适合穿短袖吗？")

这个 Demo 的代码量不大，但麻雀虽小，五脏俱全。把它的执行流程走一遍，你就会发现 Agent 的运行逻辑其实非常直白：

模型收到问题后，不是先憋一个答案，而是“判断自己是否需要工具”。如果它调用了get_weather，我们的代码就把工具返回值作为一条role=tool的消息追加到对话历史里，再带着新增信息去问模型“现在信息够了吗？”。直到模型觉得没必要再调用工具，直接输出最终回答，循环结束。

你可以分别拿“北京今天天气怎么样？”和“帮我讲个笑话”这两个问题试试看。第二个问题模型大概率不会调用任何工具，直接输出回答。这个对比能让你直观感受到：Agent 与普通问答的区别不在于每次都必须调用工具，而在于“有需要时，它有路径可以拿到外部信息”。

4.4 核心代码设计的几个关键注意点

第一个关键细节，tools 参数的结构。这里的字段名称和层级都不是随便写的，模型接口要求的 schema 风格决定了它怎么解析你的工具。name要给得简短但有区分度，description是模型判断“该不该用这个工具”的最重要依据，宁可多写几句背景，也不要只写一个词。parameters里则是把每个参数的类型、含义、约束写清楚，凡是能想到的边界条件都加上说明。

第二个关键细节，tool_call_id必须原样回传。模型发出的每个工具调用都带有唯一 ID，你执行完工具后，要拿到结果并以tool角色 + 对应tool_call_id返回，模型才能把结果和它的调用对上号。新手经常在这掉链子，忘了传 ID，或者把 ID 写错了，结果模型一脸茫然，死循环就出现了。

第三个关键细节，最大循环轮次的设定。模型不是每次都能理智地判断“够了”。有时候它会因为工具返回的结果不够符合预期，反复调用同一个工具。如果你不做最大轮次限制，它不仅会一直烧你的 token，还可能跑出一些意想不到的行为。我这里设了 5 步，相当于一个安全保险。

第四个关键细节，工具结果一定要序列化成字符串再返回。模型接口接收的content是字符串，你不能直接把 Python 字典塞进去。所以call_tool里用json.dumps转了一下，保证了结构可以完整传递。你要是随意用str()转换，中文会变成\uXXXX的转义形式，模型看起来就费劲，回答质量会下降。

4.5 从这个 Demo 中你能提炼出的通用经验

写完了这个 Demo，我希望你不仅把它跑通，更要能回答出这几个问题，回答得出来，恭喜你，Agent 的地基你就打得很牢了：

1. 如果模型连续调用工具三次之后还没有输出最终答案，你该怎么办？
2. 工具返回的结果本身就是一个很长的 JSON，但你想让模型只关注其中几个字段，你在代码里怎么处理，是直接全量塞给模型还是先筛选一遍？
3. 如果你有两个工具，一个查天气、一个查新闻，模型在回答“北京今天适合穿什么样式的衣服”时，会不会先查完天气又查新闻？你怎么避免这种多余调用？

这些问题都没有标准答案，但它们才是真正能在实际项目里帮你省时间的能力。框架说白了，就是帮你把这些问题的若干种常见解答方案打包好了而已。基础设施你已经会自己搭了，框架对你来说就只是“省事”，而不是“救命”。

5. 技术栈之外：转行者最容易忽视的“软技能”与工程习惯

5.1 把需求拆成“模型能理解、代码能执行”的能力

转行或者刚入门的人还有一个很大的困扰：“我好像能读懂技术文档，但拿到一个业务需求时仍然不知道从何下手。”这个问题的本质是缺少“需求拆解”的训练。比如产品经理说：“我想做一个能自动回邮件的小助手”，你脑子里应该立刻冒出这些问题：邮件从哪来？是用户转发、收件箱抓取还是手动粘贴？回复的标准是什么？要不要带上客户的历史沟通信息？语气风格有没有要求？是否需要人在发送前确认？把这些细节问清楚之后，这个“小助手”才能真正变成一个可以开发的项目。

Agent 开发中这种拆解能力尤其重要，因为模型本身不擅长“自己把所有未知细节都问清楚”，它只会你喂什么它处理什么。你如果连目标的边界条件都没定义好，那 Agent 就只能靠猜测工作，效果自然不稳定。我建议初学者每次拿到需求，先强制自己写一份“输入是什么、输出是什么、可用资源是什么、限制条件是什么、例外情况怎么处理”的五段式说明，写清楚了你再动代码。

5.2 日志、追踪与可观测性：面向复杂系统的必备习惯

手写 Demo 时你可能觉得日志就是print。等到 Agent 真正在生成环境里跑起来，你面对的是多步、多工具调用、偶尔失败重试的复杂流程。如果每一步中间结果、每一次工具调用、每一个模型输出都没有留下痕迹，排查问题就像在黑箱子里摸东西，完全靠猜。

所以从一开始就养成给 Agent 加日志的习惯：模型的每次思考输出、工具调用入参和出参、以及本轮命中哪个分支，都要记录下来。这样当最终结果与预期不符时，你是可以按步骤回溯的，而不是拿到一句错误的最终回答就开始瞎试。我见过很多线上事故，最后排查下来都是中间某一步的工具返回了脏数据，但因为没有日志，花了很长时间才定位到这一层。

5.3 成本意识：知道你的 Agent 每跑一次要花多少钱

这是一个很现实的问题。模型是按 token 计费的，Agent 是多轮对话、多工具反馈重试的系统，它的 token 消耗远高于一个简单的问答。如果你不做任何优化，一次完整任务的成本可能是你想像的几倍。

我在实际项目里常用的三个降本招数，分享给各位：

• 精简上下文：每一轮都筛选最有价值的信息，避免把大量中间过程塞进请求；
• 小模型前置分类：先用一个小模型判断问题类型，再决定是否调用大模型做深度处理；
• 设置预算上限：在循环机制里统计 token 消耗，超过一定阈值强制切换低成本模型或终止任务。

这些能力看起来不“性感”，但对实际项目落地影响很大。初学者在满足“能跑”之后，一定要尽早补上成本意识这一课。

6. 什么时候才需要引入框架？如何选型与避坑

6.1 判断标准：你的项目复杂度到了哪一级

看到这里你应该能理解，我并不是反对框架，框架本质上是对“手搓积木”的沉淀，它提高了大量重复工作的效率。但问题是，什么阶段引入框架最合适、选型时最该关注什么，很多新手完全没有概念。

我给你一个很干的判断方式：你的 Agent 如果只需要调用一到三个工具、逻辑散落在几个简单函数里、调用流程不超过五步，那完全不需要框架，手写就够了。这个阶段引入框架反而会平白增加你的学习成本和抽象复杂度。但如果你开始面对这些场景：需要管理多个 Agent 协作、工具数量超过十个、上下文和历史操作需要共享、需要可视化的操作追踪面板、或者你的 Agent 需要接入复杂的记忆系统，那就确实需要考虑用框架了。

6.2 选型时我一般看四个维度

第一是社区活跃度与文档质量。框架生态是否活跃、遇到新问题能不能搜到思路、文档里的例子是否贴合真实场景，这些比某个炫酷特性重要得多。第二是抽象层是否足够薄。有些框架把一切都封装成“漂亮”的高级 API，看起来方便，但你很难定位问题，我建议选那些核心概念贴近底层逻辑、你也容易打开的框架。第三是独立于框架的模型与工具接入自由度。框架越开放，你才越不会后期被限制住手脚。第四是团队里其他人的熟悉程度。如果只有你一个人会用，它再优秀也不能给团队带来持续价值。

6.3 一个常见架构落地案例：从手写过渡到框架

为了让你更直观理解什么时候要升级，我举个例子。某个人在做一个“内容安全审核 Agent”，初期就是手写的流程：模型先用一个小模型判断内容是否疑似违规，疑似的话，再调用后端敏感词过滤工具和人工复审队列接口。手写代码跑得挺顺畅，因为逻辑简单，就两个分支，迭代快。

后来需求变了，要求 Agent 能对不同平台的不同规则做分别处理，还要能根据审核记录的反馈持续自我优化规则。工具数量从三个涨到了十几个，工作流也从单线变成了可以分叉合并的拓扑结构。这个时候再手写 while 循环就去很痛苦了。于是他迁移到框架，用现成的状态机、记忆抽象和管理界面，把更多时间花在业务规则的精细化上，而非自己维护一套工作流引擎。

这个例子说明，手写和框架不是对立的，而是两个不同阶段的合适工具。你的目标应该是能随时在这两者之间来回切换，而不是把某一个的使用当成信仰。

6.4 新手选框架时最该避开的坑

选框架有两个常见的坑。一个是“看名气”：谁火就选谁，也不管项目实际是什么状态。很多框架停留在原型阶段，API 说变就变，你今天照着文档写的代码，下个月就全废了。另一个是“贪多”：上来就想用一个框架解决所有问题。结果把编排、记忆、工具库、界面全绑死在一个生态里，后期想换其中一个组件时，发现牵一发而动全身。

我自己的经验是：先把手写好的代码和框架的核心抽象对齐一下，判断框架对每个组件的封装是否符合我当前的使用方式。如果符合，就引进来，把重复的部分替换掉；如果不符合，那就手写这一部分，框架不强求。这个做法，能让你的项目长期保持在“可控”的状态。

7. 新手实战中常踩的坑与快速排查手册

7.1 模型就是不调用工具，怎么办？

这个现象新手很容易遇到。你明明把工具定义传过去了，模型却像完全看不见工具一样，每次都直接给你最终回答。这个时候，建议你先做一次“极小化排查”：把模型叫出来，故意问一个只有用工具才能回答的问题，比如“帮我查一下上海现在的天气”；确认工具描述是否足够明确；然后尝试在系统提示词里加一句“如果需要实时数据，请务必调用工具获取后再回答”。有时候模型不调工具，真的是因为它觉得“自己知道答案”，这和工具定义没太大关系。提示词引导一下就好。

7.2 工具被反复调用，进入了“死循环”

这个问题在高复杂度任务里尤其常见。模型可能因为第一次调用工具的结果不符合预期，就一直重复调用同一个工具，白白消耗资源。处理思路从上到下依次是：设定最大循环次数，这是底线；每一次工具调用的结果都要作为新的上下文内容返回，让模型看到“这次已经查过了，结果是什么”，有助于它停止重复；还可以在 Prompt 里要求模型“如果上次工具结果已经足够回答，请直接做出回答”。

7.3 模型对工具参数的理解出现偏差

比如你的工具需要传入“城市中文名”，模型却喜欢传拼音缩写；或者你的工具需要“日期”，模型却给你传“今天”。这类问题的核心是参数描述和格式示例做得不够。在description和properties里把“支持的值类型”和“典型写法”写清楚，相当有效。还有一个办法，就是把工具函数内部做成容错型，比如做一个拼音到中文的映射表，把常见的别名都归拢一下。人有模糊表达的自由，代码就得学会做兜底。

7.4 返回结果格式不稳定，代码解析频繁报错

不按照你设定的 schema 输出是常见的烦恼。无论你 Prompt 写多少遍“必须输出 JSON”，模型还是偶尔给你加几句解释文字。这时候不能只靠“写完 Prompt 祈祷它守规矩”，最稳妥的做法是在代码里做一层鲁棒解析。先提取其中的 JSON 片段，再加以解析，失败时用正则兜底。同时设计“解析失败重试”逻辑，让模型重新输出一遍。对于重要字段，解析失败时宁可抛出中断，也不要让脏数据继续流转下去。

7.5 排查工具速查表

为了让你少走弯路，我把常见问题分类整理了一下，后续调试时直接对照着检查就好。

8. 写在最后的几点个人建议

看到这里你应该已经意识到了，AI Agent 的学习路径，不是从“认识框架”开始的，而是从“理解 Agent 的底层逻辑”开始的。打好基础之后，看框架就像看一份别人帮你整理好的笔记，很多概念早就在你的脑子里了。所以如果你正打算入行或者转行，我先建议你花一周时间，把文中那个最小 Demo 自己敲一遍、调试一遍、改出点自己的花样来，再决定要不要碰框架，这个顺序会让你的学习效率高非常多。

你可能会问：“我已经开始啃框架了，现在再看这篇还来得及吗？”任何时候都来得及，你缺的不是进度，而是对底层逻辑的掌控感。就算看完了框架再回头补手写基础，也不丢人，反而会让你把框架用得更好。我也见过不少从我这里手写 Demo 之后的人，回去再翻 LangChain 文档，一眼就能看出哪个抽象是省事的糖，哪个抽象是保命的必需品。

最后再分享一个小技巧。入门阶段不要太纠结于“选择哪个模型”“用哪个框架”，而是把时间花在“把一个小 Agent 从‘偶尔能用’调到‘稳定可用’”这个过程中。这个过程里遇到的所有问题，都是你进步最快的教材。保持记录这些问题的好习惯，把每一次排查过程写成你的个人知识库，你会比那些只刷教程的人成长快得多。

加油，动手写起来吧。