企业官网建设流程全解析

说实话，这两年我见过太多新手和转行者冲进来学 AI Agent，第一步就是打开某几个热门编排框架的文档，装了一堆依赖，照着教程跑通一个 demo，然后发个朋友圈就完事了。再过两天问他原理，基本答不上来，项目也改不动，版本一升级就全崩。问题不出在不努力，而是顺序反了。

我自己的体会是：AI Agent 本质上是“大模型 + 工具 + 记忆 + 决策循环”的组合，框架只是把这几个东西打包好、加了一层调度逻辑而已。新手真正该做的，是先搞懂模型调用、提示词、结构化输出和工具设计，然后用原生代码手写一个极简 Agent，让它在自己手里跑起来，之后再回头看框架，你一眼就能看穿它到底做了什么。

这篇文章就给打算入门、以及从传统开发转行做 Agent 的朋友画一条路线。不讲玄学，不推框架，只讲第一性原理和能落地的实操，你按这个顺序学，至少能省两个月弯路的钱。

1. 先想清楚：AI Agent 到底是什么

1.1 一句话本质：大模型驱动的决策循环

很多人把 Agent 想得很玄，其实拆到最底层，它就是一个循环：

接收用户目标 → 大模型思考下一步 → 调用一个工具/给出回答 → 把结果带回来 → 再思考 → 循环，直到任务完成

这个循环里有四个核心零件，缺一个都不成立：

• 大模型：负责理解意图、拆解任务、决定下一步动作。它是“大脑”，但它自己不会执行，只会输出文字。
• 工具：模型能指挥的外部能力，比如查数据库、发请求、算数、搜索、操作文件。这是 Agent 能做事而不是只会聊天的关键。
• 记忆：上下文窗口是有限的，Agent 需要把历史对话、工具结果、长期知识保存下来，在合适的时机塞回给模型。这部分最容易被新手忽略，也最容易翻车。
• 循环控制：什么时候继续，什么时候停，出错怎么恢复，怎么防止同一个工具被反复调用，这是判断一个 Agent 工程质量的分水岭。

你看，这四个零件没有一个是某个框架专属的。你完全可以用标准代码把它们拼起来。

1.2 为什么别一上来就啃框架

我先说个扎心的事实：框架抽象掉了大量细节，而这些细节恰恰是新手最该练的基本功。

拿常见的编排框架来说，它给你封装好了 Agent、Tool、Memory、Retriever、Plan 这些概念，你写几行配置就能跑。但代价是什么？是出了问题你不知道去哪查。模型返回了一个奇怪的 JSON，你不知道是框架解析的锅还是模型输出的锅。工具一直重试，你不知道是框架的重试策略还是你自己业务代码的 bug。想把长上下文做个截断，你得先翻半天框架源码看它有没有隐藏逻辑。

我打个比方：这就好比学做菜，正常人肯定先学切菜、备料、开火、调味，你直接去五星酒店后厨跟行政总厨学“如何管理一个后厨团队”，学是能学到东西，但你连颠勺都不会，学完也做不出一桌菜。

框架是给已经懂原理的人用的。它帮你省的是重复劳动，不是帮你省学习。所以新手入门第一步，不是打开框架文档，而是把一个 Agent 能跑起来的最小闭环，用最原始的 API 调用自己亲手搭出来。

1.3 建议的学习路线总览

我给自己带的新手团队定的路线固定是四层，任何人我都拦着不让跳级：

1. 大模型调用层：搞懂 API 怎么调、输入输出长什么样、参数怎么控制。
2. 结构化输出层：搞懂怎么让模型稳定输出 JSON、工具调用指令，怎么处理失败。
3. 工具与服务层：搞懂怎么设计一个能被模型可靠调用的工具，怎么接外部系统。
4. 状态与循环层：搞懂记忆怎么管、循环怎么控制、Agent 怎么评估。

四层全部用原生代码过一遍，快的话一周半，慢的话三周。之后再去学框架，你会发现它的每个概念你都能对上号，看源码就像看自己写的代码，再也不会被一堆抽象概念绕晕。

2. 入门第一课：把大模型调用玩熟

2.1 跑通一次 API 调用，比你想象的更有价值

很多人觉得“不就是调个 API 吗”，但作为数学和编程基础相对薄弱的转行者，这一步千万别跳过。你需要亲手在代码里完成一次完整的对话补全，并且理解三个关键东西。

第一，消息格式。最常见的格式是一个数组，里面有 system、user、assistant 三种角色。system 负责定规则，user 是用户输入，assistant 是模型自己的历史回复。多轮对话就是把这个数组不断追加进去。初学者最容易犯的错，是新的一轮只传当前用户问题，导致模型“失忆”。

第二，几个核心参数。temperature 控制随机性，一般写代码、做工具调用设低一点，比如 0.1 到 0.3；闲聊可以设高一点。max_tokens 控制回复长度，很多人忽略它，结果模型回复到一半被截断，JSON 解析直接失败。top_p 现在用得少了，保持默认也行。

第三，上下文窗口。模型一次能看到的 token 数是有限的，你的历史消息越多，留给新问题和新工具结果的空间就越少。后面讲到记忆时你会反复遇到这个问题，但你在第一次调 API 时就该有这个意识。

我建议你写一个小脚本：用任意一门熟练语言，发一条请求，打印出完整响应。然后故意调高 temperature 到 1.5，观察回复变得多么离谱；故意把 max_tokens 设成 10，观察回复怎么被截断。这比看任何教程都印象深刻。

2.2 手写一个最小的 ReAct 循环

ReAct 是 Reasoning + Acting 的缩写，意思是模型一边推理一边行动，也是最朴素的一种 Agent 模式。下面是核心伪代码，不依赖任何框架：

function run_agent(goal): messages = [{role: "system", content: system_prompt}, {role: "user", content: goal}] for step in range(max_steps): reply = call_llm(messages) messages.append({role: "assistant", content: reply}) if reply contains "FINAL_ANSWER": return extract_answer(reply) else: tool_name, tool_input = parse_action(reply) result = call_tool(tool_name, tool_input) messages.append({role: "system", content: "工具返回: " + result}) return timeout_error

你可以看到，Agent 的核心就是一个循环，循环里只发生了三件事：把历史交给模型、解析模型输出、执行工具并把结果回填。框架里的 Agent 执行器，翻来覆去做的就是这件事。

我建议你把这段伪代码真正跑通，加一个最小工具，比如“计算两个数之和”或者“查当前时间”。你会发现一个很现实的问题：模型可能不按你说的格式输出行动指令，可能输出一段散文而不是 “TOOL_NAME: xxx, INPUT: yyy”。从这一步起，你就开始体会 Agent 工程师日常的痛了。

2.3 提示词是新手的第一套“隐形框架”

很多转行的人以为框架是配置出来的，其实是“提示词 + 代码”对出来的。你的第一套框架，应该是能在提示词里把任务边界写清楚。

我常用的 system prompt 结构是四段式：

• 角色：你是谁，专长是什么，在什么场景下工作。
• 目标：你现在要完成的任务是什么，成功标准是什么。
• 约束：哪些事情绝对不能做，哪些情况必须请求工具，回复格式是什么。
• 示例：给一两个输入输出的例子，尤其是“工具调用格式”的例子。

这里有一条经验：示例要贴近真实场景，不要用“用户问天气”这种通用例子。你让模型调用订单查询工具，就给它一个带订单号、平台、时间字段的真实 JSON 例子，模型大概率会照着你的格式输出，比你在提示词里写一百遍“你必须输出 JSON”管用得多。

另外，务必要给模型“思考的空间”。比如你直接问“这个用户的订单状态是什么”，模型可能猜，但如果你提示它“先检查是否有订单号，没有就问用户要”，它就会按你的流程走。这就是思维链最简单的用法，不需要什么复杂技巧，先把推理步骤写进提示词里就能明显提升准确性。

3. 转行者最缺的一块：工具调用与结构化输出

3.1 Function Calling 到底是怎么一回事

很多从传统后端转过来的朋友，对 Function Calling 天生产生误解，以为“模型在执行我的函数”，其实不是。模型只是一个文本生成器，它生成的是“调用意图”，真正执行的是你的代码。

举个具体场景。你有一个函数 query_user(name)，Function Calling 的过程是这样：

1. 你事先给模型一份“工具说明书”，说明有哪些函数、每个函数接受哪些参数、参数的含义和格式。
2. 当用户说“帮我查一下张三的信息”，模型看懂了意图，就输出一个结构化的指令，你可以理解为：调用函数 query_user，参数 name = 张三。
3. 你的代码收到这个指令，自己执行 query_user，拿到结果，把结果作为一条新消息发给模型。
4. 模型再根据结果组织回答。

关键点在于：函数的执行结果模型本来不知道，模型只知道“我已经请求调用某个函数了”，结果是你喂给它的。所以工具返回结果的格式非常重要，最好整理成简洁、结构化的文本，不要一股脑把一个超大的 JSON 原样塞回去。

好的工具结果可以这样设计：

查询成功。 用户: 张三 账户状态: 正常 当前余额: 1280.50 元 最近一笔交易: 2024-11-03 充值 500 元

差的工具结果是把整个数据库行、几十个字段、嵌套对象直接丢给模型。模型确实能读，但会浪费大量 token，而且容易在无关字段上产生幻觉，得不偿失。

3.2 不靠框架，自己实现一个工具路由

自己写工具路由其实很考验工程能力，正好适合转行者练手。我推荐的做法是“注册表模式”。

先定义一个统一接口，所有工具都返回同一个结构。然后你维护一张注册表，注册表里记录工具的元信息，包括函数名、描述、参数 schema、真实处理函数。最后写一个分发器，根据模型输出的工具名去注册表里查，找到就执行，找不到就返回错误。

我贴一个简化版本，用伪代码解释这个模式：

tools = {} def register_tool(name, description, params_schema, handler): tools[name] = {"description": description, "schema": params_schema, "handler": handler} def dispatch(tool_name, arguments): tool = tools.get(tool_name) if not tool: return "错误: 未知工具 " + tool_name try: result = tool["handler"](**arguments) return "成功: " + format_result(result) except Exception as e: return "失败: " + str(e) # 注册一个工具 register_tool("get_user_info", "根据用户名查询用户账户信息", {"user_name": "string, 必填"}, query_user_db)

这个模式的优点有三个：新工具接入只加一个注册项，不用改主干代码；工具列表可以动态生成，随时能拼到提示词里告诉模型有哪些可用工具；出了错能根据工具名快速定位。这套思路等你以后看框架源码，你会发现很多框架底层就是这么做的，只是它用装饰器和配置帮你省了注册这一步。

3.3 工具层最容易踩的坑

这部分是我带团队时整理出的高频问题，新手基本都会踩一遍，先列出来给你打个预防针。

第一，参数校验千万别省。模型输出的参数是它“猜”的，可能出现字段缺失、格式不对、value 超出枚举范围，甚至直接输出 null。你的 handler 里必须做严格校验，不要假设模型一定按 schema 来。很多项目工具调用半天不成功，最终一查，就是参数里混进去一个空格。

第二，超时和重试必须有。工具可能调用一个远程服务，如果这个服务 10 秒没响应，你的 Agent 会一直卡在循环里。我的做法是每个工具调用设置一个超时时间，超出就返回一个明确错误：“工具执行超时，请换一个方式查询”，让模型自己去决定是重试还是换策略。

第三，工具返回结果必须加长度上限。模型上下文是有限的，一个工具返回了 10000 个 token，整个 Agent 直接撑爆，后面什么事情都做不了。我的习惯是在工具里做摘要、截断、只返回关键字段。返回前先把数据压缩一遍，别偷懒。

第四，权限边界不能全交给模型。根据模型判断“要不要调用有副作用的工具”是不可靠的，比如发邮件、删文件、转账这类操作，一定要在代码里设置二次确认，或者用只读/可写两套模式区分。这不是技术问题，是安全意识问题。

4. 核心难点：状态、记忆与循环控制

4.1 记忆分层：短期、长期、工作记忆

新手往往会问：模型不是能记住上下文吗，为什么还要自己做记忆？原因前面说过：上下文窗口有上限，而且每轮对话全部重发，token 成本会高得离谱。所以你要自己设计记忆体系。

我把 Agent 的记忆粗分成三层：

• 工作记忆：当前任务用到的关键信息，比如临时变量、上一步工具结果，任务结束就清空。实现上就是放一个 dict。
• 短期记忆：最近几轮的对话摘要，用来保持多轮任务的连续性。常见做法是滑动窗口截断，只保留最近 N 条，或者用模型把早期对话压缩成摘要。
• 长期记忆：跨会话保存的用户偏好、历史结论、领域知识。一般存到向量数据库里，按需检索出来塞进提示词。

我建议入门阶段先别碰向量数据库，用一个简单的滑动窗口就够。关键代码逻辑是：当消息总长度超过阈值时，把最早的消息删掉，或者把最旧的一段对话用模型摘要成一行字，然后继续。等你的任务真正需要跨会话记忆时，再引入向量检索不迟。

4.2 循环控制与终止条件：防止 Agent 越跑越偏

没有终止条件的 Agent 就是定时炸弹。我见过一个 demo 因为没有最大轮次限制，模型反复调用同一个垃圾工具，一分钟内花掉了几十块钱的 token。所以无论你手写还是用框架，下面四个终止条件都必须有：

• 最大轮次限制：一般任务 5 到 10 轮内应该解决，超过即终止。
• 目标任务完成条件：如果你知道完成的标准，比如“日期已经拿到，且用户没有其他要求”，就主动终止。
• 重复工具检测：同一个工具、同样的参数连续被调两次以上，基本可以判定模型在打转，直接中断。
• 用户取消：永远留一个入口，让模型或前端能停止循环。

我甚至建议你在日志里给每个循环打个编号，标记第几步、用什么工具、结果摘要。一旦 Agent 出了问题，你能像回放录像一样看它每一步干了什么。这套日志习惯比任何框架功能都重要。

4.3 怎么评估一个 Agent 做得好不好

这是入门的人很少想、但实际工作一定会遇到的问题。你不能只说“感觉它变聪明了”，要有可量化的指标。

我自己的评估棋盘是这样的：

我先准备一小组测试任务，比如 30 条，人工标好期望结果。然后跑 Agent，记录三个数：任务完成率，也就是成功完成的比例；工具调用准确率，也就是整个任务中，模型选择的工具和参数是否合理；平均耗时和平均 token 成本。每次改提示词、改工具格式，就重新跑一遍这组测试，对比看数值涨跌。

这不是什么高深的评测体系，但它是你做后续一切优化的基准。没有这个基准，你会陷入“改一下试试，好像好一点又好像差一点”的死循环。我强调一句：这句话同样适用于以后你学框架、换模型、调参，先定基线，再谈优化。

5. 再决定要不要学框架：什么时候上框架才合理

5.1 框架到底帮你解决了什么

我不是反对框架，恰恰相反，我把这套逻辑彻底跑通之后，很多日常项目我也会用框架。但我是带着“我已经知道它底层在干什么”的心态去用的。

框架最大的价值在于几个方面。第一，省掉样板代码，比如消息组装、工具注册、重试策略，这些重复劳动框架替你做了。第二，提供标准的接口约定，尤其是 Tool 的输入输出抽象，多团队协作时特别有用。第三，内置很多通用模块，比如记忆、检索、人机交互的 callback，不用自己从零造轮子。这些对你以后的工程效率提升确实很大。

你可以把它理解成“一个经验丰富的项目经理”，已经把需求对齐、排期、风险和异常处理都帮你打了个模板。但前提是你自己得知道项目逻辑，否则模板反而是枷锁。

5.2 框架的坑：版本迭代快、概念多、黑盒

我还是要给你泼点冷水，框架本身有三个问题。

版本迭代快到离谱。很多热门框架每周发新版本，API 说改就改。你上周照着文档写的代码，这周可能就报一堆废弃警告。对新手来说，网上搜到的教程和当前版本不匹配，会让你陷入无尽的排查中。

概念抽象层太厚。Agent、Task、Chain、Memory、Retriever 这些概念层层嵌套。你以为你在配置业务逻辑，其实你被框架的“世界观”绑架了。遇到问题你根本不知道是配置写错了还是框架的 bug，只能去翻源码，花的时间比自己手写还长。

社区教程两极分化。要么是简单到没有营养的 hello world，要么是直接给你一个巨型项目模板，新手根本拆不动。学习体验相当差。

所以我的结论是：在你亲手写过一遍原生 Agent 之前，不建议把框架作为学习主线。等你能用 100 行代码跑通一个带工具调用的 Agent，再学框架，你会感觉非常轻松，甚至想吐槽它“怎么多了一层没必要的东西”。

5.3 我建议的看框架姿势：对照源码，而不是照抄教程

我自己学框架的方法是这样：不追求学会框架的全部功能，只挑我手写代码里已经实现的那些模块，去源码里找对应部分。

比如我已经手写了一个工具注册表，那我就去框架源码里搜 “register” 或者 “tool” 关键词，看它怎么设计的、有没有处理我没想到的边界情况。我已经写了滑动窗口记忆，就去源码里找它的 memory 模块，对比一下它的截断策略和我的有什么不同。

这种“带着问题看源码”的方式，效率大约是看教程的十倍。因为你已经有了实践基础，源码里的每一个抽象你都能映射到具体问题上，而不是被符号和类名牵着鼻子走。看完之后你很可能有两种收获：一种是发现框架比我写得漂亮，吸收它的设计；另一种是发现框架某个地方其实不如你的实现灵活，你以后就知道什么时候不该用它。

6. 新手入门必踩的坑与排查思路实录

6.1 五个高频问题速查表

我把自己带新人过程中最高频的五个问题整理成了一张速查表，你收藏起来，遇到对着看。

这张表里几乎每个问题我都踩过一遍，尤其是“同一个工具被反复调用”，刚开始手写 ReAct 循环的人遇到概率接近百分之百。你记住一个原则：模型不是不听话，是你给它的反馈信息不够清楚，工具结果里没有告诉它“任务已完成”。

6.2 排查 Agent 问题的基础方法论

排查 Agent 和排查普通代码最大的区别是：普通代码是确定性的，Agent 是不确定性的，同一句话跑两次结果可能不一样。所以你没法用“打断点、跑单测”那套思路直接套。

我的方法论就三条：全程日志、回放复现、最小样本。

全程日志指的是，我要求每个环节都打日志。模型原始输出打一份，解析后的工具调用打一份，工具真实返回打一份。三条日志对齐，基本就能定位问题出在模型、解析还是工具。

回放复现指的是，把出问题的对话原封不动地保存下来，下一次跑测试时直接输入同一段历史。这样你可以反复改提示词、改工具，围绕一个固定的样例去验证效果，而不是靠随机撞。

最小样本指的是，别拿一个 50 条任务的复杂测试集去调问题。先把出问题的那一条拎出来，写成一个单测，调通了再扩大范围。单测跑通是底线，跑不通就不要去碰别的任务。

这套方法论在我后来的真实项目里帮了大忙。Agent 的问题排查不能靠直觉和运气，靠的是把不确定的东西尽量变成可回放的过程。

7. 给新手和转行者的三周学习计划

7.1 第一周：大模型 API + 提示词基础

这一周的目标只有一个：把一个模型 API 调得滚瓜烂熟，能用提示词控制它的输出格式。

每天固定写一个练习。比如周二实现多轮对话，周三实现结构化 JSON 输出，周四做一个判断题：“给模型一段文本，让它提取姓名和日期两个字段，输出 JSON”。周五看一篇提示词工程相关的资料，然后把前一天练习加 few-shot 示例重跑一遍。到周末你手写一个简单总结器，把一段会议记录压缩成三条摘要。

第一周最重要的是形成“API 就是编程接口”的直觉。不要觉得调模型是玄学，它就是一次带输入输出的函数调用，只是输出富有不确定性，你需要用提示词和参数去驯服它。

7.2 第二周：工具调用 + 手写第一个 Agent

这周开始进入真正的 Agent 环节。你选一个熟悉的领域，比如查询订单、查天气、做数学计算，设计两个到三个工具，注册到一个工具注册表里。然后实现一个最简 ReAct 循环，让模型根据用户问题选择工具、执行、返回结果。

我建议你第一版先不要让模型自由思考，直接在提示词里写死流程：必须判断是否需要工具，不需要就作答；需要就输出工具调用的 JSON。跑通后再放开约束，让模型自己推理。这周结束时，你手里应该有一个能用自然语言驱动两个工具的 Agent，哪怕它看起来有点笨。

第二周最值得庆祝的时刻是：你发现“这个 Agent 真的会自己选择用工具了”。这一刻你对 Agent 的理解会一下子从纸面名词变成肌肉记忆。

7.3 第三周：记忆 + 评估 + 对框架祛魅

第三周做三件事。第一，给你的 Agent 加上滑动窗口记忆，让它能够连续对话十轮以上不崩溃。第二，准备一组 20 道题的测试集，用手写的方式记录完成率和工具调用准确率。第三，找任何一个你之前想学的热门框架，用“看源码”的方式，对照你自己写的代码理解它的设计。

第三周的核心目标是“祛魅”。你会发现框架里的很多东西你已经实现了，只是它封装得更成熟；同时你也会发现自己的实现确实粗糙，需要用框架补齐边界能力。这一步做扎实了，以后再学任何新框架，你都能快速上手，而不是每次都被框架牵着走。

7.4 三个适合入门的练手项目

如果你不知道自己该做什么练手项目，我给你三个选题，难度从低到高，每一个都能写进项目经历里。

第一个是“个人知识小助手”，让它读取你收藏的文章，接一个向量存储，用问答方式查询。这个项目的关键点是文本切块和检索质量，能让你体会 RAG 的基础套路。

第二个是“自动化周报生成器”，让它通过工具读取本周的 Git 提交记录，自动生成周报并发送到指定的地方。关键点是工具设计，你的“读提交记录”工具必须返回结构化数据，模型才能稳定生成总结。

第三个是“智能客服问答机器人”，让它查询订单状态、退换货政策，遇到查不到的信息时能礼貌地转人工。关键点是循环控制，你必须给足用户明确回复的时机，这是真实场景里最挑剔的能力。

这三个项目做完，你基本能覆盖 Agent 开发的核心场景：检索增强、工具调用、状态管理。面试的时候也很有说服力，因为每一步都是你自己写出来的，不是照抄框架 demo。

写在最后的几句经验

我见过很多入门者倒在不同阶段。有人卡在“调 API 都觉得玄”，有人卡在“模型老是不按格式输出”，也有人卡在“学了框架却发现离不开框架”。说实话，这些都是必经之路，但顺序错了，痛苦会加倍。

我个人最深的体会是：Agent 开发的门槛不在代码，而在“把不可控的东西变成可控”的工程思维。大模型是不可控的，但你可以用提示词约束它；工具结果是不可控的，但你可以用标准化格式驯服它；上下文是有限制的，但你可以用记忆和截断去管理它。这套思维建立起来之后，框架对你来说只是工具，而不是信仰。

如果你现在还在纠结要不要啃框架，听我一句劝：先关掉框架文档，用一个最普通的 API 调用，手写一个最小 Agent，让它在你的电脑上跑起来，哪怕是只会查时间和算加法。等你跑通的那一刻，你对 AI Agent 的理解就超过了 80% 停留在“看过教程”的人。剩下的事，都是你见招拆招之后自然会发生的事。