Agent开发入门：从ReAct循环到大模型工具调用实战

1. 别急着写代码，先想清楚Agent到底是个什么东西

最近大模型、Agent这两个词快被聊烂了。打开任何技术社区，铺天盖地都是Agent架构、Agent框架、Agent安全相关的帖子，但真有人问“Agent开发到底怎么入门”的时候，我发现大部分回答不是甩一堆概念，就是直接丢一个LangChain教程链接，看完反而更懵。

我自己的感觉是，Agent开发并不是一门独立的新技术，而是把大模型（LLM）的能力“产品化”的一套方法论。说白了，大模型本身是一个只会接话的“文本生成器”，你问它什么它答什么。但Agent不一样，Agent是让大模型变成一个“能自己想办法完成任务的人”——它会拆解任务、调用工具、查看结果、调整策略，直到把事情做完。这里面的核心差异，就是“被动问答”和“主动行动”的区别。

这篇内容我主要想写给三类人看：第一类是刚接触大模型，想搞明白Agent到底该怎么下手的新人；第二类是已经在用LangChain之类的框架，但遇到问题不知道怎么排查的初级开发者；第三类是后端转AI应用开发，想快速建立Agent开发知识体系的技术人。我会把从概念、选型、架构到实操、避坑的完整路径捋一遍，尽量不绕弯子。

先泼一盆冷水：Agent开发的门槛不在写代码，而在“设计”。代码写起来无非是调API、处理JSON、拼Prompt，但这些表面工作底下藏着大量的边界情况——模型输出格式不稳定怎么办？工具调用参数错了怎么兜底？多轮对话下来上下文爆了怎么办？这些问题不提前想清楚，Demo跑通得越顺利，上线之后摔得就越惨。

2. 从零选型：框架、模型和工具链怎么搭

2.1 框架选型：LangChain、LlamaIndex还是自己写

几乎每个入门Agent开发的人都会先撞上这个问题。市面上的框架五花八门，LangChain体量最大、生态最全，LlamaIndex侧重检索增强，还有各种新兴的轻量框架和国内团队开源的方案。很多人纠结选哪个，我的建议很直接：新手首选LangChain，但不要深陷其中。

LangChain的好处是抽象层帮你把很多脏活累活都干了。对话记忆管理、工具调用解析、Chain串联这些基础能力开箱即用，对于快速验证想法来说确实省事。但LangChain的问题也恰恰出在抽象层上——出了问题你不知道是它帮你拼的Prompt有问题，还是它解析模型输出时挂了，还是它内部某些参数没按你想的来。我见过太多人Debug了一下午，最后发现问题出在LangChain老版本某个类的方法签名变了，这种时间成本远高于自己写一套简单实现。

所以我给的建议是分两步走：第一，用一套轻量的自研方案把Agent的核心原理跑通，代码最多两三百行，彻底理解ReAct循环是怎么转起来的（后面第4章我会给出完整的代码）；第二，再回去看LangChain的源码，这时候你会发现自己能看懂它在帮你做什么了，甚至能预测它在哪些地方会出问题。

如果是纯粹做检索问答类的场景，LlamaIndex可以重点考虑，它在数据索引和检索这块比LangChain做得好。但要注意，LlamaIndex的核心定位是RAG（检索增强生成），不是通用Agent框架，如果硬要用它做复杂工具调用，你会发现自己是在跟框架的设计初衷对着干。

2.2 模型选型：工具调用能力是核心指标

选模型这事，很多新手有个误区：只看跑分和参数量，忽略了一个Agent开发里最关键的能力——结构化输出和工具调用支持。

Agent的运行机制是这样的：大模型本身不会真的调用任何函数，它只是在生成文本，但它的文本是带有特定格式的“调用指令”（通常是一段JSON），然后由你写的代码来解析这段JSON，再去执行真正的函数调用。所以模型生成的JSON格式是否稳定、是否严格遵守你给定的工具定义schema，直接决定了Agent能不能正常工作。

我自己测试下来的感受：目前主流的大模型API基本都支持Function Calling/Tool Use，但能力差距依然明显。一些模型在简单场景下表现都还行，但一旦你给了七八个工具定义，要求它从里面选一个并填对参数，有些模型就开始犯迷糊了：漏参数、参数名拼错、JSON里混进多余字段，都可能发生。

如果你是做中文场景、希望API稳定省心，直接用国内大厂的开放平台接口就够了，百度、阿里、字节这些都有兼容OpenAI格式的工具调用接口，文档也齐全。如果追求效果上限、不担心网络问题，也可以对比GPT系列和Claude系列。最关键的判断标准不是我在这里告诉你谁最强，而是拿你自己的工具列表和几个典型用户输入去实测一轮，看谁的输出格式最干净、参数填充最准确。

如果是用本地部署的模型，情况会更复杂一些。本地小模型（10B以下）的JSON生成稳定性普遍较差，经常出现“模型回答很完整但就是没法被代码解析”的情况。后面第4.4节我会专门谈本地模型跑Agent的取舍问题。

2.3 环境搭建：API、项目结构和必要依赖

先把这个最简单也最容易出问题的一步说清楚。无论你选什么框架，第一步做的事都差不多：注册API服务、拿到Key、准备好Python环境。

我的建议是无论如何先把openai这个Python包装上，因为现在几乎所有国内大模型平台的接口都兼容OpenAI格式，只需要改base_url和api_key，代码逻辑可以完全复用。这个兼容设计是整个Agent开发生态里的一个大福利，它让“切换模型”变成了一件很轻的事。

项目结构上，我推荐新手从一开始就按模块化来组织，不要图省事全部写在一个Jupyter Notebook或者单个文件里。一个比较舒服的起步结构是这样的：

• agent/目录放核心Agent逻辑
• tools/目录放各种工具函数，每个工具写成一个独立函数，用统一的装饰器注册
• memory/目录管理对话历史
• config.py统一放模型配置、API Key等
• main.py作为入口

这样划分的好处是：当你的工具从1个涨到10个的时候，你不需要在一个几千行的文件里翻来翻去。而且工具函数的注册方式一旦统一，后续加新工具只需写一个函数，成本非常低。

3. 核心架构拆解：规划、记忆、工具与行动

3.1 规划能力：让大模型学会拆解任务

Agent最核心的能力之一就是规划。用户提一个模糊的、复杂的请求，Agent需要把它拆成可执行的子任务，然后按顺序执行。这个过程在行业里最经典的实现模式叫ReAct，简单说就是“思考-行动-观察”的循环：模型观察用户输入，思考下一步该做什么，输出一个行动（通常是调用工具的指令），系统执行工具并返回结果，模型再观察这个结果，继续思考下一步。这个循环会一直持续，直到模型判断任务已经完成。

听上去很玄乎，但实现起来其实很直白——你要做的就是通过Prompt告诉模型：“你有这些工具可以用，你需要一步步来，每一步先思考再行动，行动后观察结果，直到你认为任务完成了，才输出最终答案。”就这么简单。大模型本身读了大量代码和文档，天然理解这种思维链模式，只要你的Prompt把工具清单和约束说清楚，它就能自己“规划”起来。

但这里有一个很现实的问题：模型输出的“规划质量”直接受限于模型的推理能力。对于简单的两三个步骤的任务，小模型也能做好；但对于那种流程长、决策分支多、需要根据中间结果动态调整策略的复杂任务，小模型大概率会跑偏——要么漏掉关键步骤，要么在某个环节反复打转。所以规划能力这件事，与其说是你在设计算法，不如说是在给模型“出题”，模型本身的智力水平决定了下限。

3.2 记忆系统：短期上下文和长期存储

Agent如果没有记忆，就会变成“每次对话都失忆的鱼”。记忆系统大致分两层。

短期记忆就是上下文窗口里的对话历史。大模型本身没有记忆，全靠你把历史对话塞进请求里。实践中最常见的问题是上下文无限膨胀——用户聊了半个小时，每条历史都发给模型，Token消耗越来越大，响应也越来越慢，而且模型会被冗长的历史搞糊涂，分不清哪些是用户当前真正的问题。

所以短期记忆管理的核心是“裁剪”和“遗忘”。我的做法是：最新几轮对话完整保留，更早的对话做摘要后再塞回去，最久远的直接丢弃。这个机制用LangChain的ConversationSummaryBufferMemory能自动做，但自己实现也不难——就是算Token长度，超了就触发摘要，把摘要放在会话顶部，后面跟着最近的完整对话。

长期记忆则是把重要信息沉淀到外部存储里。比如用户在一个长期项目里反复提到“我的服务器是4核8G”“我倾向用开源方案”，这些信息没必要每次都让模型从零理解，你可以把用户画像、项目常量等存在向量数据库或普通数据库里，在每次对话开始时检索出相关内容拼进Prompt。这就是Agent“越来越懂你”的实现方式。

3.3 工具系统：Agent的手和脚

工具是Agent区别于普通聊天机器人的分水岭。没有工具，大模型说得天花乱坠也只能停在嘴上；有了工具，它才能真正改变世界——查天气、搜网页、读写文件、执行代码、调数据库、发HTTP请求。

工具的设计有几个原则。第一，工具的输入输出要尽量简单、结构化。每个工具就是“输入一个JSON，输出一个字符串”，这样大模型又好理解，你解析起来也省心。第二，工具的描述要极其详细。别只写“search_web”，要写清楚“搜索互联网并返回网页摘要列表，支持site:操作符，适合检索实时信息。输入参数query为搜索关键词字符串”。模型是依靠描述来判断何时用这个工具的，描述不给力，它就会瞎用或者不用。第三，工具要有失败反馈机制。工具执行出错时，不要直接抛异常中断整个Agent，而是把错误信息作为结果返回给模型，让它自己尝试换一种方式解决。这是Agent健壮性的关键。

3.4 行动与反馈：从生成文本到执行动作

行动层就是整个循环的“物理引擎”。模型输出一段文本，你的代码解析出其中要调用哪个工具、传什么参数，然后真正执行那个函数，再把返回值重新交给模型。这个看似简单的过程，实际上藏着大量繁琐的边界工作。

最麻烦的是模型输出的解析。模型吐出来的内容可能是{"action": "get_weather", "action_input": {"city": "北京"}}，也可能在JSON前后混入“好的，让我查一下北京的天气”这种自然语言，还可能是残缺的JSON（比如被截断了）。所以你的解析代码必须非常宽容：先尝试从完整文本中提取JSON块（用正则匹配{...}），再尝试修复常见错误（多余逗号、单引号、尾随空格），实在解析失败就告诉模型“你的输出格式不符合要求，请重新输出”，让它自己纠正。

执行完工具后，反馈信息也需要整理。工具返回的长文本结果，如果直接原样塞回给模型，既浪费Token又可能让模型淹没在细节里。好的做法是：截断超长结果，提取关键部分，必要时让工具自己输出“面向模型的摘要”而不是“原始数据”。

4. 手把手写一个Agent：从环境到第一个完整Demo

4.1 最小可运行的ReAct循环

光说不练假把式。这一节我带着你从零写一个最小Agent，代码量压到最少，但会把核心循环跑通。先装一个依赖：

pip install openai

然后写一个可运行的文件，大致逻辑是：向模型传递系统提示词（告诉它有哪些工具、怎么用），拿用户输入和对话历史去调用模型API，如果模型返回工具调用请求，就执行对应函数并再次调用模型，直到模型返回最终答案。

为了把原理讲透，我这里用了一个非常直观的实现思路：让模型的输出格式严格遵循一个约定。模型如果决定要调用工具，就输出一个特定格式的JSON；如果决定直接回答，就输出FINAL ANSWER: ...。这种模式叫“结构化约定调用”，你不需要依赖特定平台的Function Calling也能跑通，对理解Agent内部机制特别有帮助，而且本地小模型也适用。

下面是一段核心示意代码：

import json from openai import OpenAI client = OpenAI(base_url="你的API地址", api_key="你的APIKey") TOOLS = """ 工具列表： 1. get_weather(city: str) - 查询指定城市的实时天气，city为城市名 """ def get_weather(city: str) -> str: # 这里原本应该真实请求天气API，演示时直接返回模拟数据 return f"{city}今天多云，气温18~26度，微风" def run_agent(user_input: str): messages = [ {"role": "system", "content": f"你是一个能调用工具的助手。{TOOLS}当你需要查询信息时，请输出严格JSON格式的调用指令，例如：{{\"tool\": \"get_weather\", \"params\": {{\"city\": \"北京\"}}}}。当你知道最终答案后，请以FINAL ANSWER开头输出答案。"}, {"role": "user", "content": user_input} ] # 最多循环五个思考轮次，防止死循环 for step in range(5): response = client.chat.completions.create( model="你的模型名", messages=messages, temperature=0, ) content = response.choices[0].message.content # 尝试解析JSON try: start = content.find("{") end = content.rfind("}") + 1 call = json.loads(content[start:end]) messages.append({"role": "assistant", "content": content}) result = globals()[call["tool"]](**call["params"]) messages.append({"role": "system", "content": f"工具返回结果：{result}"}) continue except Exception: # JSON解析失败，说明模型可能在输出最终答案 if content.strip().startswith("FINAL ANSWER"): return content.replace("FINAL ANSWER", "").strip() # 否则让模型重新输出 messages.append({"role": "assistant", "content": content}) messages.append({"role": "system", "content": "你的输出格式不符合要求，请务必输出严格JSON格式，或以FINAL ANSWER开头直接给出答案。"}) return "达到最大循环轮次，任务终止。" if __name__ == "__main__": print(run_agent("北京今天天气怎么样？"))

这段代码是最简版，但完整体现了Agent的核心骨架：模型决策、工具注册、解析执行、反馈循环。真正常见的Agent框架，做的工作也无非是在这个循环上增加更多健壮性处理、更复杂的记忆管理和更优雅的工具注册机制。

4.2 加一个工具：让Agent真正“干活”

上面的Demo只演示了一个工具，但实际项目里工具往往一大堆。我建议你用一个装饰器来统一注册工具，让新增工具变成一件只有几行代码的事。下面是一个更真实一点的结构示意：

import json tool_registry = {} def register_tool(name, description): def wrapper(func): tool_registry[name] = {"func": func, "description": description} return func return wrapper @register_tool("get_weather", "查询城市实时天气，参数city为城市名") def get_weather(city: str): return f"{city}今天多云，温度适宜" @register_tool("add_note", "添加备忘笔记，参数note为笔记内容") def add_note(note: str): with open("notes.txt", "a") as f: f.write(note + "\n") return "笔记已保存" # 动态构造系统Prompt里的TOOLS部分 def build_tools_prompt(): parts = [] for name, meta in tool_registry.items(): parts.append(f"- {name}: {meta['description']}") return "工具列表：\n" + "\n".join(parts)

这样设计以后，你往Agent里加新能力就变成了写个函数、加装饰器两件事。而且工具的描述会被自动拼到Prompt里，不会出现“工具注册了但模型不知道有这个东西”的低级问题。

我在实际项目里还习惯给每个工具加一个check_params函数，用来在真正执行前校验参数。比如某个工具要求city必须是文本且长度不超过20个字符，如果模型传了个乱七八糟的类型，校验能提前拦住，而不是让底层函数报出莫名其妙的异常。

4.3 接入RAG：给Agent加上外部知识

Agent跑起来以后，你很快会遇到一个尴尬：它什么都会，但“什么都不知道”。你问它一个2024年发布的新产品信息，它一脸茫然。这时候就需要RAG——把外部知识库的内容检索出来，拼进Prompt，让模型在回答前先“读资料”。

RAG和Agent的关系不是对立的，RAG是工具的一种形态。你可以实现一个search_knowledge_base(query)工具，内部走向量检索流程：把知识文档切片、向量化存进向量数据库，查询时把用户问题向量化，做相似度搜索，返回最相关的几段内容。Agent在回答前判断需要外部信息时，就会主动调用这个工具。

我用的是最经典的流程：文档切片（500~800字一段，按语义边界切割）、嵌入向量化（用bge或text-embedding系列模型）、存入向量库（Chroma或Milvus都行，个人项目用Chroma最省心）、检索召回（取Top 3~5段）。这里有个很容易踩的坑：检索回来的内容并不是每段都相关，你最好让模型自己判断——把检索结果和用户问题一起喂给模型，它会比硬性拼接靠谱得多。

4.4 本地小模型也能跑Agent？性能实测与取舍

团队里之前有个项目因为数据敏感，不能调用云端API，只能在内部服务器上部署本地模型。当时我们拿7B级别的开源模型做Agent，发现了一个规律：模型的对话能力是够的，但工具调用能力很不稳定。最常见的表现是它知道要调用工具，也知道工具的用途，但输出的JSON经常在参数上翻车——把{"city": "上海"}写成{"city": "上海", "unit": "celsius"}这种多字段还能容忍，但有时候它会把两个工具的参数混在一个JSON里，解析逻辑如果不够宽容，整个Agent就卡死了。

后来我们把方案改成了“两步走”：第一步让模型先“想”再“写”——第一轮输出干巴巴的自然语言，说明它想调用哪个工具、传什么参数；第二轮再让模型把这个想法转成严格JSON。虽然多了一次调用、响应慢了一点，但格式出错的概率大幅降低。这也验证了我前面说的那个观点：本地小模型跑Agent完全可行，但要在工程上做防御性设计，不要指望模型自己把格式吐得很完美。

另外提醒一下，本地部署模型的话，推理速度是个硬约束。7B模型在普通消费级显卡上跑一个ReAct循环，每步可能要几秒到十几秒，Agent要转好几步才能完成一个任务，用户体验会很难受。所以本地模型更适合做后台批量任务，不太适合做交互式实时Agent服务。

5. 进阶话题：多Agent协作、并发和成本控制

5.1 多Agent协作：从单兵作战到团队作战

单个Agent的能力有天花板，尤其在处理复杂流水线任务时，一个Agent既要理解用户意图又要调工具还要写结果，Context很容易乱。多Agent架构就是让不同Agent各管一摊，有点像软件开发里拆分微服务。

业界常见的模式有两种。一种是“规划者-执行者”模式：规划Agent负责拆解任务、分配指令，执行Agent只负责具体执行并返回结果。另一种是“同行评审”模式：一个Agent干活，另一个Agent检查它的成果，挑毛病、打回重做。两个模式我都试过，前者结构清晰、适合稳定项目，后者能显著提升输出质量，但会多耗一倍Token，怎么取舍要看场景。

多Agent之间怎么通信？最简单的方案就是共享一个消息队列。每个Agent从队列里取任务，处理完把结果放回队列。你用Redis也好、用Python的queue模块也好，核心是给每条消息带上任务ID和来源/目标信息，这样才能追踪流程、定位问题。

多Agent不是银弹，我先说结论：只有在对任务有确定性拆分的场景（比如内容生成流水线、数据清洗流水线），多Agent的收益才明显；如果是开放式的问答场景，一个精心调优的Agent配几把好“工具”通常比三个互相扯皮的Agent强得多。

5.2 Agent并发和性能：API限流与请求管理

Agent上线以后，并发问题是最早暴露的。和普通API接口不一样，Agent的每一次用户请求，内部会产生多次模型调用。所以你的后端承受的QPS不是用户请求量，而是“用户请求量 × 每轮Agent平均模型调用次数”。打个比方，一个用户请求进来，Agent内部转了4轮，那你一个用户就占了4次模型调用配额。100个用户同时提问，就是400次调用。

面对这个问题，第一件事是摸清API的并发限制。各家平台的限流策略不同，有按QPS限的，有按TPM（每分钟Token数）限的。你要在代码层面做两件事：一是给模型调用加一个重试机制，遇到429（请求过多）或5xx错误时指数退避重试；二是做请求合并和排队，必要的时候引入消息队列，把高峰期的请求削峰填谷。

很多新手问要不要上缓存，我强烈建议上。Agent的同一个工具调用结果如果和近期某个请求完全一样，可以直接返回缓存结果，省一次模型调用。比如查询相同的城市天气，模型完全没必要重新跑一遍工具。但对于生成类任务（让模型写文章），缓存要慎重，因为同一个Prompt每次都生成不同内容才是对的，不要乱开缓存。

5.3 Token成本控制：别让Agent烧钱烧到怀疑人生

Agent开发里有个隐形陷阱：成本。普通聊天一次调用平均几百Token，但Agent一个任务动辄就要几千甚至上万Token——因为多轮思考、多轮工具反馈，每轮都会累计长度。我见过最夸张的例子，一个Agent做一次资料汇总任务，烧掉了3万多个Token，折合人民币几块钱，用多了真的肉疼。

控制成本的手段总结下来就几条。一是精打细算Prompt：系统提示词里的工具描述要精炼（但不该省的不能省），避免什么“你是一个乐于助人的助手”这种废话；二是控制历史轮次：前面说的记忆裁剪机制，不只是为性能，更是为了钱包；三是长任务分段执行：不要指望模型一口气干完一个大任务，拆成几步、每步用完就释放上下文，比一股脑长对话省得多；四是缓存：对高频的、确定性的子任务做结果缓存。

还有个小技巧：可以按任务难度分流模型。简单判断类任务走便宜的小模型，复杂推理任务再走贵的大模型。别所有请求都打最强的那个模型，成本一下就能砍下来不少。

6. 避坑指南：从入门到放弃之间的距离

6.1 常见问题速查表

废话不多说，我直接把Agent开发里最常踩的坑整理成一张表。这些基本是我自己在项目里血泪换来的验证经验。

6.2 几个必须自己踩过才懂的设计教训

第一个教训是：不要让模型免费干活。很多新手会让Agent自己“思考怎么解决问题”，却不给它任何约束。这样模型会绕很多弯路，甚至会幻想出一些根本不存在的步骤。更好的做法是给它“工具链引导”——你在系统Prompt里写清楚“遇到XX类问题，优先使用XX工具，不要尝试通过常识回答”，省去大量无关推理。

第二个教训是：错误别中断，喂回去让模型自己修复。Agent和普通程序最大的不同是它具有“自我纠错”的潜力。当工具执行失败时，把错误信息塞给模型，让它自己分析原因并换一种方式重试，往往比直接在代码里抛异常更有效。这不是碰运气，而是模型推理能力的正常利用——但一定要给重试设置上限（比如最多两次），防止它一条道走到黑。

第三个教训是：测试集比Agent更值得投入。写Agent的时候一定要维护一套测试用例——正常的请求要有，异常的、边界条件的、恶意输入的更要有。每次修改Prompt或工具逻辑，都拿这套测试跑一遍，防止“修一个坑炸另一个坑”。这比任何框架都重要。

6.3 我的一个核心心得，分享给即将入门的你

做Agent开发这两年，我最深的体会是：Agent本质上不是一个“写出来的系统”，而是“调教出来的系统”。它的每一分智能，都来自Prompt设计、工具编排和反馈机制的反复打磨，而不是某天突然写出来就完美了。第一次跑通Demo确实让人兴奋，但那只是开始，真正让人又爱又恨的，是后面无数轮“为什么模型偏偏不按我想的来”的折磨。

不过也正因为这样，这件事才特别有意思。每次你解决掉一个“模型怎么都搞不定”的问题，都会对整个系统的理解加深一层。如果你正在入门这个方向，我的建议是：别害怕从最笨的代码写起，别迷信任何框架，先把一次完整的ReAct循环跑通、把工具的来龙去脉搞清楚，再谈架构和优化。底子打实了，后面无论用哪个框架、接哪个模型，你都会比别人更稳。祝入坑顺利。