手把手教你从0到1搭建一个AI Agent(智能体)
1. 什么是AI Agent？
AI Agent（智能体）是一种能够感知环境、自主决策并使用工具来完成复杂任务的智能程序。与传统的聊天机器人只会“回答问题”不同，Agent 不仅能“思考”，还能“动手做事”——比如查询天气、计算数学表达式、操作数据库，甚至自动发送邮件。
如果把大语言模型（LLM）比作一个聪明的大脑，那么 Agent 就是这个大脑配上双手（工具）和一套行动策略之后的完整个体。它能理解你的需求、制定行动计划，然后调用合适的工具去执行。
一个典型的 AI Agent 由以下核心组件构成：
- 大语言模型（LLM）：负责推理、计划与生成文本的大脑。
- 工具（Tools）：执行具体操作的函数，如计算器、搜索引擎、数据库查询接口等。
- Agent 类型：决策策略，定义了 Agent 如何思考与行动，常见的有 ReAct、OpenAI Functions、Plan-and-Execute 等。
ReAct 模式是目前最经典、最适合入门学习的 Agent 架构。它的核心思想是将**推理（Reasoning）与行动（Acting）**交替进行：
Thought（思考） → Action（选择工具） → Action Input（工具入参） → Observation（观察结果） → 重复直到找到 Final Answer这种模式让模型的每一步决策都有迹可循，便于调试，也更能应对复杂任务。本文将以 Python + LangChain 为载体，采用 ReAct 模式，手把手教你搭建一个能听懂指令、会调用工具完成任务的 AI Agent。
2. 环境准备：从零搭建开发环境
在开始写代码之前，我们先把开发环境准备好。整个过程只需几分钟。
2.1 安装 Python（3.9+）
确保你的电脑上已安装 Python 3.9 或更高版本。在终端中运行以下命令来检查：
python--version如果尚未安装，请前往 python.org 下载并安装。安装时勾选“Add Python to PATH”选项，方便后续在终端中直接使用python命令。
2.2 创建虚拟环境（推荐）
虚拟环境可以隔离项目依赖，避免不同项目之间的包版本冲突。
# 创建虚拟环境python-mvenv agent_env# 激活虚拟环境# Linux / macOS：sourceagent_env/bin/activate# Windows：agent_env\Scripts\activate激活成功后，终端提示符前会出现(agent_env)字样，说明虚拟环境已就绪。
2.3 安装依赖库
在激活的虚拟环境中，用 pip 安装以下核心依赖：
pipinstalllangchain langchain-openai python-dotenv各包的作用如下：
| 包名 | 作用 |
|---|---|
langchain | Agent 框架核心库，提供工具定义、Agent 构造器等完整能力 |
langchain-openai | OpenAI 模型集成，用于调用 GPT 系列模型 |
python-dotenv | 从.env文件中安全加载 API 密钥等敏感信息 |
如果你打算用国产大模型（如智谱 GLM、百度文心、阿里通义），只需安装对应集成包（如langchain-zhipuai）并替换后续代码中的 LLM 对象即可，整体开发流程完全一致，无需修改 Agent 和工具的构造代码。
2.4 配置 API 密钥
在项目根目录（即你准备存放代码的文件夹）下创建一个.env文件，内容如下：
OPENAI_API_KEY=sk-your-api-key-here请将sk-your-api-key-here替换为你自己的 OpenAI API Key。如果你还没有密钥，可以前往 OpenAI Platform 注册并获取。
安全提醒：
.env文件应加入.gitignore，切勿上传至公开的代码仓库，以免泄露密钥。
2.5 验证安装
在项目目录下新建一个文件，命名为test_env.py，写入以下内容：
fromlangchain_openaiimportChatOpenAIfromdotenvimportload_dotenv load_dotenv()# 加载 .env 文件中的环境变量llm=ChatOpenAI(model="gpt-3.5-turbo",temperature=0)response=llm.invoke("你好，请回复一句话确认你已就绪。")print(response.content)在终端中运行：
python test_env.py如果一切正常，你会看到模型返回的确认信息，说明环境配置已完全就绪。如果报错，请检查.env文件路径是否正确、API Key 是否有效以及网络能否正常访问 OpenAI 接口。
3. 设计并实现你的第一批工具
工具是 Agent 的“手”。一个好的工具应该功能单一、描述清晰、输入输出简洁。下面我们定义两个实用的工具：一个数学计算器和一个日期查询工具。
fromlangchain.agentsimporttoolfromdatetimeimportdatetime@tooldefcalculator(expression:str)->str:""" 计算一个数学表达式。 输入的 expression 可以是任意合法的 Python 数学表达式，例如 "3+5*2" 或 "(10-4)/3"。 返回计算结果字符串。 """try:# 演示用 eval，生产环境请使用安全的替代方案（见下文说明）result=eval(expression)returnstr(result)exceptExceptionase:returnf"计算出错：{str(e)}"@tooldefget_current_date(_:str="")->str:""" 获取今天的日期。 不需要任何输入参数。 返回格式为 YYYY-MM-DD 的日期字符串。 """returndatetime.now().strftime("%Y-%m-%d")# 将所有工具放入列表，后续传入 Agenttools=[calculator,get_current_date]这里有两个关键要点：
@tool装饰器：将一个普通的 Python 函数转换为 LangChain 可识别的工具，函数名就是工具名，docstring 就是工具描述，LLM 会根据这些信息判断何时调用哪个工具。- docstring 的质量决定 Agent 的智商：Agent 在选择工具时，完全依赖工具的 docstring 来做决策。描述越清晰、越具体，Agent 就越不容易选错工具。请务必认真编写每一个工具的 docstring。
安全提示：上面代码中使用了 Python 内置的
eval()来执行数学表达式，仅为演示方便。在实际生产环境中，eval()存在严重的安全隐患——如果用户传入恶意字符串，可能导致任意代码执行。更安全的替代方案有：
ast.literal_eval()：仅支持字面量表达式（如数字、列表、字典），安全性高numexpr库：专为数值计算设计，速度快且安全- 自己写一个简单的表达式解析器
4. 组装 Agent：让大脑连上手
有了工具之后，下一步就是把 LLM（大脑）和 tools（手）组合成一个完整的 Agent。
fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportinitialize_agent,AgentTypefromdotenvimportload_dotenv# 加载环境变量load_dotenv()# 初始化大语言模型llm=ChatOpenAI(model="gpt-3.5-turbo",temperature=0)# 创建 Agentagent=initialize_agent(tools,# 我们的工具列表llm,# 大语言模型agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,# 使用 ReAct 模式verbose=True,# 打印详细思考过程handle_parsing_errors=True,# 解析出错时自动重试max_iterations=5# 最多执行5步，防止死循环)# 执行第一个任务：询问日期response=agent.invoke("今天是几号？")print(response["output"])运行这段代码后，你会在终端中看到类似这样的输出：
> Entering new AgentExecutor chain... Thought: 用户想知道今天是几号，我需要调用 get_current_date 工具。 Action: get_current_date Action Input: Observation: 2026-06-23 Thought: 我已经获得了今天的日期，可以给出最终答案了。 Final Answer: 今天是 2026 年 6 月 23 日。 > Finished chain. 今天是 2026 年 6 月 23 日。几个关键参数说明：
| 参数 | 作用 |
|---|---|
verbose=True | 打印 Thought → Action → Observation 的完整链条，强烈推荐学习阶段开启，便于理解 Agent 的决策过程 |
handle_parsing_errors=True | 当模型输出格式不符合预期时自动重试，能显著提高稳定性 |
max_iterations=5 | 防止 Agent 陷入无限循环，达到最大步数后会强制停止 |
temperature=0 | 让模型输出更确定，适合逻辑任务；如需更多创意可调高（0~2） |
5. 实战：让 Agent 完成复合任务
现在来测试一个需要多步骤推理的复杂任务——先查日期，再做计算。
response=agent.invoke("先告诉我今天的日期，然后帮我算一下 365 除以 7 的整数部分是多少")print(response["output"])Agent 的完整思考过程如下：
> Entering new AgentExecutor chain... Thought: 用户有两个请求：1. 获取今天的日期 2. 计算 365 除以 7 的整数部分 我应该先获取日期，再进行数学计算。 Action: get_current_date Action Input: Observation: 2026-06-23 Thought: 日期已获得。现在需要计算 365//7 的整数部分。 Action: calculator Action Input: 365//7 Observation: 52 Thought: 我已经得到了所有需要的信息，可以给出最终答案。 Final Answer: 今天是 2026 年 6 月 23 日。365 除以 7 的整数部分是 52。 > Finished chain.从这个例子可以清楚看到 ReAct 模式的精髓：Agent 先分析用户的复合需求，然后制定行动计划，按步骤调用不同的工具，最后将所有信息整合成一个完整的回答。整个过程透明、可控、易于调试。
你可以继续尝试更复杂的任务，比如：
"100 元买 3 个苹果和 2 个橘子，苹果每个 15 元，橘子每个 12 元，找零多少？再告诉我今天是星期几。""算一下 2 的 10 次方，然后告诉我今天日期。"
6. 进阶：让 Agent 记住你们的对话
单轮问答适合一次性任务，但在实际应用中，用户往往希望进行多轮对话，Agent 能记住之前说过的话。这时就需要为 Agent 添加**记忆（Memory）**组件。
fromlangchain.memoryimportConversationBufferMemory# 创建记忆组件memory=ConversationBufferMemory(memory_key="chat_history",# 记忆内容的存储键名return_messages=True# 以消息对象形式返回历史记录)# 使用支持对话的 Agent 类型agent_with_memory=initialize_agent(tools,llm,agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,# 对话式 ReActmemory=memory,verbose=True,handle_parsing_errors=True,max_iterations=5)# 连续对话测试agent_with_memory.invoke("今天是几号？")agent_with_memory.invoke("那明天呢？")# Agent 能结合上下文推算出明天日期ConversationBufferMemory会将每一轮对话历史保存在内存中，并在后续的每次调用时把历史记录注入到 prompt 中，让模型能够“回忆”之前的交互内容。
常见的记忆策略：
| 记忆类型 | 适用场景 |
|---|---|
ConversationBufferMemory | 对话轮次少，需要完整历史记忆 |
ConversationBufferWindowMemory | 只保留最近 k 轮对话，控制 token 消耗 |
ConversationSummaryMemory | 长对话场景，用摘要代替完整历史 |
7. 自定义更多工具，扩展 Agent 能力
Agent 的强大之处在于你可以无限扩展它的能力——只要你把功能封装成工具，Agent 就能自动学会调用它。
下面是一个文件读取工具的示例：
@tooldefread_file(file_path:str)->str:""" 读取指定路径的文本文件内容。 输入的 file_path 应是一个有效的文件路径字符串。 返回文件中的全部文本内容。 """try:withopen(file_path,"r",encoding="utf-8")asf:returnf.read()exceptFileNotFoundError:returnf"错误：文件 '{file_path}' 不存在。"exceptExceptionase:returnf"读取文件时出错：{str(e)}"# 将新工具加入工具列表tools.append(read_file)更多可扩展的工具方向：
- 搜索引擎工具：集成 SerpAPI 或 Tavily，让 Agent 实时查询最新信息
- 数据库查询工具：连接 MySQL、PostgreSQL，让 Agent 能执行 SQL 查询
- 邮件发送工具：调用 SMTP 服务，让 Agent 能代发邮件
- HTTP 请求工具：封装
requests库，让 Agent 能调用任意 REST API - 代码执行工具：在沙箱中运行 Python 代码片段（需要严格的安全隔离）
8. 常见问题排查指南
8.1 Agent 总是选择错误的工具？
- 检查 docstring：工具描述是否准确、无歧义？LLM 的选择完全基于 docstring，这是最常见的问题根源。
- 精简工具数量：工具太多会让模型选择困难，建议一期只给 3~5 个最核心的工具。
- 启用自动重试：确保
handle_parsing_errors=True已打开。
8.2 Agent 陷入死循环或迟迟不结束？
- 降低 max_iterations：调小最大步数限制（如 3~5 步）。
- 开启 verbose：观察是哪一步触发了循环，针对性地优化工具或 prompt。
- 调整 temperature：将
temperature设为 0 可以减少模型的随机行为。
8.3 网络错误或 API 调用失败？
- 检查
.env中的 API Key 是否正确，是否已过期。 - 确认网络能正常访问
api.openai.com。 - 如在国内使用，可考虑配置代理，或改用国产大模型 API。
8.4 如何改用国产大模型？
只需替换 LLM 的初始化代码。以智谱 GLM 为例：
pipinstalllangchain-zhipuaifromlangchain_zhipuaiimportChatZhipuAI llm=ChatZhipuAI(model="glm-4-flash",temperature=0)Agent 和工具的定义部分完全不需要修改，做到了模型层面的即插即用。
9. 总结与下一步学习路线
本文回顾
通过这篇教程，你从零开始完成了以下里程碑：
- 理解了 AI Agent 的核心概念和 ReAct 工作模式
- 搭建了完整的 Python 开发环境并验证通过
- 用
@tool装饰器定义了两个实用工具 - 使用
initialize_agent组装了第一个可运行的 Agent - 成功执行了单步和复合多步任务
- 为 Agent 添加了记忆能力，支持多轮对话
- 学习了如何自定义更多工具以及排查常见问题
下一步学习建议
- 深入 Agent 架构：学习 Plan-and-Execute、AutoGPT 等更复杂的 Agent 范式。
- 构建完整应用：将 Agent 接入你的业务 API，打造企业级内部助手。
- 打造 UI 界面：用 Gradio、Chainlit 或 Streamlit 为你的 Agent 搭建一个可视化操作界面。
整体架构速览
现在，你已经掌握了搭建 AI Agent 的完整技能。打开你的 IDE，从第一行代码开始，创造一个属于你自己的智能体吧！