AI Agent入门：从最小Agent搭建到Token成本控制与Django落地

开头

每次有新人来问我"AI Agent到底该怎么入门"，我都能从问题里嗅出一种共同的焦虑：他们翻了几篇文章，看到"智能体""自主决策""多Agent协作"这些词，感觉既高大上又完全无从下手。有人甚至以为AI Agent就是给ChatGPT加个联网搜索的插件，或者是个必须买昂贵平台账号才能用的黑盒。这些理解不能说全错，但都离真相差了很远。

我自己的经历是从一个个失败的"玩具项目"里爬出来的。最开始我连Agent和普通函数调用的区别都讲不清，做出来的东西要么是套了个循环的聊天机器人，要么是逻辑死板得连天气都查不利索的脚本。直到某次我把一个真正带"感知-决策-行动"闭环的小工具跑通，才第一次有了"它在替我干活"的感觉。这篇入门手册，就是想把这段从懵到通的路程压缩成一篇能直接照着走的地图。

内容会覆盖这几个维度：AI Agent的定义和误区、主流架构与选型、一个最小Agent的完整搭建过程、Token到底怎么算怎么省，以及一条按周排的学习路线和几个能落地的方向。无论你是准备用Python做后端集成，还是好奇Rust能不能写Agent，或者想用Agent接Django做个小业务，这篇都能给你一个不绕远路的起点。

1. 别把Agent想得太玄：先建立正确的最小心智模型

1.1 从"问答机器"到"干活的人"，到底变了什么

如果你用过ChatGPT这类大模型，你的体验大概率是：提一个问题，得到一个答案。这个过程再流畅，本质上也只是一次"问答"。AI Agent的核心变化，是把"问答"升级成了"干活"。

用一个我常打的比方：传统大模型像一个记忆力超强的图书管理员，你问他"某本书里写了什么"，他翻箱倒柜给你找出来背出来。但你如果说"帮我把办公室下周的会议全部安排好，顺便给每个参会人发提醒邮件"，他只会愣住——因为这事不是靠查资料就能解决的，需要拆解任务、调用日历工具、写邮件草稿、确认发送结果、处理失败重试。AI Agent就是那个被赋予"手"和"脚"的图书管理员：他拿到目标后，会自己规划出步骤，一步步执行，每执行一步看一眼结果对不对，不对就调整，直到任务完成。

所以判断一个程序算不算Agent，最简单的标准不是看它有没有用大模型，而是看它有没有形成闭环：目标 -> 规划 -> 调用工具 -> 观察结果 -> 修正 -> 完成。有闭环的才叫Agent，没有闭环的，即使套了个华丽的外壳，也只是个花哨的脚本。

1.2 四大核心组件：大脑、手脚、记忆、规划器

市面上所有的Agent框架，拆开来看，都逃不过这四个组件：

• 大模型（大脑）：负责理解意图、做推理决策、生成行动指令。它是整个Agent的智能来源。
• 工具（手脚）：让Agent能影响外部世界的东西。可以是API调用、数据库查询、代码执行器、浏览器操作，甚至是另一个Agent。
• 记忆（经验）：短期记忆负责当前任务里的上下文，长期记忆负责跨会话保留用户偏好和历史事实。记忆决定了Agent是不是"每次都像第一次见面"。
• 任务规划与执行循环（驱动器）：把上面三样串起来的那层胶水。它决定Agent先做哪一步、后做哪一步、什么时候该停下。

我在看很多初学者的代码时发现，最容易缺的是第四个组件。大家很自然地把模型API接上、给了几个工具函数，然后就等着模型自己"悟出"该干什么。结果模型经常乱用工具或者一直绕圈。实际上，规划与执行循环才是Agent的灵魂，它需要你去显式地设计：最大步数是多少、每步要不要记录中间结果、出现错误时怎么恢复。

1.3 一个装在任何框架脑中的统一循环

不管你是看LangChain文档、阿里云AI Agent白皮书，还是某个Rust写的开源Agent引擎，底层都是同一个循环在运行，只是被包装得越来越复杂：

目标明确 --> 模型生成"下一步行动" --> 解析行动 --> 如果是"结束"就退出，否则调用工具 --> 把工具返回追加到上下文 --> 回到第一步

这个循环也解释了一个很常见的困惑：为什么Agent会越跑越贵？因为每一步工具返回结果都要作为新的输入再发给大模型一遍，上下文越滚越长，计算量是逐轮累积的。后面我会专门讲Token这笔账，这里先记住一个结论：Agent的成本不是单次问答的N倍，而是每一轮循环都要为历史上下文付费。

2. 主流架构与选型：从ReAct到多Agent协作，别一上来就上重武器

2.1 单Agent的经典架构：ReAct与Plan-and-Execute

目前业界最主流的单Agent工作流，归纳起来就两类。

第一类是ReAct（Reasoning + Acting），核心思想是让模型在每一轮里交替输出"推理过程"和"行动指令"。你把前一轮工具的结果拼回去，让模型看到"做完这件事后发生了什么"，再决定下一步做什么。这种架构的优点是灵活、能应付中途变化，缺点是token消耗大、模型可能要绕很多圈才找到正确答案。

第二类是Plan-and-Execute（先规划再执行）。它会先让模型一次性生成一份完整计划，然后按计划逐步执行，每一步只做"当前步骤+检查结果"，而不是每一步都重新思考全局。它像一个先画好施工图再动工的建筑队，好处是稳定、可控、token相对省，坏处是计划一旦错了，中途调整很麻烦。实际项目里，我一般这样选：任务不确定、变化多的（比如"帮我研究这个行业的竞争对手"）用ReAct；任务流程明确、步骤固定的（比如"每天定时抓取数据并生成日报"）用Plan-and-Execute。

2.2 多Agent模式：什么时候需要一堆Agent一起干活

很多入门文章会把多Agent吹得神乎其神，仿佛一个Agent不够用，得上十个。我的经验恰恰相反：在你连一个Agent都跑不稳之前，多Agent只会放大地狱难度。但理解几种编排模式还是必要的，因为总会有任务大到单Agent搞不定。

• 主从模式（Supervisor）：一个"老板Agent"负责拆解任务，把子任务派发给若干"专员Agent"，再回收结果汇总。适合目标单一但专业领域复杂的场景，比如做一个"市场调研报告生成器"，调研Agent、数据分析Agent、文案Agent各自分工。
• 流水线模式（Pipeline）：A的输出正好是B的输入。适合处理流程高度固定的任务，比如"翻译-校对-润色"三步流水线。
• 协作/网状模式（Collaborative）：多个Agent可以互相对话、争论、投票。这种最灵活也最不可控，现阶段我基本只在实验项目里用。

给入门者的建议：先老老实实做单Agent，把它做到稳定、可观测、成本可控，再考虑引入二三个角色的主从模式。方案不是越高级越好，而是越匹配任务越好。

2.3 基于Rust和基于Python/JS，到底差在哪

搜索热点里经常出现"基于Rust语言的AI Agent"，这个方向确实存在，但很多人对它的期待是错位的。我也接触过几个Rust写的Agent框架，客观评价一下差异：

Python系（LangChain、LlamaIndex、AutoGen等）生态最丰富，文档、教程、现成工具一抓一大把，适合快速验证想法，我建议99%的入门者从Python开始。JS/TypeScript系（LangChain.js、Vercel AI SDK）在Web集成上有天然优势，如果你要把Agent塞进浏览器页面或Node服务里，选它没错。Rust系（比如rig、swift-rs这类crate）主打的是极致性能和低资源占用，适合做高并发的Agent服务、Agent基础设施，但目前生态还在早期，很多工具链要自己造。

打个比方：Python系像便利店，什么都有，走进去就能买到东西；JS系像社区超市，贴近你家（浏览器和前端生态）；Rust系像专业建材市场，东西精但少，你得会自己组装。如果你不是对性能有极端需求，没必要一上来就挑战Rust。真有那个执念，可以先用Python把业务逻辑想清楚，再用Rust重写Agent的调度核心。

3. 从零搭一个最小可用Agent：不靠框架也能跑通闭环

3.1 别急着装框架，先用手搓一个循环

很多人一听说Agent就直奔LangChain，装了一堆依赖，结果连"模型该怎么被调用"都没搞明白。我强烈建议你在接触任何框架之前，先手写一个只有几十行的最小Agent。这几十行代码会像肌肉记忆一样印在你脑子里，以后不管换什么框架，你都能看懂它到底帮你做了哪些事。

我给的方案只需要三样东西：一个大模型API（任何兼容OpenAI接口的都行）、两个工具函数、一个循环。

3.2 一段能跑的Mini Agent代码示例

假设我们要做一个"房屋信息查询Agent"。用户说"我想在海淀区找一间80平以上、月租低于8000的房"，Agent需要决定是直接回答，还是调用搜索工具。

import json from openai import OpenAI client = OpenAI() # 换成你的模型服务地址和密钥 # 工具1：查询房源 def search_house(district, max_price, min_area): """模拟房源数据库查询""" fake_data = [ {"district": "海淀", "area": 85, "price": 7500, "name": "海淀黄庄小区"}, {"district": "朝阳", "area": 90, "price": 9000, "name": "望京西园"}, {"district": "海淀", "area": 78, "price": 7200, "name": "知春里小区"}, ] result = [h for h in fake_data if h["district"] == district and h["area"] >= min_area and h["price"] <= max_price] return json.dumps(result, ensure_ascii=False) TOOLS = [ { "type": "function", "function": { "name": "search_house", "description": "搜索符合条件的房源列表。district为行政区名，max_price为最高月租，min_area为最小面积。", "parameters": { "type": "object", "properties": { "district": {"type": "string", "description": "行政区，如海淀"}, "max_price": {"type": "integer", "description": "最高月租"}, "min_area": {"type": "integer", "description": "最小面积（平方米）"} }, "required": ["district", "max_price", "min_area"] } } } ] def run_agent(user_message): messages = [{"role": "user", "content": user_message}] max_steps = 5 for _ in range(max_steps): resp = client.chat.completions.create( model="gpt-4o-mini", messages=messages, tools=TOOLS, tool_choice="auto", ) msg = resp.choices[0].message messages.append(msg) # 保存模型的思考或行动指令 if msg.tool_calls: # 模型想调用工具 for call in msg.tool_calls: args = json.loads(call.function.arguments) if call.function.name == "search_house": result = search_house(**args) messages.append({ "role": "tool", "tool_call_id": call.id, "content": result, }) else: # 模型已经给出最终回答 return msg.content return "已达最大执行步数，任务未完成。" print(run_agent("我想在海淀找80平以上、月租低于8000的房子"))

这段代码的运行逻辑很简单：模型收到用户问题后，发现靠自己的知识无法精确查询房源，于是输出一个结构化指令调用search_house；工具返回JSON后，模型再根据结果生成自然语言回答。整个过程只有两步工具调用，但已经是一个完整的最小闭环。

如果你用的不是OpenAI官方服务，只要是兼容协议的端点，把model和base_url替换即可。Rust那边的思路也一样，只是把chat.completions.create换成对应的HTTP调用。

3.3 工具定义要像产品说明书，而不是名词列表

我在实战中发现一个非常容易被忽略的细节：工具调用的成败，很大程度取决于Function的定义质量，尤其description领域的措辞。模型是通过描述来理解"你这个工具是干嘛的、什么时候该用"的。

举个例子。新手可能会这样写："description": "查询房源"。模型拿到这个描述，只能猜大概。更好的写法是："description": "根据行政区、面积、价格条件搜索房源列表，常用于需要获取实时房源数据时；只能在用户明确提到区名时使用"。这么写，模型才知道在什么场景下调用、参数怎么填。这就是为什么很多看着功能很全的Agent却老抽风——工具函数本身没错，但"说明书"写得太烂了。

所以请把你的工具当成要给外包团队做的接口文档来对待：每个参数的类型、边界、示例值都写清楚。能多具体就多具体。

3.4 跑起来之后，第一件事是加日志

你把这个Agent跑通之后，第二步一定不要急着加功能，而是在循环里打印每一轮的原始输出，包括模型回复的内容、工具返回的内容。你会看到模型有时会自说自话，有时会分析半天才决定调用工具，这些信息是你后面做优化最重要的一手资料。

我习惯给每一轮决策打印一个结构化的JSON日志，类似：

step=1 | thought="用户提到了海淀，需要调用搜索工具" | action="search_house(district=海淀, ...)" | observation="[...]"

有了这一步，你才能回答那些最要命的问题："为什么它绕了四圈才拿到答案？""为什么它一直重复调用同一个工具？"没有日志的Agent项目，就像没有仪表盘的飞机，飞得再高也是碰运气。

4. Token是什么、怎么算、如何控成本：Agent开发绕不开的账

4.1 为什么Agent的Token消耗会呈指数级上升

先解答热搜词"ai agent token是什么意思"。Token是大模型处理文本的最小计量单位，可以粗略理解为"一段文本被切成的碎片数"。一个中文汉字通常对应1到2个Token，一个英文单词大约对应1.3个Token。大模型按Token计费，就好比你按字数给编辑排版付费：字数越多，钱越多。

普通聊天场景，一次问一句、答一句，Token消耗是可以预估的。但Agent的循环机制让它非常"烧钱"。每一轮模型决策，都要把用户原始问题 + 前几轮的思考历史 + 工具返回的长文本全部再发一遍。假设一轮对话需要3000 Token，循环5轮就是15000 Token，而不是很多人直觉以为的"5倍单轮"——因为每一轮的输入都在涨，工具返回的结果可能几百字节，模型生成的推理过程可能又几百字节，累积起来非常可观。

我维护的一个内部Agent曾出现过单次任务消耗40万Token的极端案例。原因是一条工具接口意外返回了完整的日志文件，Agent把整份日志作为上下文反复咀嚼，等于你雇了个每小时收费的助理，让他完整背诵一份几百页的流水账。

4.2 成本公式与优化三板斧

先看成本估算公式：

单次任务成本 ≈ 平均每轮Token数 × 循环轮数 × Token单价

你不需要算得很精确，只需要有一个"量级感"。压成本也无非是压这三个乘数：

第一，压平均每轮Token数。把工具返回结果精简到最小——只返回字段摘要和必要数据，不要整坨原始数据；历史消息只保留最近的几轮，超过就丢掉；对长历史做LLM摘要，把过去十轮的完整对话压成三行摘要存下来。

第二，压循环轮数。给Agent设置max_steps，别让它无限绕圈。我见过的最常见烧钱行为就是Agent在错误的工具上来回横跳，是因为工具的边界定义不清楚，它试了又试。能从源头把工具描述写清楚，比任何省钱技巧都管用。

第三，分级使用模型。不是所有环节都要上最强模型。工具参数抽取、简单格式化这类活儿，用小模型处理又快又便宜；真正需要复杂推理和总结收尾的地方，才让大模型上。这种"快慢模型搭配"的架构，在真实系统里能省下很大一笔成本。

4.3 缓存与批处理：被很多人忽略的省钱大招

实际开发中，两个场景经常被忽略：一个是用户反复问同类问题，一个是Agent内部的重复子流程。如果同样一个工具调用，输入参数完全一致，工具返回的结果大概率也一样。这种结果可以直接缓存，命中缓存就不需要再交给模型处理一次。

另一个是批处理思维。如果你的Agent服务用在非实时场景（比如夜里生成报表），完全可以把任务排成队列批量跑，利用低峰期资源，而不是让每个用户请求都实时触发一次昂贵的Agent循环。这块跟部署架构强相关，我放在后面Django那一节接着说。

5. 入门路线与落地部署：从Demo到真实业务之间还有几道坎

5.1 一份按周排的学习路线，照着走就行

我在回答"ai agent学习路线"时，给过很多版本，最终沉淀下来的是下面这份八周路线。它的原则很简单：先手动后框架、先小模型后大模型、先跑通后优化。

第4周选框架时，我给的建议是别贪多。LangChain资料多但抽象层级复杂，Coze/Dify这类低代码平台上手快、适合验证产品想法，如果你想深入底层就去啃LangChain核心源码。Rust入门者想走Agent方向的，可以把第3周的那个Python循环用Rust重写一遍，体会一下所有权系统在并发Agent调度里的约束。

5.2 用Django接Agent：为什么必须上异步任务

搜索引擎里经常有人搜"用ai agent开发django"。我的第一反应是：你千万别直接在Django的同步视图函数里调Agent。Agent循环是典型的长耗时任务，动辄一二分钟，而HTTP请求等待时间是以秒计的。你在视图里同步跑Agent，用户请求会被挂起，网关会超时报错，而且每来一个请求就占一个进程，服务直接瘫掉。

正确的姿势是把Agent当作一个异步任务丢到队列里执行。我用过的组合是：Django + Celery + Redis。用户发起请求后，接口立刻返回"任务已提交，ID为xxx"，真正的Agent运行交给Celery worker在后台跑，跑完再通过WebSocket、回调或前端轮询把结果交给用户。

一个简化版的Celery任务定义大概是这样的：

# tasks.py from celery import shared_task @shared_task(bind=True, max_retries=3) def run_agent_task(self, user_input: str): try: result = run_agent(user_input) # 就是你手写的那个Agent循环 return result except Exception as e: self.retry(exc=e, countdown=30)

Django视图里只需要异步触发它：

# views.py from django.http import JsonResponse from .tasks import run_agent_task def agent_api(request): user_input = request.POST.get("message") task = run_agent_task.delay(user_input) return JsonResponse({"task_id": task.id, "status": "queued"})

另外强调一点：Agent跑出来的结果，一定要先校验再入库。模型输出偶尔会有幻觉内容，尤其是工具返回为空时，Agent可能编造一个结果。给Agent的回复加一道正则或字段校验闸门，是我在多个项目里被坑过后总结出来的经验。

5.3 一个贴近生活的落地案例：自动发消息类Agent的合规拆解

"AI Agent让小红书自动发消息"这类玩法经常上热搜。作为技术，它的本质不复杂：Agent调用平台开放的接口或通过浏览器自动化模拟操作，按设定的文案和频率去执行"发私信、发评论"之类的重复动作。作为一个从零到一的技术练习，理解这套"定时触发 -> 生成内容 -> 调用渠道接口 -> 记录反馈"的流水线是很有价值的。

但我要泼一盆冷水：在真实业务里，这类自动行为必须严格遵守平台规则。几乎所有内容平台都对机器批量行为有明确限制，自动私信、刷量、群发轻则触发风控封号，重则涉及违规推广。如果你在练手，我强烈建议把目标替换成同样技术框架但合规的场景，比如"自动回复邮件""自动整理会议纪要并发到群""定时生成销售日报"。

核心机制完全一样：都需要目标管理、工具调用、失败重试、日志追踪。等你把这套练熟练了，再在平台开放接口和授权规则允许的范围内，去实现一些合规的自动化运营功能，才有意义。

5.4 阿里云AI Agent白皮书这类资料，怎么读才不浪费

打开热搜词，总能看到"阿里云ai agent白皮书"之类的官方报告。这类资料对入门者是有价值的，但价值不在"读完"而在"用来校准认知"。我的建议是：第一遍只看它的框架图和大章节标题，建立全局认知，知道行业都把Agent拆成了哪些层级；等自己动手做了一两个项目之后，再回头精读，这时候你会突然看明白它讲的那些架构、成本、安全章节到底在说什么。

新手最容易犯的错，是把白皮书当参考书从头背到尾。它们往往是行业全景式的，细节不深入，而且观点有一定滞后性。真正能让你成长的，还是前面那张路线图里的动手项目。

6. 踩过的坑与最后的几条实在建议

6.1 坑一：上来就上重型框架，结果一周没跑通

我第一次做Agent时，听别人说LangChain好，装了一堆依赖，还接了一堆Model和Memory配置。结果卡在"不同版本的链组件不兼容"上整整两天，最后连一个"让模型告诉我今天星期几"的Demo都跑不出来。后来我把框架全卸了，用原生API手写循环，一个小时就跑通了。这个教训让我养成了一个习惯：任何新技术先问"最朴素写法是什么"，先把朴素的跑通，再考虑值不值得用框架。

6.2 坑二：用传统测试思维去测模型，测到怀疑人生

模型输出天生带随机性，同一个问题可能得到措辞不同的回答。用传统"断言字符串完全相等"的方式测Agent，你会崩溃。我的解决办法分三层：第一，测试时把temperature设为0，降低随机性；第二，让模型以固定JSON格式输出，通过校验JSON结构来做断言；第三，对自然语言结果做"关键内容模糊匹配"，比如断言输出里必须包含某个地址或数字。没有这些手段，你会在CI里看到自己的Agent测试像薛定谔的猫一样时好时坏。

6.3 坑三：忽略"工具描述"的修改对全局的影响

我刚做第二个Agent项目时，有一次模型突然死活不调用工具，直接硬答。排查了半天，发现是我给工具description加了一个"请注意不要在用户不明确的情况下调用"，导致模型以为默认就应"不调用"。Prompt和工具描述就像咒语，差之毫厘谬以千里。改这些文本之前，先想清楚它可能对模型行为产生什么样的连锁反应。

6.4 最后三点，送给准备动手的你

第一，设边界。给Agent限定工具白名单、最大步数、超时时间，就像给实习生交代"你只负责这三件事，遇到其他情况先回来问我"。没有边界的Agent，迟早会给你整出幺蛾子。

第二，留日志。每一个决策、每一轮工具返回、每一次异常，都留痕。出了问题，日志就是你的现场监控录像。

第三，先小后大。先做一个能用未用的小Agent，再慢慢加记忆、多工具、多角色。我见过太多项目死在"第一天就想做全平台自动运营机器人"的野心上了。

做Agent最迷人的地方在于，它没有标准答案，每个项目都会长出完全不同的形态。你手搓的第一版循环可能会很粗糙，但它教会你的东西，比任何最新框架文档都值钱。希望这篇入门手册能帮你把那层雾拨开，剩下的事，就是打开编辑器，先把那个房源查询Agent跑起来。