很多想转行大模型开发的读者最初都会被“AI Agent”这个概念卡住。网上资料多但碎片化严重有的讲 LangChain 源码有的直接跑开源项目有的全是在讲提示词技巧很难形成一条完整的进阶链路。如果你也是这种情况这篇文章就是为你准备的。我会从一条完整的 Python AI Agent 学习主线出发拆解智能体开发中真正绕不开的核心模块包括大模型 API 的调用方式、Agent 的记忆与工具调用机制、ReAct 模式的实现原理以及本地部署和实际项目落地时的工程要点。这篇文章不会只贴概念而是会给出可运行的最小示例、环境搭建步骤、常见坑点以及一套从零基础到能开发自定义智能体的学习路径。读完你会清楚AI Agent 到底在解决什么问题它的核心机制是什么从零开始应该按什么顺序学以及学到什么程度可以够到“大模型 Agent 开发”这个岗位的基本门槛。1. 为什么 AI Agent 突然成为大模型开发的核心方向先下一个判断AI Agent 不是大模型的附属玩法而是大模型从“对话工具”走向“生产力工具”的关键一跳。在 Agent 出现之前大模型的主要使用方式是 ChatBot。你问一句它答一句。模型有常识、有推理能力但它没有手、没有脚无法操作外部系统也无法持续完成一个多步骤任务。比如你让它“帮我查一下这个目录下的文件找出所有包含报错信息的日志并汇总成表格”传统 ChatBot 只能给你一段代码让你自己复制运行。AI Agent 改变了这个闭环。它让大模型不仅“能说”还能“行动”。Agent 可以调用工具、读取文件、搜索网页、操作数据库、调用其他模型的 API甚至在自己执行结果的基础上继续规划下一步动作。链条变成大模型负责思考和决策工具负责执行代码负责把两者粘合起来。从 2025 年到 2026 年整个大模型行业已经很少再讨论“模型参数多大”“榜单分数多高”而是开始讨论“这个模型能不能稳定调用工具”“能不能在复杂任务里不跑偏”。也就是说行业竞争的重点已经从前端模型能力转移到了后端的 Agent 工程化能力。再说回学习价值。对一个 Python 开发者来说AI Agent 是当下性价比很高的进阶方向。它不需要你从零发明算法也不需要你训练模型只需要你掌握大模型 API 的调用方式、理解 Agent 运行机制并具备一定的工程能力就能做出不少实用的智能体应用。这也是为什么大量 Java、Python 背景的开发者和学生开始系统学习 Agent 开发。这篇文章对应的学习主线就是围绕“从零搭建自定义智能体”展开的先学 Python 基础再学大模型 API然后理解 Agent 内部机制最后落地成一个完整的 Agent 项目。2. Agent 是什么从 ChatBot 到智能体的核心差异2.1 大模型、Agent、AI Agent 三者的关系很多初学者会把“大模型”和“Agent”混为一谈。实际上它们的层级关系非常清晰概念含义举例大模型具备语言理解和生成能力的模型GPT 系列、Qwen、DeepSeek、GLMChatBot基于大模型的对话应用各类 AI 助手Agent能感知、决策、执行、反思的智能系统自动编程助手、自动客服、数据分析智能体大模型是“大脑”Agent 是“完整的人”。大脑只负责思考人还要通过眼睛看、耳朵听、手操作、脚移动来接触世界。对应到技术上Agent 大模型 规划能力 工具调用 记忆系统。2.2 Agent 为什么需要工具调用先看一个传统大模型无法完成的任务用户帮我统计一下当前目录下所有 Python 文件的行数并按行数从大到小排列。模型知道“Python 文件”和“行数”是什么意思但它看不到你的文件系统无法执行os.walk也不能直接运行命令。于是模型只能给你一段代码让你自己去跑。Agent 的方法是给模型配备一个“执行代码”的工具模型只需要在回答中声明“我要调用工具 execute_python_code参数是 ……”系统收到这个声明后自动执行代码并把结果返回给模型模型再根据结果继续回应。这个过程的本质是把模型的一次性输出变成多轮“思考—行动—观察”循环。技术界称它为 ReAct 模式Reason Act即推理与行动结合。正是这个循环让大模型第一次具备了完成真实任务的能力。2.3 Agent 的四个核心模块从工程角度看一个标准 Agent 包含以下模块大脑引擎LLM负责理解任务、拆解步骤、生成决策。规划模块Planning把复杂任务拆成多个子步骤并对每个子步骤选择工具。工具集Tools包括代码执行器、搜索工具、API 请求工具、数据库查询工具等。记忆模块Memory包括短期记忆对话上下文和长期记忆向量数据库、用户偏好存储。如果你要自己搭建 Agent第一步不是写代码而是理解这四件事分别对应什么组件以及它们之间如何通信。后面我们会在代码示例里完整呈现。3. 学习路径从 Python 基础到自定义 Agent 完整体系结合前面提到的课程主线下面这条学习路径适合从 Python 零基础开始走最终目标是用 Python 开发一个具备工具调用能力的自定义 Agent。3.1 阶段一Python 基础与工程化能力这一阶段的目标不是“会用 Python 写语法”而是“具备用 Python 支撑一个项目的工程能力”。需要掌握的知识点包括基本语法变量、数据类型、条件判断、循环、函数。面向对象类、对象、继承、类的封装与抽象。文件与异常处理读写文件、捕获异常、自定义异常。常用标准库os、sys、json、datetime、re。第三方库管理pip、virtualenv、requirements.txt。爬虫基础requests、BeautifulSoup或lxml用于给 Agent 增加网页信息获取能力。数据基础能处理 JSON 格式的 API 请求与响应。很多人认为学 Python 只需要刷语法题这是最大的误区。Agent 开发是典型的工程化任务代码组织能力比语法炫技重要得多。3.2 阶段二大模型 API 与大模型基础原理Agent 的“大脑”是外部大模型。你需要先学会怎么“给大脑下达指令”。这一阶段需要理解API 调用基本流程构造请求、发送请求、解析响应。Token 与上下文的含义模型能接受的输入长度决定你能否把完整任务发给它。System Prompt、User Prompt、Assistant 消息的角色区分。大模型的基础原理为什么模型能生成内容什么是注意力机制只需理解级即可不要求手推公式。主流大模型的基本参数temperature温度、max_tokens、top_p 等。从免费 API 开始练习是不错的选择但需要注意不同厂商的 API 兼容协议不同工程中通常通过统一封装层屏蔽差异。3.3 阶段三Agent 机制与工具调用当你已经会调用大模型 API接下来就是让模型“具备行动力”。这是 Agent 开发的核心阶段需要理解ReAct 模式模型如何输出一个行动系统如何执行行动结果如何反馈给模型。Function Calling函数调用/工具调用大模型厂商提供的一种结构化输出能力模型返回一个 JSON 结构声明要调用哪个函数、传什么参数。Tool 的定义与注册如何把一个 Python 函数变成模型可识别的“工具”。多轮工具调用一个任务可能需要连续调用多个工具模型如何规划顺序。记忆管理上下文太长怎么办哪些信息需要长期保存。这一阶段可以先用自制代码实现一个最小 Agent再用 LangChain 或 LlamaIndex 等框架简化开发。3.4 阶段四完整项目实战学习 Agent 开发的最终目的是落地项目。建议至少完成下面几类项目个人知识库问答 Agent使用向量数据库存储文档片段让 Agent 基于本地文档回答。数据分析 AgentAgent 通过 Python 代码工具读取 CSV、做统计、画图表。自动化运维 AgentAgent 读取日志文件分析异常模式生成排查建议。日程管理与信息聚合 AgentAgent 通过 API 获取天气、新闻、日程信息汇总后回答用户。学完这四个阶段你对 Agent 开发的理解已经不是“调 API 的小技巧”而是一套完整的系统设计能力。4. 环境搭建Python、依赖管理与大模型 API 准备在写 Agent 代码之前先把环境准备好。这里给出一套通用的环境准备步骤版本以你实际安装为准重点是明白每一步在做什么。4.1 安装 Python 并验证如果你还没有 Python 环境先到 Python 官网下载安装包Windows 用户注意勾选“Add Python to PATH”。安装完成后在命令行验证python --version pip --version如果命令提示找不到python检查安装时有没有勾选添加 PATH。macOS 和 Linux 用户可以使用系统包管理器安装例如 Ubuntu 下的apt install python3 python3-pip。4.2 创建虚拟环境Agent 项目依赖通常较多强烈建议为每个项目单独建一个虚拟环境避免不同项目依赖冲突mkdir my-agent-project cd my-agent-project python -m venv venv激活虚拟环境Windowsvenv\Scripts\activatemacOS / Linuxsource venv/bin/activate激活后命令行会多出(venv)前缀说明虚拟环境已生效。4.3 安装核心依赖库在这里我们安装的是 agent 开发过程中会用到的核心依赖。如果你使用 OpenAI 兼容协议需要openai库如果你后续要用 LangChain再安装langchain。这里先装最基础的几个pip install openai python-dotenv requestsopenai用于调用支持 OpenAI 协议的模型 API。python-dotenv用于从.env文件读取密钥避免把密钥写进代码。requests用于调用非 OpenAI 协议的 HTTP API 或搜索工具。如果你不确定模型服务是否兼容 OpenAI 协议可以先看官方文档。当前大多数国内大模型厂商也提供了 OpenAI 兼容接口这大大降低了切换成本。4.4 配置 API Key在项目根目录创建.env文件写入你的 API KeyOPENAI_API_KEY你的密钥 BASE_URLhttps://你的模型服务地址注意.env文件不能提交到 Git 仓库需要在.gitignore中添加.env。然后创建一个配置文件config.pyimport os from dotenv import load_dotenv load_dotenv() OPENAI_API_KEY os.getenv(OPENAI_API_KEY) BASE_URL os.getenv(BASE_URL)这样可以把密钥和代码隔离团队成员拉取代码后只需要各自配置.env。5. 从零实现一个最小 Agent核心代码拆解理解了概念和环境接下来我们手写一个最小 Agent。这个 Agent 不依赖任何 Agent 框架只用大模型 API 和 Python 函数目标是让你看透 Agent 的最简运行逻辑。5.0 当前实现说明下面示例使用 OpenAI 兼容接口协议。无论你使用的是哪家大模型服务只要它提供 base_url、api_key 和 chat/completions 接口都可以复用这套代码。执行前需要先安装 openai 库pip install openai python-dotenv5.1 定义两个工具函数Agent 的核心能力是“调用工具”。我们先定义两个简单的工具一个是加法计算器一个是获取当前时间。在实际项目中这里可以是“查询数据库”“调用天气接口”等更复杂的函数。工具就是一个普通 Python 函数关键在于我们要把它“注册”给模型让模型知道这个函数的存在、用途和参数格式。# 文件路径my-agent-project/tools.py import datetime def add_numbers(a: int, b: int) - int: 两个整数相加。 return a b def get_current_time() - str: 获取当前日期和时间。 return datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S)这两个函数本身非常简单。重点是下一步如何让大模型知道它们的存在并在合适的场景主动调用。5.2 定义工具描述给模型OpenAI 协议支持通过tools参数向模型声明可用工具。我们把上面的两个函数写成 JSON Schema。这是连接“模型决策”和“Python 函数执行”的关键桥梁# 文件路径my-agent-project/tool_schemas.py tools [ { type: function, function: { name: add_numbers, description: 计算两个整数的加法, parameters: { type: object, properties: { a: {type: integer, description: 第一个加数}, b: {type: integer, description: 第二个加数}, }, required: [a, b], }, }, }, { type: function, function: { name: get_current_time, description: 获取当前日期和时间不需要参数, parameters: { type: object, properties: {}, }, }, }, ]这个步骤的作用是帮大模型把“自然语言表达的任务”映射到“可执行的函数调用”。模型不会直接执行 Python 代码它只负责在回答中输出一个结构化的函数调用指令。执行仍然由你的代码完成。5.3 构建主循环Agent 的最小运行逻辑现在写 Agent 的核心循环。这个循环内部做的事情如下把用户的自然语言问题发送给大模型同时把工具描述也传给模型。大模型判断该不该调用工具。如果不需要调用直接返回回答流程结束。如果需要调用工具模型会返回函数名和参数。你的代码执行对应的函数把结果追加到消息列表。把函数执行结果返回给模型让模型组织成自然语言回答。重复以上过程直到模型不再请求调用新工具。# 文件路径my-agent-project/agent.py import json from openai import OpenAI from config import OPENAI_API_KEY, BASE_URL from tools import add_numbers, get_current_time from tool_schemas import tools def call_llm(messages): client OpenAI(api_keyOPENAI_API_KEY, base_urlBASE_URL) response client.chat.completions.create( modeldeepseek-chat, # 请以你的模型服务实际支持为准 messagesmessages, toolstools, tool_choiceauto, ) return response.choices[0].message def execute_tool(name, args): if name add_numbers: return add_numbers(args[a], args[b]) if name get_current_time: return get_current_time() raise ValueError(f未知工具: {name}) def run_agent(user_input): messages [ {role: system, content: 你是一个有用的助手。当用户的问题需要计算或获取当前时间时请调用对应工具。}, {role: user, content: user_input}, ] for _ in range(5): message call_llm(messages) # 如果模型没有要求调用工具直接输出回答 if not message.tool_calls: print(Agent 回答, message.content) return for tool_call in message.tool_calls: fn_name tool_call.function.name args json.loads(tool_call.function.arguments) print(f调用工具: {fn_name}, 参数: {args}) result execute_tool(fn_name, args) messages.append(message) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) print(已达到最大迭代次数流程结束。) if __name__ __main__: print( 最小 Agent 示例 ) run_agent(你能告诉我现在的日期和时间吗) run_agent(请计算 12345 加上 67890 的结果。)这段代码是整个 Agent 开发学习路径中最核心的一个示例。关键点有三个toolstools把工具描述传给模型模型才能“看到”工具。tool_call_id工具调用的结果必须通过这个 ID 关联回对话模型才能正确理解“这次执行结果是对刚才那次调用的回应”。消息列表不断追加assistant和tool消息这是 Agent 多轮对话的骨架。5.4 运行与验证运行方式python agent.py预期输出类似 最小 Agent 示例 调用工具: get_current_time, 参数: {} Agent 回答 当前时间是 2026-02-15 14:30:22。 调用工具: add_numbers, 参数: {a: 12345, b: 67890} Agent 回答 12345 加上 67890 的结果是 80235。如果运行后模型没有调用工具而是直接给出了回答比如计算题它自己硬算说明模型在你的 system 提示下没有意识到必须使用工具。可以在 system prompt 中加强约束“必须使用工具回答计算类问题”。如果报错提示 API Key 或 base_url 不对先检查.env是否配置正确并确认你的模型服务地址和密钥是否匹配。6. 给 Agent 增加更复杂的能力搜索、记忆与本地知识库最小 Agent 跑通后你已经理解了 Agent 的运行机制。接下来可以逐步给它增加更接近生产环境的复杂能力。6.1 增加网络搜索工具一个常见的 Agent 工具是搜索。你可以用requests库调用搜索 API 或爬取指定网页内容。这种能力让 Agent 不再局限于预训练知识而是可以获取实时信息。# 文件路径my-agent-project/web_tool.py import requests from bs4 import BeautifulSoup def fetch_webpage_text(url: str) - str: 抓取网页正文并提取纯文本。注意请确保你有权访问并使用该网页遵守目标网站的 robots 协议。 headers {User-Agent: Mozilla/5.0 (compatible; MyAgent/1.0)} resp requests.get(url, headersheaders, timeout10) resp.raise_for_status() soup BeautifulSoup(resp.text, html.parser) return soup.get_text(separator\n, stripTrue)[:2000]新增工具后不要忘记在tool_schemas.py中补充对应的 JSON Schema并往execute_tool函数里增加分支。一个容易忽略的坑是很多网页内容动态加载requests拿不到真实数据。工程上有两个方向一是改用无头浏览器方案如 Playwright二是使用合适的搜索 API 让服务商直接返回结构化结果。新手阶段建议优先使用 API把精力放在 Agent 逻辑上而不是爬虫对抗上。6.2 记忆机制为什么 Agent 经常“聊着聊着就忘了”大模型的上下文窗口是有限的。当对话超过上下文长度历史消息就会被截断或丢失。Agent 应用中常见的做法是短期记忆只保留最近 N 轮对话。长期记忆把重要的用户信息、历史结论写入外部存储向量数据库或普通数据库下次对话时检索出来补充到 prompt 中。从最小实现角度看短期记忆可以在前面代码的基础上做两处修改每次用户提问先截断messages中第 1 条之后的早期消息。用一个单独变量保存核心结论在构造系统消息时注入。从更工程化的角度看真正解决记忆问题需要引入向量数据库如 Chroma、Milvus 等把用户历史信息拆块向量化存储每次对话时做语义检索把最相关的内容放进上下文。6.3 本地知识库问答 Agent本地知识库问答是目前最实用的 Agent 项目类型之一。它解决的是“让模型基于企业私有文档回答”的问题。主要流程是离线阶段把文档切分成片段对每个片段做 embedding向量化存入向量数据库。在线阶段用户提问时把问题向量化在向量数据库中检索相似片段。把检索结果拼进 prompt让大模型基于给定材料回答。这条路线的关键不在于“调用大模型”而在于召回质量。如果片段切分太短语义不完整太长又会混入无关内容。工程实践中需要针对文档类型反复调优 chunk size 和 overlap 参数。7. LangChain 与从零实现什么时候用框架什么时候手写市面上大部分 Agent 教程会直接带你用 LangChain。我的建议是先手写一个最小 Agent再上框架。7.1 手写的价值手写 Agent 的价值在于让你明白“框架底下发生了什么”。当你看到 LangChain 里的agent.run()时你能意识到背后其实就是“模型输出 tool_call系统执行函数结果回填给模型”这样一个循环。这样后续遇到复杂 bug 时你不会一头扎进框架源码的海洋而是能从基本原理出发做判断。7.2 LangChain 适合什么场景LangChain 真正降低的是“工具生态的对接成本”。它内置了大量文档加载器、向量库集成、模型接口适配、记忆组件。如果你要在两天内做一个带知识库的 Agent 原型用 LangChain 是合理的选择。一个简单的 LangChain Agent 示例# 文件路径my-agent-project/langchain_agent_demo.py from langchain_core.tools import tool from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate tool def add_numbers(a: int, b: int) - int: 两个整数相加。 return a b llm ChatOpenAI(modeldeepseek-chat, api_key你的密钥, base_url你的接口地址) prompt ChatPromptTemplate.from_messages([ (system, 你是一个有用的助手), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, [add_numbers], prompt) executor AgentExecutor(agentagent, tools[add_numbers], verboseTrue) result executor.invoke({input: 请计算 12345 67890}) print(result)从代码量上看LangChain 确实省了不少事。但代价是你必须理解agent_scratchpad、AgentExecutor这些抽象概念。新手如果对 ReAct 循环没有概念直接用 LangChain遇到报错很容易懵。7.3 更稳妥的判断正确路线是阶段一用原生 API 手写一个最小 Agent理解循环与工具调用本质。阶段二用 LangChain 重写同一个例子感受框架封装了什么。阶段三在实际项目中选择是否引入框架。如果项目工具非常简单手写反而更可控如果工具多、需要多模型兼容框架能节省大量时间。8. 常见问题与排查思路Agent 开发中遇到的报错和问题很多都有固定套路。下面整理几个高频问题。问题现象可能原因排查方式解决方案模型回复没有调用工具工具描述不清晰或 prompt 没有约束打印请求中的 tools 参数查看模型返回内容优化工具 description在 system prompt 中明确必须使用工具调用工具后报错“tool_call_id not found”构造 tool 消息时缺少关联 ID打印 messages 列表检查 tool 消息将 assistant 消息和 tool 消息都追加到同一列表并保证 tool_call_id 一致工具执行结果未生效函数返回值未转成字符串或 JSON检查 execute_tool 返回类型使用json.dumps(result, ensure_asciiFalse)转为字符串上下文超长报错多轮工具调用把历史消息撑爆查看 messages 总量做截断、摘要压缩或改用支持更长上下文的模型请求超时或 429并发太高或需要重试机制查看日志中的状态码增加重试和退避逻辑例如使用tenacity库API 返回 401 或无效 key密钥配置错误或 base_url 不一致检查 .env 和 config.py 的加载路径确认密钥有效确认 base_url 与模型服务商要求一致一个防御性的编程习惯是把每次调用的请求和响应都记录到本地日志文件中。Agent 是多步调用一旦出错如果没有日志你很难判断是哪一步出了问题。# 简易日志调试示例 import logging logging.basicConfig(levellogging.INFO, format%(asctime)s %(message)s) def call_llm_with_log(messages): logging.info(请求消息: %s, messages[-1]) message call_llm(messages) logging.info(模型返回: %s, message) return message这个习惯能帮你省下大量排查时间。9. 最佳实践与工程建议9.1 工具函数要做输入校验Agent 的一大隐患是大模型生成的参数并不可靠它可能会传入负数、超长字符串、不存在的字段。工具函数内部要有防御式校验。加法和拼接问题不大但如果是删除文件、执行命令这类高风险工具必须做白名单校验绝不能直接用模型给的参数执行系统命令。9.2 高风险操作必须加确认机制如果 Agent 拥有写数据库、删除文件、调用线上接口的权限一定要加“人工确认”这一步。最小实现是在执行前打印即将执行的动作并等待用户输入 “y” 确认。生产环境可以引入审批流或者把所有危险工具单独隔离到一个服务器内。9.3 用最小权限原则设计工具集不要一开始就给 Agent 塞进 20 个工具。工具越多模型选错工具的概率越高。建议给每个 Agent 只挂载完成当前任务所需的最少工具。这个原则在很多真实项目里都能看到数据分析 Agent 只有执行 Python 和读写文件的工具不挂搜索文档问答 Agent 只有检索知识库的工具不给它发邮件。9.4 Prompt 与工具描述分开维护在工程化 Agent 项目里system prompt、工具描述、模型参数都应该被当成配置来管理而不是硬编码在业务代码里。推荐结构config/ prompts/ system.md tools/ add_numbers.yaml settings.py这样可以方便产品同学调整提示词不用触碰业务代码和数据库逻辑。9.5 工具执行需要超时和重试大模型返回的“调用参数”里工具名可能不存在参数可能缺失外部工具也可能超时。每个工具的执行都应该设置超时时间并在异常时返回明确的错误字符串给大模型让模型能根据错误调整策略。这比让整个 Agent 崩掉体验好得多。9.6 评估 Agent 是否可靠要回归任务指标Agent 项目做出来后不要只凭“感觉回答不错”来判断效果。建议准备一组测试问题集覆盖正常情况、边界情况和恶意输入每次修改 prompt 或工具定义后都跑一遍回归测试记录成功率与耗时。这样才能持续优化。10. 总结与下一步行动建议现在回头看AI Agent 开发的学习路径其实非常清晰先理解大模型 API 的调用方式再用代码实现一个包含“思考—行动—观察”循环的最小智能体接着扩展工具集和记忆模块最后通过一个完整项目把这些能力整合起来。这篇文章里你已经看到了一个可运行的、不依赖任何重量级框架的最小 Agent 实现。建议你亲手运行一遍再尝试给它新增一个工具比如让 Agent 帮你查询本地目录下的文件名、请求一个公开接口并总结数据。这一步跑通之后你对 Agent 的掌控感会明显不一样。如果你正在规划转型或学习路线从 Python 语言基础到大模型 API再到 Agent 机制和项目实战可以按照文中的主线往前推进。练手阶段多折腾几个小项目比只看教程更有用。下一步你可以选一个方向深入研究如果想要做知识库问答就去学习向量库和 embedding如果想要做流程自动化就重点练习 Function Calling 和复杂工具编排如果目标是进入大模型应用开发岗位就要开始关注评估、可观测性、成本优化这些工程层面的问题。无论选择哪一个核心逻辑是一样的先有一套跑得通的最小系统再逐步加入复杂度。