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 -m venv agent_env

# 激活虚拟环境
# Linux / macOS：
source agent_env/bin/activate

# Windows：
agent_env\Scripts\activate

激活成功后，终端提示符前会出现 (agent_env) 字样，说明虚拟环境已就绪。

2.3 安装依赖库

在激活的虚拟环境中，用 pip 安装以下核心依赖：

pip install langchain 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，写入以下内容：

from langchain_openai import ChatOpenAI
from dotenv import load_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 的“手”。一个好的工具应该功能单一、描述清晰、输入输出简洁。下面我们定义两个实用的工具：一个数学计算器和一个日期查询工具。

from langchain.agents import tool
from datetime import datetime

@tool
def calculator(expression: str) -> str:
    """
    计算一个数学表达式。
    输入的 expression 可以是任意合法的 Python 数学表达式，例如 "3+5*2" 或 "(10-4)/3"。
    返回计算结果字符串。
    """
    try:
        # 演示用 eval，生产环境请使用安全的替代方案（见下文说明）
        result = eval(expression)
        return str(result)
    except Exception as e:
        return f"计算出错：{str(e)}"

@tool
def get_current_date(_: str = "") -> str:
    """
    获取今天的日期。
    不需要任何输入参数。
    返回格式为 YYYY-MM-DD 的日期字符串。
    """
    return datetime.now().strftime("%Y-%m-%d")

# 将所有工具放入列表，后续传入 Agent
tools = [calculator, get_current_date]

这里有两个关键要点：

1. @tool 装饰器：将一个普通的 Python 函数转换为 LangChain 可识别的工具，函数名就是工具名，docstring 就是工具描述，LLM 会根据这些信息判断何时调用哪个工具。
2. docstring 的质量决定 Agent 的智商：Agent 在选择工具时，完全依赖工具的 docstring 来做决策。描述越清晰、越具体，Agent 就越不容易选错工具。请务必认真编写每一个工具的 docstring。

安全提示：上面代码中使用了 Python 内置的 eval() 来执行数学表达式，仅为演示方便。在实际生产环境中，eval() 存在严重的安全隐患——如果用户传入恶意字符串，可能导致任意代码执行。更安全的替代方案有：

• ast.literal_eval()：仅支持字面量表达式（如数字、列表、字典），安全性高
• numexpr 库：专为数值计算设计，速度快且安全
• 自己写一个简单的表达式解析器

4. 组装 Agent：让大脑连上手

有了工具之后，下一步就是把 LLM（大脑）和 tools（手）组合成一个完整的 Agent。

from langchain_openai import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 初始化大语言模型
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)

# 创建 Agent
agent = 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）**组件。

from langchain.memory import ConversationBufferMemory

# 创建记忆组件
memory = ConversationBufferMemory(
    memory_key="chat_history",  # 记忆内容的存储键名
    return_messages=True        # 以消息对象形式返回历史记录
)

# 使用支持对话的 Agent 类型
agent_with_memory = initialize_agent(
    tools,
    llm,
    agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,  # 对话式 ReAct
    memory=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 就能自动学会调用它。

下面是一个文件读取工具的示例：

@tool
def read_file(file_path: str) -> str:
    """
    读取指定路径的文本文件内容。
    输入的 file_path 应是一个有效的文件路径字符串。
    返回文件中的全部文本内容。
    """
    try:
        with open(file_path, "r", encoding="utf-8") as f:
            return f.read()
    except FileNotFoundError:
        return f"错误：文件 '{file_path}' 不存在。"
    except Exception as e:
        return f"读取文件时出错：{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 为例：

pip install langchain-zhipuai

from langchain_zhipuai import ChatZhipuAI

llm = ChatZhipuAI(model="glm-4-flash", temperature=0)

Agent 和工具的定义部分完全不需要修改，做到了模型层面的即插即用。

9. 总结与下一步学习路线

本文回顾

通过这篇教程，你从零开始完成了以下里程碑：

1. 理解了 AI Agent 的核心概念和 ReAct 工作模式
2. 搭建了完整的 Python 开发环境并验证通过
3. 用 @tool 装饰器定义了两个实用工具
4. 使用 initialize_agent 组装了第一个可运行的 Agent
5. 成功执行了单步和复合多步任务
6. 为 Agent 添加了记忆能力，支持多轮对话
7. 学习了如何自定义更多工具以及排查常见问题

下一步学习建议

• 深入 Agent 架构：学习 Plan-and-Execute、AutoGPT 等更复杂的 Agent 范式。
• 构建完整应用：将 Agent 接入你的业务 API，打造企业级内部助手。
• 打造 UI 界面：用 Gradio、Chainlit 或 Streamlit 为你的 Agent 搭建一个可视化操作界面。

整体架构速览

现在，你已经掌握了搭建 AI Agent 的完整技能。打开你的 IDE，从第一行代码开始，创造一个属于你自己的智能体吧！