手把手教你从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 -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

各包的作用如下：

如果你打算用国产大模型（如智谱 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]

这里有两个关键要点：

安全提示：上面代码中使用了 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 日。

几个关键参数说明：

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 中，让模型能够“回忆”之前的交互内容。

常见的记忆策略：

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. 总结与下一步学习路线

本文回顾

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

下一步学习建议

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

整体架构速览

#mermaid-svg-n2FB6TePsjUxTBCc{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-n2FB6TePsjUxTBCc .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-n2FB6TePsjUxTBCc .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-n2FB6TePsjUxTBCc .error-icon{fill:#552222;}#mermaid-svg-n2FB6TePsjUxTBCc .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-n2FB6TePsjUxTBCc .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-n2FB6TePsjUxTBCc .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-n2FB6TePsjUxTBCc .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-n2FB6TePsjUxTBCc .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-n2FB6TePsjUxTBCc .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-n2FB6TePsjUxTBCc .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-n2FB6TePsjUxTBCc .marker{fill:#333333;stroke:#333333;}#mermaid-svg-n2FB6TePsjUxTBCc .marker.cross{stroke:#333333;}#mermaid-svg-n2FB6TePsjUxTBCc svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-n2FB6TePsjUxTBCc p{margin:0;}#mermaid-svg-n2FB6TePsjUxTBCc .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-n2FB6TePsjUxTBCc .cluster-label text{fill:#333;}#mermaid-svg-n2FB6TePsjUxTBCc .cluster-label span{color:#333;}#mermaid-svg-n2FB6TePsjUxTBCc .cluster-label span p{background-color:transparent;}#mermaid-svg-n2FB6TePsjUxTBCc .label text,#mermaid-svg-n2FB6TePsjUxTBCc span{fill:#333;color:#333;}#mermaid-svg-n2FB6TePsjUxTBCc .node rect,#mermaid-svg-n2FB6TePsjUxTBCc .node circle,#mermaid-svg-n2FB6TePsjUxTBCc .node ellipse,#mermaid-svg-n2FB6TePsjUxTBCc .node polygon,#mermaid-svg-n2FB6TePsjUxTBCc .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-n2FB6TePsjUxTBCc .rough-node .label text,#mermaid-svg-n2FB6TePsjUxTBCc .node .label text,#mermaid-svg-n2FB6TePsjUxTBCc .image-shape .label,#mermaid-svg-n2FB6TePsjUxTBCc .icon-shape .label{text-anchor:middle;}#mermaid-svg-n2FB6TePsjUxTBCc .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-n2FB6TePsjUxTBCc .rough-node .label,#mermaid-svg-n2FB6TePsjUxTBCc .node .label,#mermaid-svg-n2FB6TePsjUxTBCc .image-shape .label,#mermaid-svg-n2FB6TePsjUxTBCc .icon-shape .label{text-align:center;}#mermaid-svg-n2FB6TePsjUxTBCc .node.clickable{cursor:pointer;}#mermaid-svg-n2FB6TePsjUxTBCc .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-n2FB6TePsjUxTBCc .arrowheadPath{fill:#333333;}#mermaid-svg-n2FB6TePsjUxTBCc .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-n2FB6TePsjUxTBCc .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-n2FB6TePsjUxTBCc .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-n2FB6TePsjUxTBCc .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-n2FB6TePsjUxTBCc .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-n2FB6TePsjUxTBCc .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-n2FB6TePsjUxTBCc .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-n2FB6TePsjUxTBCc .cluster text{fill:#333;}#mermaid-svg-n2FB6TePsjUxTBCc .cluster span{color:#333;}#mermaid-svg-n2FB6TePsjUxTBCc div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-n2FB6TePsjUxTBCc .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-n2FB6TePsjUxTBCc rect.text{fill:none;stroke-width:0;}#mermaid-svg-n2FB6TePsjUxTBCc .icon-shape,#mermaid-svg-n2FB6TePsjUxTBCc .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-n2FB6TePsjUxTBCc .icon-shape p,#mermaid-svg-n2FB6TePsjUxTBCc .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-n2FB6TePsjUxTBCc .icon-shape .label rect,#mermaid-svg-n2FB6TePsjUxTBCc .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-n2FB6TePsjUxTBCc .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-n2FB6TePsjUxTBCc .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-n2FB6TePsjUxTBCc :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

制定计划

任务完成

用户输入任务

Agent 大脑（LLM）

选择工具

工具1：计算器

工具2：日期查询

工具3：文件读取

返回观察结果

输出最终答案

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