AI Agent这个词过去一年快被聊烂了。但真让我带过几个从零起步的朋友之后我发现一个很扎心的事实绝大多数人卡住的地方根本不是Agent这个概念有多难而是不知道要从哪里开始。打开搜索引擎教程一篇接一篇这个讲提示词那个讲Function Calling还有讲向量数据库的、讲多Agent协作的单独看都挺好串不起来。学了两个星期连一个能跑的Demo都没有。于是就有了这套教程和这篇前言导读。我要做的就是给你一条清晰、可执行的路径从搭环境、调通第一个API开始一步步走到规划、记忆、工具调用最后完成一个真正在干活的Agent项目。这篇导读不写代码先把路线图、学习方法和避坑思路讲清楚相当于整个系列的总入口。适合谁看有三类人我觉得特别对口一是会一点Python、想往AI应用方向转的开发者二是已经在写业务代码、想让系统具备自动化能力的工程师三是产品经理、运营这类非技术岗位想搞懂Agent能做什么、不能做什么。另外如果你正在带团队做AI相关的事情这篇导读也能帮你评估团队成员适合走哪条学习路径方便安排后续的培训和分工。1. 教程定位与整体设计思路1.1 为什么是一条主线而不是知识点合集现在网上的Agent资料有一个普遍问题碎片化。刷到某篇文章讲Function Calling讲得很细另一篇讲记忆机制讲得也不错但没有任何一篇能把你从我知道Agent有记忆带到我能自己实现一套记忆管理。大多数初学者缺的不是某一个知识点而是把知识点串起来的那条主线。这套教程想做那条主线。我在实际项目里用Agent做过不少事自动整理会议纪要、定时巡检服务器日志并生成日报、帮运营团队批量生成商品描述然后交给人工审核。每个项目单独看都不复杂但把它们放在一起就会发现Agent开发的套路是固定的——模型负责理解与生成外围代码负责规划、记忆和工具调度。这个固定套路就是整套教程的核心主线。教程的另一个目的是帮读者建立最小可行闭环的概念。很多人学了一堆概念却做不出东西就是因为没有在第一时间跑通一个完整的循环用户输入 - 模型判断 - 调用工具 - 返回结果。这套教程从第03篇开始就会带着你跑通这个循环之后所有内容都是在这个骨架上做增强。你后面看到的记忆机制、规划策略、多轮对话管理本质上都是往这个基础循环里加模块而不是推翻重来。1.2 章节地图八篇内容带你跑完全程整套教程按认知 - 基础 - 机制 - 实战四个层次展开共八篇正文加这篇导读章节安排如下章节主题学完后你能做到第00篇前言与导读本文看清学习路径、明确前置条件第01篇开发环境与第一次模型调用调通API拿到第一个结构化输出第02篇提示词工程基础与JSON输出让模型稳定按指定格式返回结果第03篇Function Calling与工具调用模型能操纵你定义的函数第04篇记忆机制与上下文管理实现多轮对话与外置存储第05篇规划能力与多步骤任务Agent能拆解任务并逐步执行第06篇主流框架选型与工程化组织选对框架学会合理组织代码第07篇实战自动周报Agent交付一个可用的完整作品第08篇部署上线与运维踩坑把Agent稳定跑在服务器上这样设计的原则是每个章节都产出可验证的成果。你每学完一章手里就会多一个能运行的东西信心是慢慢积累出来的。第01篇和第02篇是地基第03篇到第05篇是Agent相对通用的三大核心机制第06篇帮你在自己写和用框架之间做一个理性选择第07篇和第08篇把前面所有东西揉进一个完整项目里。1.3 适合谁读需要什么前置基础先说不适合谁一点编程基础都没有的读者建议先去补Python基础语法、变量、函数和简单的列表字典操作再来啃这套教程。已经在用某类成熟框架做过三个以上生产级Agent项目的工程师这套教程对你来说会偏基础可以挑着看第05篇之后的工程化部分。教程默认你具备三样东西第一Python基础语法能看懂函数定义和if/else第二命令行基本操作知道pip install和python xx.py是什么意思第三一点耐心因为大模型接口的行为有随机性同一个问题多跑几次结果可能不一样你得接受这种不确定性并学会应对。另外教程假设你有一个能调用大模型API的账号和少量预算。虽然很多开源模型可以本地跑但为了把精力全部放在Agent机制上而不是折腾显卡驱动和推理服务教程统一用在线API路线。等你学到了第08篇部署章节我会再讲怎么替换成本地模型方案。这样做能最大程度降低入门门槛。2. AI Agent到底是什么先建立整体认知2.1 大模型与Agent的区别大脑和使用大脑的人这个词我在教学时经常被问Agent和大模型到底是不是一回事最简单的回答是大模型是大脑Agent是会用大脑的人。你单独调用一个大模型API它只会做一件事根据你给的文本生成一段新的文本。你问它北京天气怎么样它只能凭训练时的记忆告诉你一个大概因为它没有联网能力也没有实时获取数据的手段。但如果你给它配上工具——一个查询天气的函数一个获取当前时间的函数再让它学会需要时就去调用这些函数的规则它就变成了一个能真正帮你干活的Agent。这个类比可以继续往下推。一个人要完成复杂任务光有大脑还不够还得有眼睛观察、手执行、笔记本记东西。Agent也一样模型负责理解和生成外面的代码负责感知环境、执行动作、保存状态。这也是为什么Agent开发不完全等于提示词工程——提示词只是其中一环工程代码同样重要。2.2 四大核心组件规划、记忆、工具、行动如果把一个Agent拆开来看几乎所有架构都会归结到四个核心组件第一是规划Planning。Agent需要把一个复杂目标拆解成一系列可执行的子步骤。比如用户说帮我把这周的销售数据整理成报告发到群里Agent得先想清楚要读取数据、要分析数据、要生成报告、要调用群机器人接口发出去每一步可能还要处理失败重试。规划能力决定了Agent能不能处理复杂任务而不是只会回答是或否。第二是记忆Memory。记忆分为短期和长期。短期记忆就是模型的上下文窗口也就是当前对话里能记住的内容长期记忆则需要外置存储可以是向量数据库、Redis甚至就是普通的JSON文件。比如你希望Agent记住用户的偏好——客户A喜欢简洁风格客户B需要数据表格这些信息不会出现在当前对话里必须单独存下来在需要时检索注入。没有记忆的Agent每次对话都是一次失忆的重新开始。第三是工具Tools。工具是Agent连接外部世界的通道。常见的工具包括Function Calling定义的本地函数、外部REST API、代码解释器、数据库查询接口。工具让Agent突破了只能生成文本的限制能够真正影响现实世界的东西。比如查询订单状态、发送邮件、操作文件系统这些都是靠工具完成的。第四是行动Action。行动是把规划和工具调用落地的过程。Agent根据规划选出一个动作执行它观察结果再决定下一步。行动不是单独一步而是贯穿整个循环。你在代码里看到的大多数while循环和for循环本质上都是在实现行动-观察-再行动的机制。2.3 一个Agent的完整运行循环理解了四个组件我们来串一遍完整流程。以查天气并提醒我带伞为例接收用户目标把目标放入上下文短期记忆。Agent从记忆里检索相关信息比如用户所在城市。规划模块决定需要调用get_weather工具。行动模块执行工具调用得到北京今天有雨的返回值。把观察结果放回上下文模型判断任务还没完成需要再生成一句提醒。模型生成最终回答北京今天有雨记得带伞。循环结束输出结果。这个流程在学术和工程上有一个很朴素的名字叫ReAct模式——Reasoning推理和Acting行动交替进行。你不需要把它想得多高深它就是让模型思考一步、执行一步、观察结果、再思考下一步的循环。整个系列的第05篇会专门展开讲规划策略但你现在只要记住这个循环后面学什么框架、看什么代码都会觉得非常眼熟。因为市面上所有Agent框架核心逻辑跑不出这个循环。3. 三阶段学习路径与动手规划3.1 阶段一打好模型调用与提示词基础第一阶段对应教程第01篇和第02篇目标是让模型听你的话。这里说的听话不是指语气礼貌而是指输出格式稳定、内容可控。这个阶段你要做三件事第一搭好环境成功调用一次大模型API搞清楚system、user、assistant三种角色的区别第二学会写结构清晰的提示词让模型按照JSON格式返回结果而不是满篇废话第三理解temperature、max_tokens这些参数对输出有什么影响。我见过很多人在这个阶段就翻车提示词写得含糊模型返回里夹杂着解释性文字然后程序解析JSON报错。其实解决办法很朴素——提示词里明确写只输出JSON不要任何其他内容再加上代码里对返回结果做强校验基本就能解决。阶段一的验收标准很明确给模型输入一段非结构化文本你能让它稳定输出一个字段完整的JSON对象连续测试十次不失败。达不到这个标准就不要急着进入下一阶段否则后面写Agent代码时你会发现每一步都在跟格式不对搏斗。3.2 阶段二逐个击破Agent核心机制第二阶段对应第03篇到第05篇是整套教程的核心区。这个阶段的任务是把你前面学到的东西组合成一个能自动完成任务的系统。先练Function Calling。你要理解工具的schema格式知道怎么定义参数怎么在代码里接收模型的工具调用请求并执行。练到这一步你应该能做出一个输入城市名就能返回天气的小Agent虽然它只能干这一件事但闭环已经通了。再练记忆。给Agent加上对话历史保存功能重启进程后还能记得之前聊过什么。这个阶段你会接触到messages数组的拼接、截断策略、简单向量检索。你要理解为什么不能把全部历史都塞进上下文——因为上下文窗口有限而且塞太多无关信息反而会干扰模型判断。最后练规划。给Agent一个多步骤任务让它自己拆解。你可以从给三个不同的人发不同内容的邮件这种小型任务开始观察模型会不会生成正确的工具调用序列会不会在失败后重试。这个阶段会明显感到调试复杂度上升因为问题不再是格式对不对而是流程通不通。3.3 阶段三整合项目与工程化第三阶段对应第06篇到第08篇目标是把Demo变成项目。很多人学了前面的机制后会做一个一个的小脚本但一旦要组合成完整应用就懵了——代码该放几个文件、状态怎么管理、出错怎么处理、日志怎么打全是问题。第06篇会讲框架选型。我的建议是不要一上来就用重框架先用裸代码跑通再用框架重构。这样你对框架替你做的事情有感知而不是稀里糊涂地调用了一段魔法。选型时要考虑团队熟悉度、社区活跃度、是否需要可视化编排、是否要部署到特定平台。没有绝对最好的框架只有适合你当前场景的选型。第07篇和第08篇是压轴实战做一个自动周报Agent。它会读取你这周的代码提交记录、生成业务进展摘要、调用群机器人发送消息。这个项目难度适中但覆盖了前面所有机制——模型调用、工具调用、记忆存储、规划执行、异常处理、定时调度、部署上线。做完这个项目你就有能力评估哪些日常工作能交给Agent了。4. 环境准备与第一个Agent骨架4.1 开发环境搭建清单在开始写代码之前我建议你按下面这个清单准备好环境可以省掉后面大量折腾时间Python 3.10 或更高版本建议用虚拟环境隔离项目依赖别直接装到系统解释器里一个模型API账号并创建一个Key权限最小化只保留模型调用权限python-dotenv库用.env文件管理密钥避免把Key写死在代码里VS Code或者你习惯的编辑器装上Python插件一个HTTP调试工具比如Postman或curl用来快速验证API连通性。我习惯把每个Agent项目放进独立的虚拟环境并创建.env.example文件作为模板提交到仓库真实.env加进.gitignore。这样别人拿到代码后复制一份模板填上自己的Key就能跑不会泄露密钥也不会因为依赖冲突折腾半天。4.2 模型API选型与成本规划在线API是教程的主线选哪个取决于你的具体需求我按三类场景给出建议场景更合适的模型路线原因复杂推理、长文档理解大参数商业模型准确率高指令遵循能力强高频、成本敏感的中等任务轻量级模型速度快成本低够用即可数据敏感、需本地部署开源模型私有化数据不出内网可控性强成本控制方面我建议你从第一天就养成看token数的习惯。每次调用都打印一下prompt_tokens和completion_tokens你很快会对一个任务大概消耗多少token产生直觉。不要小看这个习惯很多Agent在生产环境跑崩了不是因为代码bug而是因为忘记设单次任务的最大步数和token上限导致一次任务调用几十次模型接口账单直接爆掉。后面第08篇会细讲怎么设置预算阈值和告警。4.3 最小可运行的Agent骨架理论说了很多我们直接看一个最朴素的ReAct风格Agent骨架。这段代码不依赖任何Agent框架只用模型服务商的SDK展示Agent最本质的循环# agent_skeleton.py # 最朴素的 ReAct 风格 Agent 骨架 import json from llm_sdk import LLMClient # 替换为你实际使用的模型服务商 SDK client LLMClient(api_key你的API Key) # 工具注册表 def get_current_time() - str: from datetime import datetime return datetime.now().strftime(%Y-%m-%d %H:%M:%S) def get_weather(city: str) - str: # 实际项目中应替换为真实天气 API 调用 return f{city} 今天晴气温 22℃ TOOL_FUNCTIONS { get_current_time: get_current_time, get_weather: get_weather, } # 工具的 schema 描述模型靠它来决定何时调用、传什么参数 TOOL_SCHEMAS [ { type: function, function: { name: get_current_time, description: 获取当前日期和时间, parameters: {type: object, properties: {}}, }, }, { type: function, function: { name: get_weather, description: 查询指定城市的天气, parameters: { type: object, properties: {city: {type: string}}, required: [city], }, }, }, ] def run_agent(user_input: str, max_steps: int 5): messages [{role: user, content: user_input}] for step in range(max_steps): response client.chat.completions.create( model你的模型ID, messagesmessages, toolsTOOL_SCHEMAS, tool_choiceauto, ) msg response.choices[0].message messages.append(msg) # 模型没有请求调用工具说明它可以给出最终答案 if not msg.tool_calls: return msg.content # 执行所有工具调用并把结果放回对话上下文 for tool_call in msg.tool_calls: func TOOL_FUNCTIONS[tool_call.function.name] args json.loads(tool_call.function.arguments) result func(**args) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) return 已达到最大轮数任务未能完成。 if __name__ __main__: print(run_agent(现在几点了))这段代码结构很简单run_agent里有一个循环每次把最新的消息发给模型模型要么返回一个工具调用请求要么返回最终回答。如果请求调用工具代码就执行对应函数把结果作为tool消息追加进上下文然后进入下一轮让模型看到工具结果后继续推理。max_steps是安全阀防止Agent陷入无限循环。4.4 运行效果与调试技巧你运行这段代码输入现在几点了模型大概率会走这样一条路请求调用get_current_time工具代码执行并返回时间字符串模型读取结果生成当前时间是2025年X月X日 XX:XX:XX的回答。整个过程在终端里会打印出最终结果但你看不到中间过程。我强烈建议你在初学阶段把中间过程打出来这是调试Agent最重要的一招。具体做法很简单在for step in range(max_steps)循环里加上一行print(json.dumps(msg, ensure_asciiFalse, indent2, defaultstr))。这样你能清楚看到每一轮模型想了什么、想调用哪个工具、传了什么参数。很多诡异问题——比如模型死活不调用工具、模型调用了工具但参数是空的——有了日志一眼就能定位。另一个注意事项模型返回的tool_calls可能不止一个同一个msg里可能同时请求调用多个工具。上面的代码已经处理了这种情况逐个执行。新手容易在这里写错只处理tool_calls[0]结果任务明明需要两次工具调用却被静默丢弃了一次。这个问题排查起来很费劲因为不是每次都会触发属于典型的间歇性bug。5. 常见问题与避坑指南5.1 新手最容易踩的五个坑我把带新人过程中反复出现的五类问题整理成了一张速查表你在学习过程中撞见任何一个都能回来对照坑典型现象解决方案不设最大轮数任务卡死模型反复调用工具账单飙升始终给循环设max_steps并打印日志不校验模型输出解析JSON崩溃程序报KeyError用json.loads外层套try/except失败就重试上下文无限膨胀对话历史越塞越多成本越来越高定期裁剪只保留最近N轮或关键摘要工具参数类型错误模型传了字符串函数却需要数字在工具函数入口做类型转换和校验拿测试数据当真实结果返回天气晴就以为对接成功用真实API测试核对返回字段结构第一个坑的杀伤力最大。我见过一个同学在演示时Agent因为工具返回格式不符合预期不断重试同一个调用三分钟花了十几块钱。其实只要设置单任务预算上限比如最多执行5次工具调用就能避免这种事故。第二个坑也很常见大模型不保证100%按格式输出哪怕概率只有1%生产环境下一天几千次调用也会出事所以一定要在代码层面兜底。5.2 高效学习这套教程的操作建议结合我自己带人学习的经验给你几条实操建议照着做学习效率会高很多第一每篇教程都要动手跑代码不要只看。哪怕你把代码抄一遍再运行收获都比干看大三倍。第二给每个练习建立一个实验日志记录改了哪个参数、结果发生了什么变化。这个日志一开始看起来没什么用但当你遇到一种奇怪的随机问题时回头看日志能找到规律。第三故意改坏代码再修复。比如把max_steps改成1你会看到Agent明显变笨把工具函数返回值改成错误格式你会看到模型怎么处理异常。这种破坏性实验能让你快速理解每个环节的作用。还有一个建议找人一起学。Agent开发中很多问题都是环境相关、随机相关的一个人排查半天没思路另一个人瞄一眼日志可能就发现了。我在线下带过几期小组凡是能坚持每周同步一次进度的小组完成率都在八成以上单打独斗的一半以上会卡在第03篇前后。结对学习的价值在这个领域比很多传统编程领域更明显因为Agent的调试更需要讨论和复现。5.3 这套教程结束之后你可以走向哪里学完第08篇之后你的能力大概处在一个能独立开发并部署一个单Agent应用的水平。这个时候面前有几条路可以选。第一条是工程化深挖。把Agent接到更复杂的业务系统里做好权限控制、审计、监控、多租户隔离这部分更多是后端工程经验Agent只是其中一个模块。第二条是多Agent协作。研究多个Agent分工配合比如一个负责收集信息一个负责撰写一个负责审核处理流程长、角色多、需要相互校验的任务。第三条是垂直领域深耕。同样是Agent技术用在客服、法律文书、供应链、教育辅导每一个场景都有自己独特的数据结构和领域约束需要针对性优化。我个人比较推荐第三条路。技术上单Agent的套路你已经掌握了剩下的瓶颈其实是对某个行业业务流程的理解程度。与其追逐框架更新不如选一个你熟悉的业务场景把一个具体问题用Agent解决到极致。这种东西才是真正能产生业务价值、让你在团队里不可替代的东西。最后基于我实际带人和做项目的经历再补一句学Agent开发最大的敌人不是概念难而是完美主义。我见过太多人反复看资料、反复比较框架就是不动手。你真正需要做的是先把今天那段骨架代码跑起来然后把它改成一个能查天气的小工具再让它去做一件你日常工作里重复了三遍以上的事。每一次把模型生成文本变成模型驱动行动你都会对Agent多一层直觉。这套教程的每一篇都是冲着这个目标去的。路线已经给你画好了剩下的就是动手了。