最近几个月越来越多朋友问我同一个问题AI Agent到底是个什么东西为什么感觉全世界都在聊但翻来覆去看教程也抓不住重点说实话这个领域确实很特别——它不像学一个框架那样有明确语法也不像学算法那样有标准答案它更像是把大模型、工具调用、任务规划、记忆管理这些东西串起来的一整套工程方法。我也是踩了不少坑才慢慢把这条路趟明白。这篇入门手册我尽量用做工程的人能听懂的语言把AI Agent从概念到落地掰开揉碎讲清楚。内容覆盖四个部分先搞懂Agent的本质和它会用到的基本概念Token、记忆、工具然后梳理当前主流的架构和框架选型接着用一份可以直接抄的代码从一个能跑的最小Agent开始一步步做到把它部署成Web服务。最后是学习路线和排坑清单这部分是我最想让你认真看的因为很多问题只有真正跑起来才会遇到。适合谁来读零基础但想快速建立认知的新手写过几年代码但还没碰过Agent的后端开发者以及已经在玩Prompt、想更进一步做自动化决策产品的技术同学。我不堆概念不贴大话尽量让你读完就能动手。1. 先搞清楚到底什么才算AI Agent1.1 Agent不是ChatGPT的换皮很多人第一次接触Agent会下意识觉得“这不就是ChatGPT加了个系统提示词吗”。这个理解不能说全错但它忽略了一个关键的东西Agent有自主行动能力。传统Chatbot的工作方式是人问一句、模型答一句模型本身不会主动去查资料、不会去调接口、也不会因为任务没完成而继续追问。Agent则不一样它被设计成一个“能独立完成目标”的智能体。你可以把大语言模型理解成它的大脑但除了大脑之外它还有眼睛读取外部信息、手调用工具和记忆力保存上下文。模型负责思考外部工具负责执行这两者通过一套循环机制串起来才构成了真正的Agent。我用个生活化类比你请了个客服他只会背话术你问什么他答什么这叫Chatbot。你请了个店长他会自己看库存、安排进货、回复顾客、处理售后完不成任务还知道换方案这才叫Agent。所以判断一个系统是不是Agent我一般看三个特征它有没有一个自主的”目标拆解-行动-反馈“循环而不是一次问答就结束它有没有外部工具或信息源而不只是凭模型内部的知识硬答它有没有记忆能力能记住本次任务的经过并参考历史经验调整策略。这三个特征是后续理解所有框架、架构和工程实践的底层线索。1.2 Token、上下文窗口与Agent的“记忆”热搜词里有个问题很典型AI Agent中的Token是什么意思。其实Token不是Agent特有的概念它是大模型处理文本的基本单位。简单理解Token就是一段文字被模型分词后的最小片段。英文里一个词可能被拆成一两个Token中文里一个字通常对应一到两个Token不同模型的分词器差别还挺大。Token和Agent的关系主要体现在两个地方第一Token决定了成本。你每次调用大模型接口本质上是在按消耗的Token数量付费。Agent的特点是它会在一次任务中多次调用模型思考一次、观察一次、再思考一次每轮都要消耗Token。所以Agent项目的Token消耗通常是普通对话的几倍甚至几十倍成本失控是新手最容易栽的坑。第二Token的窗口决定了模型的“工作记忆”。每个模型都有一个上下文窗口你可以把它想象成桌子的面积——桌子上能摊开的文件越多模型能同时参考的信息就越多。但Agent干活的时候历史记录、工具返回的结果、系统提示、当前用户问题全都要堆在这张桌子上。桌子太小早期的内容就会被“挤下桌”模型就“失忆”了。那Agent是怎么解决这个问题的答案是分层记忆。短期记忆用对话历史控制在窗口范围内长期记忆则把重要信息抽取出来存进向量数据库比如按语义检索的Embedding库等需要时再找回对话里。这个机制在工程上非常重要很多号称“记忆增强”的Agent产品本质就是在管理这一层外部存储。2. AI Agent的主流架构与技术栈2.1 三种主流的Agent工作模式我讲Agent架构之前先说个前提现在市面上的Agent框架虽然多但底层跑的逻辑其实就那么几种。你先把这几种模式看熟再去看任何框架都会觉得自己是在“用不同的语法写同一套思想”。第一种是ReAct模式这也是最容易理解和实现的一种。它的名字来自Reasoning Acting核心循环是模型先思考当前应该做什么Reason然后执行一个动作Act得到结果后再观察Observe然后继续思考下一步。好比一个人迷路了他先看地图判断方向思考然后往前走一段行动再抬头看路标观察再判断下个路口怎么走再思考。这套模式适合大多数需要多步骤处理的真实任务最大的优点是灵活、容易调试缺点是Token消耗大、容易绕弯路。第二种是Plan-and-Execute模式。它的特点是先把大任务拆成一系列步骤生成一份完整的行动计划然后按步骤执行执行完再根据结果调整计划。它更接近“项目经理”的工作方式。好处是对于结构清晰的任务比如“帮我做个数据分析报告”它不太会跑偏Token消耗也更低坏处是灵活性弱遇到计划外的情况反应慢而且一开始的计划如果拆得不好后面全盘皆输。第三种是多Agent协作模式。由多个角色Agent组成团队比如一个写代码的Agent、一个负责测试的Agent、一个负责把关的Agent它们通过消息传递协同完成复杂任务。MetaGPT这类框架就是走了这个路子。这种模式适合大型复杂项目但工程复杂度成倍上升新手前期建议看看思路就好别一上来就搞一整套。2.2 主流框架盘点新手该怎么选主流框架我分成两派一派是“灵活原语派”以LangGraph为代表另一派是“开箱即用派”以CrewAI、AutoGen为代表。另外还有走代码生成路线的MetaGPT这类角色扮演派。下面这张表我整理了一个简单对比框架核心设计思路适合场景上手难度备注LangChain / LangGraph以链和图为原语手工编排控制流需要精细控制流程、自定义状态管理中高灵活但概念多学习曲线陡CrewAI用多个角色Agent协作完成任务快速搭建小组式协作Agent低简单直观适合做原型验证AutoGen以对话为核心的Agent互聊需要Agent之间对话协商的场景中Microsoft出品学术圈用得多MetaGPT模拟软件公司流程多Agent产出文档模拟项目流程、生成复杂方案中高更偏研究探索型新手我的建议很直接如果你只是为了理解原理选LangGraph因为它的图模型能逼你想清楚每一段流程如果你想快速实现一个能交付的小工具CrewAI最省心如果你对“Agent会自行开发软件”这种研究方向感兴趣从MetaGPT和相关的论文入手更合适。但不管选哪个框架我强烈建议你先自己手写一个最小ReAct循环再碰框架。原因后面实操章节会说框架把你应该理解的细节全封装掉了你直接用出了问题根本定位不到根因。2.3 为什么有人用Rust写Agent热搜词里有条“基于Rust语言AI Agent”我也聊两句给感兴趣的人指个方向。Rust在Agent场景里的优势很突出第一是性能Rust跑LLM推理调度和工具调用的开销比Python低得多做高并发Agent网关的时候优势明显第二是内存安全多Agent并发跑的时候不容易内存泄漏第三是部署便利Rust编译出来是单个二进制文件放到服务器上就能跑不用像Python项目那样装一整套虚拟环境和依赖。但目前Agent生态大部分还是Python的天下成熟框架、工具库、示例代码几乎全是Python写的。所以我的建议是理解原理用Python想要极致性能和可控部署再考虑Rust。Rust更适合做Agent的运行时内核、网关层和工具调度层不太适合刚入门时用来学概念。等你能把LangGraph跑明白、理解了Agent的生命周期管理再去看Rust生态比如已经有不少用Rust实现Agent原语的开源项目会顺畅很多。3. 自己动手从零搭一个能跑的最小Agent3.1 选型与环境准备理论和框架聊再多不动手都是白搭。这一节我就带大家搭一个能实际运行的最小Agent。它具备两个能力能算数学题、能查天气。看起来简单但覆盖了Agent最核心的机制——模型思考、调用工具、处理返回值、继续决策。模型接入上我建议你用国内可以直接调用的API比如阿里云百炼平台上的通义千问系列、智谱的GLM系列、DeepSeek等。这些服务都提供了OpenAI兼容的接口调用方式基本一模一样你只要把base_url和api_key换掉同一个请求就能切换服务商。我不想绕到环境配置的话题上去反正一句要点确保你能拿到API Key并把网络到接口这家事确认好。环境方面我假设你用的是Python 3.10以上推荐用uv或venv建虚拟环境先装好openai这个包它已经是事实上的HTTP客户端标准python -m venv .venv source .venv/bin/activate pip install openai python-dotenv然后建一个.env文件把密钥放进去不要提交到Git。这是一个我反复提醒自己、也提醒朋友的基本习惯。提示国内模型服务的API Key在开通后通常有免费额度做实验足够了。另外务必注意按量付费的模型不要开过高额度后面成本控制部分详说。3.2 项目结构与核心代码我习惯把Agent项目拆成四个文件tools.py放外部工具agent.py放循环逻辑main.py是入口.env存密钥。下面这段代码就是一套极简的ReAct实现为了演示我把工具调用设计成模型返回JSON字符串然后由代码解析执行# tools.py import json, requests def calculate(expr: str) - str: 计算数学表达式。安全起见我只允许数字和-*/.%() allow set(0123456789-*/.%() ) if any(c not in allow for c in expr): return Error: 非法字符 try: return str(eval(expr)) except Exception as e: return fError: {e} def get_weather(city: str) - str: 查询城市天气这里用免费接口演示 try: resp requests.get( fhttps://wttr.in/{city}, params{format: 3}, timeout5 ) return resp.text except Exception as e: return fError: {e} TOOLS { calculate: { description: 计算数学表达式参数expression为字符串形式的算式, function: calculate }, get_weather: { description: 查询某个城市的当前天气参数city为城市名, function: get_weather } }下面是agent.py。核心是维护一个messages列表把每一步的思考和工具结果都追加进去再交给模型继续生成直到模型给出最终答案# agent.py import json from openai import OpenAI from tools import TOOLS client OpenAI( api_keyyour-api-key, # 实际使用从.env读取 base_urlhttps://api.example.com/v1 # 换成你选的模型服务商地址 ) SYSTEM_PROMPT 你是一个能调用工具完成任务的AI助手。 当用户的问题需要工具时你必须只输出如下JSON {thought: 你的思考, tool: 工具名, params: {参数名: 参数值}} 否则请直接输出最终答案文本。 def run_agent(user_input: str, max_steps: int 5) - str: messages [{role: system, content: SYSTEM_PROMPT}] messages.append({role: user, content: user_input}) for step in range(max_steps): resp client.chat.completions.create( modelqwen-plus, # 换成你选用的模型 messagesmessages, temperature0.3 ) content resp.choices[0].message.content.strip() try: parsed json.loads(content) except json.JSONDecodeError: return content if tool in parsed and parsed[tool] in TOOLS: tool TOOLS[parsed[tool]] print(f[Step {step1}] 调用工具: {parsed[tool]}, 参数: {parsed[params]}) result tool[function](**parsed[params]) messages.append({role: assistant, content: json.dumps(parsed, ensure_asciiFalse)}) messages.append({role: user, content: f工具返回结果{result}}) else: return parsed.get(answer, content) return 达到最大迭代步数任务可能未能完成。main.py就简单了读用户输入调用run_agent打印结果。跑一次“北京天气怎么样”你会看到Agent先思考、再调用get_weather、最后根据返回结果组织答案的完整流程。这段代码不是我刻意写简单而是想让你看清楚Agent的本质它不过是一个循环——调模型、判定是否需要工具、执行工具、把结果喂回去。你理解了这四步后面看LangGraph的StateGraph会发现它只是把这种循环抽象成节点和边而已。3.3 把Agent接到Web服务上FastAPI/Django的玩法本地能跑通只是第一步。真实项目里Agent很少直接暴露成命令行多半要包一层HTTP接口供前端或自动化流程调用。这个环节我推荐用FastAPI它自带异步支持和OpenAI的异步接口配合起来很顺手。如果“用AI Agent开发Django”这类热词点到了你的需求我也多说一句Django和FastAPI并不是二选一的对立关系。Django适合整个业务系统、用户体系、后台管理都在同一个项目里的场景FastAPI适合纯粹做Agent服务网关。我个人实践下来Agent服务本身用FastAPI写外层业务系统用Django跑两边通过HTTP通信是最清爽的架构。下面给一个FastAPI封装的例子# server.py from fastapi import FastAPI from pydantic import BaseModel from agent import run_agent app FastAPI() class Query(BaseModel): input: str app.post(/agent) def agent_endpoint(q: Query): answer run_agent(q.input) return {answer: answer}这样你的Agent就有了一个Web入口。部署的时候用uvicorn跑前面再加一层反向代理比如Nginx就能对外提供服务了。要提一句流式输出如果Agent任务耗时长用户在前端会一直干等。这时候建议用SSE或者WebSocket把模型返回的内容边生成边推给前端。FastAPI配合StreamingResponse就能实现体验会好很多。3.4 一个能落地的场景自动消息处理工作流很多人问“能不能用Agent让小红书自动发消息”——这种自动化的需求很常见但我必须先把丑话说在前面任何平台都有它的规则和风控机制做自动化脚本之前一定要仔细阅读平台的服务条款合规合法地使用接口。我下面给的案例重点是消息处理工作流本身你可以把它应用到自己的系统、自己的账号但不要拿去钻平台规则的漏洞。场景假设是你自己的小业务后台客户通过表单提交了一个咨询Agent收到消息后先判断意图是询价、售后还是闲聊然后调用内部接口查订单状态或库存最后生成一段带人情味的回复再由发送模块发给客户。消息来源可以是邮件、站内信或Webhook这套逻辑是通用的。工作流拆解如下接收消息Webhook收到JSON意图识别用LLM判断类别并决定是否需要调用工具工具调用查订单、查库存、催单等生成回复LLM根据工具结果客户问题组织话术人审兜底对高风险回复退款、投诉类先进入人工确认队列。这个流程里Agent不是替代人而是先把90%的重复性工作消化掉只把需要经验判断的少量case推给真人。这也是我现在做Agent项目的核心心法别想着全自动要做成“能自动的都自动重要节点留人审”。4. 踩坑实录新手必看的排查清单4.1 工具调用为什么总是失败我见过最多的问题不是模型不能思考而是工具调用老出错。表现千奇百怪根因基本就几个。第一是JSON格式飘了。模型返回的内容不是合法JSON而是夹杂着解释性文字。解决方案有两个一个是像我前面示例代码那样用正则或者宽松解析做容错另一个是在系统提示词里给出强约束并配一个“格式不合格就重试”的fallback。第二是参数名不匹配。你定义了expression模型传成了expr执行时TypeError整个Agent中断。这类问题我建议你在工具定义旁边放一份JSON Schema并在系统提示词中明确“参数名必须严格一致”同时给LLM一个工具描述的schema样例。第三是Multi-tool-call支持不足。现在的模型其实已经支持一次返回多个工具调用但入门Agent往往忽略了处理。如果遇到“明明工具执行了但模型还是瞎编答案”的情况很可能是多个调用结果没有正确传回模型导致模型缺失关键信息。4.2 Token爆炸与成本失控再提醒一次Agent是Token消耗大户。原因很简单它会在一次任务里循环多次每一次循环都重新发送整个历史记录。对话越长每轮发送的Token越多形成一种类似“滚雪球”的效应。控制成本我从两个层面做第一限制每次循环的历史轮数。只保留最近N轮消息早一些的总结成摘要放回上下文。这个叫滑动窗口摘要压缩虽然会损失部分细节但成本控制效果立竿见影。第二限制工具返回体量。工具返回结果不要原封不动丢给模型能截断的截断能摘要的摘要。比如查询数据库返回2000行你是想丢给模型全看吗显然不是。可以先用SQL聚合好或者只返回Top 5结果并附一句统计说明。还有一个小技巧同一个Agent任务里先用便宜的模型跑意图识别再用强模型跑复杂推理成本能优化30%-50%。这就好比小问题找实习生、大问题才找资深专家别浪费资源。4.3 Agent陷入死循环“Agent不停重复同一个动作就是不结束”是我调试时最容易崩溃的问题之一。典型的死循环长这样模型判断需要调用工具A得到结果后又判断需要调用工具A再拿到了同一个结果然后继续要求调用A……死循环。我处理这个问题的办法有三个一是设置硬性的最大迭代次数。就像前面代码里的max_steps没有上限的话Token和费用都会失控。这应该是Agent的必备兜底。二是对工具执行结果做“结果指纹”。如果新一次的工具调用参数和上一次完全一样返回值也一样说明Agent在原地打转这时候主动跳出循环强制要求模型改变策略或直接给用户最终答复。三是反馈里带上“上一次已尝试过什么”。把“你已经试过XX方法但失败了”写进上下文中能显著降低模型重复尝试的低效行为。这本质上是给模型更多决策信息减少盲目试错。4.4 上下文污染与幻觉上下文污染是指无用的、误导性的信息混进了Agent的消息列表。问题在于模型是无差别地依据上下文进行推理的一旦上下文里混入“某个工具返回了一串HTML代码”或者“上一次失败的报错信息”它就可能被带偏把报错当成用户需求来回答——我见过Agent把工具返回的404页面内容当作结算成功事件记录下来的真实案例。解决办法还是老三条系统提示词里明确“只有调用工具的结果才判断为事实其余推测必须标注”在把工具结果放回上下文前做清洗和格式化历史消息中过期的系统状态要及时移除或标记为“已不适用”。幻觉更常见。模型如果没拿到工具的真实返回它就会“脑补”一个结果比如虚构一个订单状态。行为上Agent就开始一本正经地编造数据了。对策就一条对Agent的最终回答做“事实校验”凡是涉及状态、数字、查询结果的句子必须对应到工具返回值中的证据片段。这在工程上叫“引用溯源”实现起来不算难却是提升Agent可信度的关键一步。4.5 常见问题速查表我把上面这些整理成一张速查表你遇到问题可以直接对照排查症状常见原因排查思路工具调用后Agent又重复调用同一工具返回结果被截断/未传回模型检查工具返回是否被完整写入messages模型假装调用了工具但没真正执行没有执行工具直接输出tool_call在循环中必须拦截tool_call并执行Agent回答和工具结果不一致上下文被污染或幻觉检查是否误放入了无关的历史信息成本突然飙升循环历史无限增长加滑动窗口限制历史轮数任务执行到一半就停了达到max_steps提高上限或优化提示词减少绕路不同时间跑同一任务结果差异大模型温度过高或Prompt不稳定调低temperature尽量用结构化输出5. 一份可以直接抄的AI Agent学习路线5.1 第一阶段先学会用不急着写框架我见过太多人上来就啃LangGraph源码结果一周后放弃了。我的建议是反着来先用现成的产品形态理解Agent的输入输出是什么样的。你可以去用几款主流的Agent产品比如一些开源的ChatGPT套壳里加了工具调用能力的项目或者各类“AI工作流”产品先感受一下Agent和普通对话的区别。同时把Prompt Engineering基础补上结构化输出、上下文组织、system/user/assistant的消息角色这些是后面所有复杂度的基石。这个阶段的目标不是学会某工具而是建立直觉什么任务适合Agent做什么任务直接写代码反而是更好的选择。判断标准很简单任务有没有一个可拆解的目标、需不需要根据中间结果做下一步决策。如果有值得做Agent如果只是固定流程那用传统代码更靠谱别为了AI而AI。5.2 第二阶段手写一遍ReAct循环等你有了基本认知就可以把这个开头我自己写的最简Agent完完整整实现一遍不依赖任何框架就用原生OpenAI SDK。做完你会获得一个特别重要的心法所谓Agent框架核心结构就是“模型调用 条件跳转 状态管理”剩下的全是工程化优化。手写的好处是你调试时能完全掌控变量坏处是工程细节都要自己补——但这就是你该练的。这个阶段要重点吃透的四个点工具调用Tool Calling协议、消息历史的构建方式、异常时的容错重试、以及上下文裁剪策略。这四个点覆盖了“Agent做得像样”的全部底层能力。5.3 第三阶段读一个开源框架的源码当你用原生SDK写出了自己的小Agent再回头去看LangGraph或CrewAI你会发现自己不再是“看不懂源码”而是“原来它用状态图把我的循环包装起来了”。我推荐的阅读路径是先看官方示例中涉及工具调用的部分再看它State状态的流转设计最后看节点node和边edge的抽象方式。不要一开始就看源码内部所有细节那样必迷失。拿到一个开源框架你先要搞清楚它解决的是哪几个工程问题额外引入了哪些机制然后结合自己写的小Agent去对照效率极高。读完源码再去用它就变成了“带着你的问题去选型”而不是“学不会就骂框架”。5.4 第四阶段结合业务做垂直Agent最后一个阶段才是接真实业务。AI Agent的火爆不代表它是一个万能银弹事实上我做了这么多Agent项目后一个强烈的体会是Agent项目的复杂度往往不在Agent本身而在外部的业务集成。比如你要做一个自动售后Agent你得和订单系统、物流系统、库存系统对接要做内容审核辅助Agent你得处理内容安全接口、风险条款。这些集成工作占了项目80%的工作量。所以做垂直Agent时建议先花大量时间梳理流程和异常分支——哪些环节可以交给LLM决策哪些必须硬编码兜底哪些要有人工介入。持续迭代脏活累活的过程才是Agent工程师真正的分水岭。阿里云、各家大厂都发布过一些AI Agent白皮书和最佳实践文档里面对于企业级Agent的分层架构、RAG选型、评测体系写得比较系统到这个阶段再去读收获会比一开始囫囵吞枣大得多。我在实际操作中发现最终决定一个Agent项目能不能稳定交付的反而不是大模型选得有多新而是你对它的限制边界划得有多清楚。模型的推理能力会越来越强但边界设计和工具链建设永远是你作为工程师的立身之本。想清楚这个再去看层出不穷的新框架、新热词就不会慌。
