AI Agent入门：先学底层原理，再碰框架

1. 为什么一上来就啃框架是新手最大的坑我带过不少想转行做 AI Agent 的朋友也看过很多新手的学习路径发现一个特别普遍的现象打开某个主流 Agent 框架的官方文档看到一堆概念——Chain、Tool、Memory、Retriever、Agent Executor——然后就开始照着示例代码一行行敲敲完跑通了觉得自己入门了。但一旦需求稍微变一下比如换个模型、加个自定义工具、处理多轮对话里的上下文丢失问题整个人就懵了。这不是个别现象而是学习路径本身出了问题。框架是别人对一类问题的抽象和封装它默认你已经理解了被封装的那些底层概念。你直接跳到抽象层相当于还没学会加减法就去解方程能套公式算出答案但不知道为什么要这样算。我个人的判断是AI Agent 入门阶段最该先搞清楚的是“一个 Agent 到底由哪些基本部件组成、每个部件解决什么问题”而不是“某个框架怎么调用”。框架会过时、会换 API、会改设计哲学但底层那套东西——模型怎么被调用、工具怎么被描述和选择、上下文怎么管理、循环怎么终止——这些是相对稳定的。这篇文章就是想把这条学习路径讲清楚。适合两类人一类是完全没有 AI 应用开发经验的新手另一类是从传统开发比如后端、前端、数据分析想转到 AI Agent 方向的从业者。我会先讲清楚该学什么、按什么顺序学再讲每个环节的实操要点和踩坑经验最后给一套可以直接照着走的学习路线。全程不绑定任何具体框架因为我想让你学的是“能力”不是“某个工具的用法”。2. 先建立认知地图Agent 到底由什么组成2.1 用生活类比理解 Agent 的本质你可以把一个 AI Agent 想象成一个刚入职的助理。这个助理很聪明但有几个特点他只能通过文字和你沟通他记性有限聊太久会忘掉前面说过的内容他不能直接操作电脑需要你告诉他“你可以用哪些工具”他有时候会自作主张需要你给他划清边界。对应到技术层面一个 Agent 系统通常包含这几个核心部件模型大脑负责理解意图、做决策、生成内容。它是整个系统的推理核心。工具手脚模型本身只能生成文字要让它查数据、发请求、读写文件必须给它提供可调用的函数。上下文/记忆记事本模型每次调用都是无状态的你需要把历史对话、任务状态、中间结果组织好再喂给它。控制循环工作流程决定什么时候调用模型、什么时候调用工具、什么时候结束。这是 Agent 和普通“一问一答”最本质的区别。新手最容易忽略的是最后一点。很多人以为 Agent 就是“模型加工具”其实真正让它“动起来”的是那个循环模型输出一个动作意图系统执行这个动作把结果再喂回模型模型再决定下一步直到任务完成。这个循环的设计才是 Agent 开发的核心难点。2.2 为什么底层概念比框架 API 更值得先学我举个具体的例子。假设你要做一个“根据用户问题自动查数据库并回答”的 Agent。用框架的话可能是几行配置的事。但如果你不理解底层遇到下面这些问题就会卡住模型总是选错工具明明该查数据库却去调了计算器为什么——因为工具的描述description写得不够清晰模型是靠这段文字来判断的。多轮对话后模型开始胡言乱语为什么——因为上下文窗口塞满了无关历史或者关键信息被截断了。任务执行到一半死循环为什么——因为循环没有设置最大步数或终止条件。这些问题框架文档里往往一笔带过但实际开发中天天遇到。你只有理解了“模型是怎么根据工具描述做选择的”“上下文是怎么被组织和截断的”“循环是怎么被控制的”才能对症下药。所以我的建议很明确入门阶段先用最原始的方式直接调模型 API 手写循环把一个小 Agent 跑通理解每个部件的作用再去用框架提效。这样你学框架的时候是在学“它帮我封装了什么”而不是“它让我填什么参数”。2.3 一张学习优先级清单我把入门阶段该学的东西按优先级排一下你可以对照自己的情况看优先级学习内容为什么重要建议投入时间高模型 API 的基本调用输入输出格式、参数一切的基础不理解这个后面都是空中楼阁1-2 天高提示词的基本写法角色、指令、格式约束模型的行为高度依赖你怎么说3-5 天高工具调用的原理怎么描述工具、怎么解析调用Agent 能“做事”的关键3-5 天中上下文管理与简单记忆决定多轮任务能不能跑通2-3 天中控制循环的设计终止条件、错误处理决定 Agent 稳不稳定3-5 天低具体框架的使用提效工具可后置按需这张表的核心逻辑是先学“不可变”的再学“可变”的。模型 API 的调用方式、提示词的写法、工具调用的原理这些是跨框架通用的而某个框架的具体 API换个框架就作废了。3. 核心基础一模型调用与提示词别小看这两件事3.1 模型 API 调用先搞懂“输入什么、输出什么”很多人觉得调模型 API 很简单不就是发个请求拿个回复吗但实际开发中你需要搞清楚几个关键点第一消息的角色role是怎么划分的。通常有 system、user、assistant 三种角色。system 用来设定模型的整体行为user 是用户输入assistant 是模型的回复。在 Agent 场景里工具调用的结果通常也以特定角色比如 tool 或 function回传。理解角色划分是理解上下文组织的第一步。第二输出格式的控制。普通对话你不需要管格式但 Agent 场景里你经常需要模型输出结构化的内容比如一个 JSON里面包含“要调用哪个工具、传什么参数”。这时候就要用到格式约束比如要求模型输出 JSON或者使用模型提供的结构化输出能力。第三参数的影响。温度temperature控制随机性Agent 场景通常要调低因为你需要稳定的决策最大输出长度max tokens决定回复能有多长设太小会导致工具调用参数被截断。我建议你入门时先不借助任何封装库直接用 HTTP 请求或官方 SDK 调一次模型把请求体和响应体完整打印出来看一遍。这一步很多人跳过但它是建立直觉的关键。你会亲眼看到哦原来模型收到的是一串消息列表返回的是一段文本加一些元信息。3.2 提示词Agent 的“岗位说明书”提示词在 Agent 里的作用比在普通对话里重要得多。普通对话里提示词影响回复质量Agent 里提示词直接决定模型会不会正确调用工具、会不会跑偏、会不会死循环。我踩过的一个坑是早期写工具描述时只写了“查询天气”结果模型经常在不该查天气的时候也去查。后来我把描述改成“当用户明确询问某个城市的当前天气时使用此工具其他情况不要调用”误调用率立刻降下来了。写 Agent 提示词我总结了几条实操经验角色要具体不要写“你是一个助手”要写“你是一个负责处理订单查询的客服 Agent你只能通过提供的工具获取信息不能编造”。工具描述要写清楚“什么时候用”和“什么时候不用”模型是靠这段文字做选择的模糊的描述会导致错误调用。输出格式要明确如果需要模型输出工具调用就明确告诉它格式最好给一个例子。边界要划清告诉模型遇到不确定的情况该怎么办比如“如果工具返回错误最多重试两次然后告知用户”。提示提示词不是写一次就完事的它需要根据实际运行效果反复调整。建议你把每次调整和对应的效果记录下来慢慢就形成自己的“提示词手感”了。3.3 一个最小可运行示例下面这段代码展示了不借助任何 Agent 框架直接调模型并手动处理工具调用的最小结构。语言用 Python你可以照着改import json # 假设这是你的模型调用函数返回模型输出的文本 def call_model(messages): # 实际项目中这里替换为真实的模型 API 调用 # 返回模型生成的文本 pass # 定义工具 tools [ { name: get_weather, description: 当用户明确询问某个城市的当前天气时使用。参数为城市名。, parameters: {city: string} } ] # 工具的实际执行函数 def execute_tool(name, params): if name get_weather: # 实际项目中这里调用天气 API return f{params[city]}今天晴25度 return 未知工具 # 手动控制循环 def run_agent(user_input, max_steps5): messages [ {role: system, content: 你是一个助手可以使用工具。需要工具时输出 JSON{\tool\: \工具名\, \params\: {...}}}, {role: user, content: user_input} ] for step in range(max_steps): response call_model(messages) messages.append({role: assistant, content: response}) # 判断模型是否要调用工具 try: action json.loads(response) if tool in action: result execute_tool(action[tool], action.get(params, {})) messages.append({role: user, content: f工具返回{result}}) else: return response except json.JSONDecodeError: # 不是 JSON说明是普通回复任务结束 return response return 达到最大步数任务未完成这段代码很粗糙但它把 Agent 的核心结构完整暴露出来了消息列表、工具定义、循环、终止条件。你把这个跑通再去用框架就会明白框架帮你省了哪些事。4. 核心基础二工具调用与上下文管理4.1 工具调用Agent 从“会说”到“会做”的关键工具调用的本质是让模型输出一段结构化的内容告诉系统“我要调用哪个函数、传什么参数”系统执行后把结果回传。这里面有几个容易出问题的地方工具描述的质量直接决定调用准确率。我见过太多新手把工具描述写成“查询数据”“处理请求”这种模糊表述然后抱怨模型老选错。工具描述要像写给一个新员工的说明这个工具做什么、什么时候用、参数是什么格式、返回什么。越具体越好。参数校验不能省。模型输出的参数不一定符合你的预期可能缺字段、类型不对、甚至编造不存在的参数。系统在执行工具前必须做校验不合法就返回错误信息让模型重试而不是直接崩溃。工具数量要控制。一次性给模型几十个工具它的选择准确率会明显下降。实践中我通常把工具控制在 10 个以内如果确实需要很多工具就做分组或分层让模型先选类别再选具体工具。错误处理要设计好。工具执行失败是常态网络超时、参数错误、权限不足都可能发生。你要决定是让模型重试、换工具、还是直接告知用户失败。这个决策逻辑最好写在提示词里让模型有章可循。4.2 上下文管理为什么你的 Agent 聊着聊着就“失忆”了上下文管理是新手最容易低估的部分。模型每次调用都是无状态的它看到的只有你这次传进去的消息列表。所以“记忆”这件事完全是你自己实现的。最简单的做法是把所有历史消息都带上。但这样很快会遇到问题上下文窗口有限聊久了就塞不下而且无关历史会干扰模型判断。我实测下来一个任务型 Agent 如果无脑带上全部历史跑到十几轮之后模型开始忽略最新的指令反而去回应很早之前的内容。我的做法是分层管理系统提示词始终保留放在最前面。当前任务相关的上下文比如用户最初的需求、已经确认的关键信息这些要保留。近期对话保留最近几轮保证连贯性。远期历史做摘要压缩或者直接丢弃。摘要压缩是个实用技巧当历史消息超过一定长度就调用模型把前面的内容总结成一段简短的话替换掉原始消息。这样既保留了关键信息又控制了长度。注意摘要会丢失细节所以关键信息比如用户明确给出的参数、已经确认的决策不要依赖摘要要单独结构化存储。4.3 一个上下文管理的实操方案下面这个结构是我在实际项目中常用的你可以参考class ContextManager: def __init__(self, max_recent6): self.system_prompt self.key_facts [] # 结构化存储的关键信息 self.recent_messages [] # 近期对话 self.summary # 远期历史的摘要 self.max_recent max_recent def add_message(self, role, content): self.recent_messages.append({role: role, content: content}) if len(self.recent_messages) self.max_recent: self._compress() def _compress(self): # 把最早的两条消息并入摘要 to_compress self.recent_messages[:2] self.recent_messages self.recent_messages[2:] # 实际项目中这里调用模型做摘要 new_text .join([m[content] for m in to_compress]) self.summary (self.summary new_text).strip() def build_messages(self): messages [{role: system, content: self.system_prompt}] if self.summary: messages.append({role: system, content: f历史摘要{self.summary}}) if self.key_facts: facts .join(self.key_facts) messages.append({role: system, content: f关键信息{facts}}) messages.extend(self.recent_messages) return messages这个方案的核心思想是把“记忆”拆成不同层次每层用不同的策略处理。关键信息结构化存储近期对话原样保留远期历史压缩成摘要。这样既控制了长度又尽量不丢信息。5. 核心基础三控制循环与错误处理5.1 循环设计Agent 的“心跳”控制循环决定了 Agent 怎么一步步推进任务。最简单的循环是调用模型 → 如果有工具调用就执行 → 把结果回传 → 再调用模型 → 直到模型不再调用工具或达到最大步数。但实际场景里你需要考虑更多终止条件要明确。除了“模型不再调用工具”还要设置最大步数、最大耗时、最大 token 消耗。我踩过的坑是有一次模型陷入了一个“调用工具 → 结果不满意 → 再调用同一个工具”的死循环因为没有设最大步数跑了几十轮才被我发现。中间状态要可观测。每一步模型输出了什么、调用了什么工具、返回了什么结果都要记录下来。不然出了问题你根本不知道是哪一步错的。我通常会把每一步的完整信息写到日志里调试的时候一目了然。异常要能恢复。工具调用失败、模型返回格式错误、网络超时这些都要有对应的处理逻辑。我的做法是把错误信息作为工具结果回传给模型让模型决定下一步。大多数情况下模型看到错误信息后会调整策略。5.2 错误处理让 Agent 在出错时“优雅地失败”新手写的 Agent一出错就整个崩掉。但实际生产环境里出错是常态关键是怎么处理。我把错误分成三类可重试错误网络超时、临时限流。这类错误直接重试通常重试一两次就好了。可恢复错误参数格式不对、工具返回空结果。这类错误把信息回传给模型让它调整。不可恢复错误权限不足、工具不存在。这类错误直接终止任务告知用户。对应到代码里就是给工具调用包一层错误处理def safe_execute_tool(name, params, max_retry2): for attempt in range(max_retry): try: result execute_tool(name, params) if result is None: return {error: 工具返回空结果请检查参数} return {result: result} except TimeoutError: if attempt max_retry - 1: return {error: 工具调用超时请稍后重试} continue except Exception as e: return {error: f工具执行失败{str(e)}}这个结构把错误信息结构化后回传给模型模型看到error字段就知道这次调用失败了可以选择重试、换工具或告知用户。5.3 循环步数的经验值最大步数设多少合适这个没有标准答案但根据我的经验简单任务单次工具调用3-5 步足够。中等任务多步推理 多次工具调用10-15 步。复杂任务需要反复调整策略20-30 步。设太小会导致任务没完成就中断设太大又浪费资源。我的做法是先设一个保守值比如 15观察实际运行时的步数分布再调整。如果发现大部分任务都在 5 步内完成那 15 就够用了如果经常撞到上限说明要么任务确实复杂要么提示词有问题导致模型绕弯路。6. 常见问题与排查技巧实录6.1 模型不调用工具怎么办这是新手最常遇到的问题。模型明明有能力调用工具但它就是直接回复文字不输出工具调用。排查思路检查工具描述是否清晰模型是靠描述判断的描述模糊它就不敢调。检查提示词是否明确要求使用工具有时候需要在系统提示词里明确写“你必须通过工具获取信息不能凭记忆回答”。检查输出格式约束如果要求模型输出 JSON但没给例子模型可能不知道怎么输出。检查模型能力不是所有模型都支持工具调用确认你用的模型有这个能力。我的经验是90% 的情况是工具描述或提示词的问题不是模型的问题。6.2 模型选错工具怎么办模型在多个工具之间选错了。常见原因和解决方法现象可能原因解决方法总是选某个不相关的工具该工具描述太宽泛收窄描述明确使用场景该用 A 却用了 BA 和 B 描述太相似在描述里写清楚两者的区别该调用工具却直接回答提示词没强调必须用工具在系统提示词里明确要求参数传错参数说明不清晰给出参数格式示例6.3 Agent 陷入死循环怎么办死循环的表现是模型反复调用同一个工具或者反复输出相同的内容。排查思路检查工具返回结果如果工具一直返回错误或空结果模型可能会一直重试。确保工具在正常情况下能返回有效结果。检查提示词里的重试逻辑如果提示词说“失败就重试”但没说重试上限模型可能无限重试。明确写“最多重试两次”。设置硬性最大步数这是最后的防线不管什么原因到了步数上限就强制终止。6.4 上下文太长导致模型“失忆”表现是聊到后面模型忘记了前面说过的关键信息或者开始重复之前的内容。解决方法结构化存储关键信息不要依赖模型自己记住把关键参数、已确认的决策单独存起来每次调用时放在系统提示词里。压缩历史用摘要替换远期历史。控制单次输入长度如果单条消息特别长比如工具返回了一大段数据考虑截断或摘要后再喂给模型。6.5 我的避坑清单最后整理一份我踩过的坑你可以直接对照检查工具描述写得太简单导致模型误调用。没有设置最大步数导致死循环消耗大量资源。上下文无脑全带导致模型被无关信息干扰。工具执行没有错误处理一出错整个流程崩溃。提示词里没有明确输出格式导致解析失败。没有记录中间步骤出问题无法定位。一次性给太多工具模型选择困难。忽略了模型的输出长度限制导致工具调用参数被截断。7. 一套可以直接照着走的学习路线7.1 第一周打地基目标理解模型调用的基本流程能写出稳定的提示词。第一天到第二天直接调模型 API打印请求和响应理解消息角色和参数。第三天到第五天练习写提示词从简单角色设定到复杂的格式约束观察不同写法对输出的影响。第六天到第七天写一个不涉及工具调用的多轮对话程序手动管理上下文。这一周的关键是“动手”不要只看文档。每改一次提示词就跑一次看效果记录差异。7.2 第二周让 Agent 动起来目标理解工具调用原理能写出一个能调用工具的最小 Agent。第一天到第三天定义两三个简单工具比如查时间、做计算手动实现工具调用循环。第四天到第五天加入错误处理和最大步数限制测试各种异常情况。第六天到第七天加入简单的上下文管理测试多轮任务。这一周你会遇到大量问题这正是价值所在。每解决一个问题你对 Agent 的理解就深一层。7.3 第三周引入框架提效目标在理解底层的基础上用框架重写之前的 Agent体会框架的便利和局限。选一个主流框架用它重写第二周的最小 Agent。对比手写版本和框架版本理解框架封装了什么、牺牲了什么。尝试框架的高级功能比如多 Agent 协作、复杂记忆管理。这时候你学框架是在“验证自己的理解”而不是“从零猜测”。效率完全不一样。7.4 后续方向基础打牢之后你可以往几个方向深入多 Agent 协作多个 Agent 分工合作完成复杂任务。RAG 结合让 Agent 能检索外部知识库。评估与优化建立评估体系持续优化 Agent 的表现。生产化日志、监控、限流、成本控制。我个人在实际操作中的体会是入门阶段最忌讳的就是“贪快”。我见过太多人一周换一个框架每个都只跑通了示例但遇到实际问题就束手无策。反而是那些愿意花两周时间手写最小 Agent 的人后面学什么都快。因为底层那套东西是相通的框架只是换了个壳。你把壳下面的东西搞明白了换什么壳都不慌。