AI Agent新手学习路线：先掌握四件核心事，再看框架

很多朋友在后台问同一个问题：想做 AI Agent，是不是得先把 LangChain、AutoGen 这些框架学熟？我的回答一向很直接——别急着啃框架，框架恰恰是新手最不该先碰的东西。AI Agent 入门，本质上是搞明白三件事：怎么把大模型当成一个“会思考的函数”来调用，怎么给这个函数装上能动手的工具，怎么让它记住对话过程中产生的重要信息。这三件事弄明白了，框架对你是锦上添花；弄不明白，框架就是一座你永远找不到出口的迷宫。

这篇文章就是写给刚入门的新手和准备转行的人看的。我不打算讲任何框架的 API 用法，只讲 Agent 最底层的运行逻辑，以及你真正需要优先花时间的四个基础模块。最后会给你一条可以直接照着走的学习路线，帮你把时间花在刀刃上。

1. 一上来就啃框架，为什么最容易劝退

1.1 框架解决的是工程问题，不是认知问题

先想清楚一个事实：LangChain 这类框架诞生的初衷，是为了解决“把多个大模型调用串起来”这种偏工程化的编排问题，而不是帮你理解大模型本身。框架做的事情，本质上是在你和大模型之间加了一层封装：帮你拼 prompt、帮你维护消息列表、帮你调度工具、帮你管理记忆状态。

听起来很省事对吧？但问题恰恰出在这里。封装意味着隐藏，隐藏意味着你出了问题根本不知道去哪找。我见过不少新人照着教程搭了一个链，跑通了，然后自己加一个需求，改什么都报错，最后只能把整段代码删掉重来。为什么？因为他不知道框架内部是怎么构造 prompt 的，也不知道消息是怎么流转的，更不知道为什么某个工具调用的结果没被模型看到。

打个不准确的比方：框架像是开发商交楼的精装样板间，看着什么都好，拎包入住，但水电管线全埋在墙里。你住进去第一天灯泡坏了，你连配电箱在哪都不知道，只能干瞪眼。

如果你先自己把“管线”走一遍——自己调一次模型、自己构造消息、自己写工具调用逻辑——再去看框架的源码和文档，你会发现那层封装薄得像一层纸。相反，基础一片空白就冲进框架，每一个报错都是黑盒，每一条文档都像天书。

1.2 框架各有各的“脾气”，切换成本远比想象中高

还有一个更隐蔽的坑：框架之间的概念体系并不统一，甚至可以说是各说各话。我随便举几个例子，你看完就知道我在说什么。

某框架说“链”，某框架说“代理”，某框架说“会话”，还有框架说“团队”。同样是“让模型决定调用哪个工具”这个功能，不同框架的写法千差万别，甚至连 prompt 的组织方式都不一样。你要是先学框架，每换一个框架就等于重新学一套黑话，人很容易就麻了。

转行的朋友尤其要注意这个坑。你转行学 AI，本来要学的核心知识就不少：模型原理、API 使用、提示词设计、数据格式、上下文管理。这些是不管你用什么框架都必须掌握的通用能力。如果一上来就把时间砸在某个框架上，等于把“专业知识”和“工具语法”两件事搅在了一起。将来框架更新换代、你换项目了，专业知识还在，工具语法就清零重来了。

所以我一直建议：先剥离框架，用纯代码把 Agent 的核心循环跑通一次。这一步花的时间不会超过两周，但会给你后面省下无数个抓狂的夜晚。

2. 新手和转行者只需先学这四件事

2.1 第一件事：把大模型当成一个可编程的“函数”来调用

很多人听说过“大模型 API”这个概念，但真到写代码的时候，又总觉得这是某个神秘的云服务，跟自己的程序是两套体系。实际上没那么玄。你就把一次 API 调用当作一次远程函数调用：你传一段文本进去，它返回一段文本出来。

这里有一个最容易被忽略的认知：API 本身是没有记忆的。你每一次调用，都要把之前所有的对话历史重新发一遍。这是理解 Agent 的基石——所谓“多轮对话”不是模型记住了你，而是你的程序每次都在把我们俩之前聊过的话原封不动地打包发过去。

写代码之前，先认清几个核心参数：

• messages：整个消息列表，每条消息都有role（system、user、assistant，tool）和content。system 就是给模型立规矩的，user 是用户输入，assistant 是模型回复。
• temperature：控制随机性，越低越稳定，越高越发散。做 Agent 我一般建议设成 0.2 以下，否则它发挥不稳定。
• max_tokens：控制输出长度，注意它不控制输入长度，只控制新生成多少 token。
• stream：是否流式返回。流式体验好，但对程序逻辑要求更高，新手可以先不碰。

一个最基础的 Python 调用长这样：

import os from openai import OpenAI client = OpenAI(api_key=os.getenv("LLM_API_KEY")) def ask_llm(messages, temperature=0.2, max_tokens=500): response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, temperature=temperature, max_tokens=max_tokens, ) return response.choices[0].message.content # 第一次调用 messages = [ {"role": "system", "content": "你是一个耐心、严谨的技术助手。"}, {"role": "user", "content": "请用一句话解释什么是 Agent。"}, ] print(ask_llm(messages))

注意我上面特意把调用封装成了一个函数。为什么？因为后面你所有 Agent 逻辑都会反复用到这个函数，封装好它，后面代码才能干净。很多新手上来就在业务代码里到处裸写 API 调用，后面想统一加个日志或重试机制，改起来想哭。

如果你第一次跑这个脚本就报错，先别慌，多半不是代码问题，而是环境问题，后面我会专门写一节排查清单。

2.2 第二件事：提示词是结构，不是玄学

提示词工程被很多人讲得神乎其神，其实底层逻辑非常简单：你给模型的信息越结构化，它的输出就越可控。不要指望一句“你帮我分析一下吧”就能得到可用于生产的输出——这种输入，模型只能给你一个掷骰子式的答案。

我自己写提示词一般遵循一个五件套结构：

1. 角色定义：你是谁。
2. 任务目标：你要完成什么。
3. 约束条件：你不能做什么、必须做到什么。
4. 输出格式：以什么格式输出，最好给出模板。
5. 示例：给一个输入输出对照，这是最重要的。

举个例子，假设你要做一个工单处理助手：

system_prompt = """ 你是一名IT工单处理助手。你的任务是根据工单的状态信息，给用户一个清晰的处理建议。 约束： - 只能依据提供的工单信息回答，不能编造不存在的处理记录。 - 如果工单状态是“处理中”，建议时给出等待时长预期。 - 回答必须控制在150字以内。 输出格式： 按以下模板输出： 工单当前状态：{状态} 初步判断：{结论} 建议动作：{建议} 示例： 工单当前状态：待处理 初步判断：该工单尚未有人受理。 建议动作：请先联系值班人员进行受理，并设置响应时限。 请开始处理，工单信息如下： {工单信息} """

注意这段提示词把输出格式“焊死”了。为什么要这样？因为后续如果要做结构化输出，比如让模型返回 JSON，你提前把格式约束好，后面解析才稳定。

我还想单独强调一下示例的作用。模型不是靠规则理解你要什么，而是靠模式。你给的示例越多、越贴合实际场景，它跑偏的概率就越低。如果你要的是一种比较特殊的输出格式，务必给两个示例，一个正常情况，一个边界情况。

我自己做 Agent 的时候，会专门维护一个“提示词模板库”，把不同任务的 system prompt 都放在同一个目录下，用配置去加载，而不是散落在代码里。这属于工程习惯，但越早养成越好。

2.3 第三件事：给 Agent 装上“手”——函数调用

如果说提示词是 Agent 的大脑，那函数调用（Function Calling）就是它的手。这也是 Agent 区别于普通聊天机器人的关键：它不只“动嘴说”，还能真的去查数据库、调接口、操作文件。

原理不复杂。你告诉模型：“我有这些工具可以用，等你需要时，你就输出一个特殊结构，告诉我你想用哪个工具、传什么参数。”模型理解后，会返回一段 JSON 结构化的工具调用请求。此时代码并没有真正执行工具，只是拿到了一张“调用申请单”。接下来由你的代码来执行真正的函数，把执行结果作为一条新的消息再发给模型，模型基于结果做最终回答。

举个最简例子。假设我们有两个工具：一个是查天气，一个是做计算。我们这样声明：

tools = [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名，如北京"} }, "required": ["city"] } } }, { "type": "function", "function": { "name": "calculator", "description": "执行四则运算表达式", "parameters": { "type": "object", "properties": { "expression": {"type": "string", "description": "数学表达式，如 (12+3)*4"} }, "required": ["expression"] } } } ]

然后调用模型时，把tools传进去。模型的返回里会多一个字段tool_calls，里面带着它想调用的函数名和参数。你的代码读取这个字段，执行对应的函数，再把结果作为role="tool"的消息追加回去，然后再次调用模型。

这里有一个新手必踩的坑：误以为模型“调用”了工具，所以工具逻辑应该在框架内部自动执行。不是的。模型只输出一个意图，真正执行函数的是你。你的代码才是那个“手”，模型只是“大脑”。搞清楚这个关系，后面排查问题能省一大半力气。

函数调用是 Agent 入门里最实用也最容易出成就感的部分。当你看到模型说“我来帮你查一下”，然后你的代码真的去发起查询、把结果塞回去、模型再对结果进行解释时，你会第一次感受到“这一个体行为闭环”的乐趣。这种正反馈对新手很重要。

2.4 第四件事：让 Agent 记住重要信息——上下文管理

前面说了 API 是没有记忆的，那 Agent 的多轮对话怎么实现？靠程序维护一个消息列表，不断把历史消息追加进messages里。这是最朴素的记忆方案，但马上就撞上一堵墙：上下文窗口是有限的。

模型能接收的输入 token 是有限的。哪怕现在的模型号称支持超长上下文，但上下文越长，成本越高，响应越慢，模型还可能“迷失”在长篇历史里，抓不住重点。所以你不能无限往里面塞历史，必须做上下文管理。

新手至少要掌握三种策略：

策略一：截断。只保留最近的 N 条消息，更早的直接丢掉。实现简单，但丢掉的可能是重要信息。

策略二：摘要。每过一段时间，把旧消息交给模型总结成一段摘要，后续只带摘要+最近消息。能保留主要信息，但会丢失细节，多次压缩后失真。

策略三：向量检索。把所有历史消息切块、向量化存入向量数据库，每次提问时只把与当前问题相关度最高的几条片段取出来，拼接进上下文。这个最“高级”，能保留大量记忆，但前期工程成本高，新手不建议第一个上手就搞。

不同记忆策略的取舍，我用一张表给你看：

我这几年带人的经验是：新手项目先用截断，撑不住再加摘要，向量检索等你对 Agent 整体手感有了再玩。别一上来就上向量数据库，那个坑更多，后续会讲哪些坑。

3. 动手写一个最小可用 Agent 的完整过程

3.1 场景设定：工单查询与处理建议助手

纸上谈兵讲再多，不如手写一遍。下面我带你写一个非常小的 Agent，场景是“工单查询与处理建议助手”。嗯，它需要：

• 通过函数调用查询工单状态。
• 根据状态给用户处理建议。
• 支持多轮对话，区分工单查询和日常寒暄。

我不依赖任何 Agent 框架，只用纯 Python 加一个模型 API。先定义两个工具函数，但为了便于你演练，这里用模拟数据：

# 模拟工单数据库 TICKETS_DB = { "TK1001": {"status": "处理中", "create_time": "2025-01-10", "handler": "张工"}, "TK1002": {"status": "已解决", "create_time": "2025-01-08", "handler": "李工"}, "TK1003": {"status": "待处理", "create_time": "2025-01-12", "handler": None}, } def get_ticket_status(ticket_id): """查询工单状态""" info = TICKETS_DB.get(ticket_id) if info is None: return f"未找到工单 {ticket_id}" return f"工单{ticket_id}状态：{info['status']}，创建于{info['create_time']}，处理人：{info['handler'] or '暂无'}" def escalate_ticket(ticket_id): """升级工单优先级""" if ticket_id in TICKETS_DB: TICKETS_DB[ticket_id]["handler"] = "优先处理队列" return f"工单{ticket_id}已升级并加入优先处理队列" return f"未找到工单 {ticket_id}"

3.2 Agent 主循环：三步走

核心循环只有三步：把当前消息发给模型 → 检查模型是否要求调用工具 → 如果要求则执行工具并回填，再让模型回复。就这么简单。

先定义工具注册表，把函数名映射到真实函数：

# 工具函数注册表 FUNC_MAP = { "get_ticket_status": get_ticket_status, "escalate_ticket": escalate_ticket, }

然后写主循环，注意这里的日志打印非常重要，新手调试全靠它：

def run_agent(user_input): messages = [ {"role": "system", "content": "你是IT工单助手，需要根据工具查询结果回答问题。"}, {"role": "user", "content": user_input}, ] while True: print(">>> 正在发送消息给模型，消息条数:", len(messages)) response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, tools=tools, tool_choice="auto", ) msg = response.choices[0].message # 如果没有工具调用请求，直接返回最终回答 if not msg.tool_calls: return msg.content # 有工具调用：先把模型这条消息加入历史 messages.append(msg) # 逐一执行工具调用 for tool_call in msg.tool_calls: fn_name = tool_call.function.name fn_args = json.loads(tool_call.function.arguments) print(f">>> 模型要求调用: {fn_name}, 参数: {fn_args}") result = FUNC_MAP[fn_name](**fn_args) print(f">>> 工具返回: {result}") # 把工具执行结果作为一条新消息加入历史 messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": result, }) # 带着工具结果再次进入循环，模型会基于结果给出最终答案

上面的while True就是 Agent 循环的精髓。模型每次返回可能有三种情况：

1. 直接给最终回复 → 循环结束。
2. 要求调用一个工具 → 执行后继续循环。
3. 要求连续调用多个工具 → 代码会一次执行完，然后继续循环。

这个循环看起来简单，但它已经是一个完整的 Agent 了。它可以自主决定“要不要用工具”“用什么工具”，并且能根据工具返回的结果继续推理。

3.3 跑一遍，看看效果

我用这个脚本跑了一次真实对话，输入是：

你好，帮我查一下工单TK1003，顺便看下它是不是需要升级处理。

模型先判断这是一个查询请求，于是触发工具调用，返回get_ticket_status(TK1003)。代码执行后把结果回填，模型看到“状态是待处理、处理人暂缺”，判断合适触发升级，于是又触发escalate_ticket(TK1003)。执行后再回填，模型这才给出最终回答：

工单TK1003当前状态是待处理，且暂无处理人，建议已自动发起升级流程，已加入优先处理队列。请相关同事及时跟进。

注意看这个完整链路：从“判断”到“行动”到“再判断”再到“总结”，一共走了两轮工具调用。这就是 Agent 和普通助手的本质区别——它不是一步回答完问题，而是像人一样，查一步、想一步、再走一步。能自己“多走几步”，才有资格叫 Agent。

这个例子只有八十行代码，但已经覆盖了前面讲过的四大基础：API 调用、结构化提示词、函数调用、消息回填。把这八十行代码吃透，再看任何框架，你会觉得它们的文档突然变得好懂很多。

4. 新手必看的常见问题与排查实录

我在给新人做代码审查时，发现很多“看起来是框架问题”的报错，刨到底都是下面这几类基础问题。我把最常见的几种汇总成一份排查实录，你照着对号入座即可。

4.1 API 调用大面积报错：凭证、超时与限流

症状：第一次调 API 就 401、403、超时，或者连续调用几次后突然 429。

原因无外乎三种：API Key 配错了、网络代理不对、调用频率超限。这里我想多说一句，很多人把多轮对话写成循环后，没做任何限速控制，结果连续快速请求直接触发限流，报 429。这时不要硬等，代码里要加重试和退避机制。

import time import random def call_with_retry(messages, max_retries=3): for i in range(max_retries): try: return client.chat.completions.create(model=..., messages=messages) except Exception as e: if i < max_retries - 1: sleep_time = 2 ** i + random.random() time.sleep(sleep_time) else: raise e

4.2 工具返回的结果没被模型看到

症状：模型说“我没法获取工单信息”，但日志里明明已经执行了工具函数。

几乎所有原因都指向同一处：你把工具执行结果返回给模型的格式不对。模型要求工具结果必须以role: "tool"格式回填，且tool_call_id必须和模型返回的一致。很多人漏掉tool_call_id，模型就不知道这条工具结果对应哪次调用，自然就“看不到”。

4.3 模型老是不按格式输出

症状：你想让它输出 JSON，它总是给你带一堆解释文本；你想让它限定字数，它说废话。

这个问题只靠提示词还不好彻底解决，我推荐两层方案：第一，提示词里用强约束 + 示例；第二，代码层做输出校验，解析失败就重新调用一次模型并带回错误信息，让模型自己修正。第二种方案特别有效，可以试试。

def parse_json_safe(text): try: return json.loads(text) except Exception: return None

4.4 上下文越长，Agent 越“傻”

症状：任务刚开始很正常，聊了二十轮后，模型开始答非所问，甚至重复以前说过的话。响应时间也肉眼可见地变慢。

这就是典型上下文爆掉。前面我们提过要截断，这里给一个简单可用的策略：只保留最近十条消息，加上最早的系统提示和最新的用户问题，中间的全部丢给模型做一次摘要压缩。

4.5 常见问题速查表

5. 基础到位后，再谈框架与学习路线

5.1 什么时候才轮得到框架

基础打牢之后，框架自然有用武之地。我给你一个判断标准：当你发现自己手写代码里出现了大量重复的“用工具循环”逻辑，或者你的 Agent 不再只有一个，而是多个 Agent 需要协作、共享状态、编排任务时，框架的工程价值就出来了。

一个好的框架能帮你解决：工作流持久化、多 Agent 通信、重试调度、模型服务切换、插件机制。这些是工程问题，不是认知问题。此时你已经知道底层发生了什么，再用框架就是“抄作业但知道作业为什么这么写”，和新人阶段“对着作业抄还抄串行”是完全两码事。

5.2 挑框架的四个维度

等你要挑框架了，不要只看谁热度高，从四个维度判断：

• 可调试性：报错信息是否清晰？能否方便地看到 prompt 日志和工具调用记录？
• 抽象层级：越底层越好调，越高层越省事，但越难排查问题。
• 生态完整度：有没有人解决过你要的需求，比如数据库集成、权限控制、部署方案。
• 维护活跃度：看最近的发布频率、Issue 回复速度，别选一个年久失修的项目。

我个人新起项目时，反而会先看看它能不能“降级使用”。如果一个框架要求我必须按它规定的写法来，我会果断放弃。框架应该是我的脚手架，不是我的笼子。

5.3 给转行者的一条务实学习路线

最后，给准备转行或刚入门的朋友一条时间线，这是我自己带人验证过比较稳的节奏：

请注意，我特意在第3-4周安排了“不依赖框架手写项目”，这是整条路线里最枯燥但最值钱的一步。过了这一关，你后面哪怕用再复杂的框架，出问题也能自己拆开看明白。

学 Agent 真的没有什么神秘捷径。框架会过时，模型会更新，但“消息往返、工具调用、记忆管理”这套逻辑，短时间不会变。把这三件事练熟，就是你在这个领域安身立命的底气。

最后再分享一个我自己的心得：调试 Agent 的时候，一定要养成看日志的习惯，把每一次模型输入输出、每一次工具调用全都打出来，你会亲眼看到模型“思考”的过程。这东西看多了，所谓黑盒在你眼里慢慢就透明了——这才是入门最宝贵的收获。