手把手教你从0到1搭建一个AI Agent(智能体)

1. 什么是AI AgentAI 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 安装 Python3.9确保你的电脑上已安装 Python 3.9 或更高版本。在终端中运行以下命令来检查python--version如果尚未安装请前往 python.org 下载并安装。安装时勾选“Add Python to PATH”选项方便后续在终端中直接使用python命令。2.2 创建虚拟环境推荐虚拟环境可以隔离项目依赖避免不同项目之间的包版本冲突。# 创建虚拟环境python-mvenv agent_env# 激活虚拟环境# Linux / macOSsourceagent_env/bin/activate# Windowsagent_env\Scripts\activate激活成功后终端提示符前会出现(agent_env)字样说明虚拟环境已就绪。2.3 安装依赖库在激活的虚拟环境中用 pip 安装以下核心依赖pipinstalllangchain langchain-openai python-dotenv各包的作用如下包名作用langchainAgent 框架核心库提供工具定义、Agent 构造器等完整能力langchain-openaiOpenAI 模型集成用于调用 GPT 系列模型python-dotenv从.env文件中安全加载 API 密钥等敏感信息如果你打算用国产大模型如智谱 GLM、百度文心、阿里通义只需安装对应集成包如langchain-zhipuai并替换后续代码中的 LLM 对象即可整体开发流程完全一致无需修改 Agent 和工具的构造代码。2.4 配置 API 密钥在项目根目录即你准备存放代码的文件夹下创建一个.env文件内容如下OPENAI_API_KEYsk-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 文件中的环境变量llmChatOpenAI(modelgpt-3.5-turbo,temperature0)responsellm.invoke(你好请回复一句话确认你已就绪。)print(response.content)在终端中运行python test_env.py如果一切正常你会看到模型返回的确认信息说明环境配置已完全就绪。如果报错请检查.env文件路径是否正确、API Key 是否有效以及网络能否正常访问 OpenAI 接口。3. 设计并实现你的第一批工具工具是 Agent 的“手”。一个好的工具应该功能单一、描述清晰、输入输出简洁。下面我们定义两个实用的工具一个数学计算器和一个日期查询工具。fromlangchain.agentsimporttoolfromdatetimeimportdatetimetooldefcalculator(expression:str)-str: 计算一个数学表达式。 输入的 expression 可以是任意合法的 Python 数学表达式例如 35*2 或 (10-4)/3。 返回计算结果字符串。 try:# 演示用 eval生产环境请使用安全的替代方案见下文说明resulteval(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()# 初始化大语言模型llmChatOpenAI(modelgpt-3.5-turbo,temperature0)# 创建 Agentagentinitialize_agent(tools,# 我们的工具列表llm,# 大语言模型agentAgentType.ZERO_SHOT_REACT_DESCRIPTION,# 使用 ReAct 模式verboseTrue,# 打印详细思考过程handle_parsing_errorsTrue,# 解析出错时自动重试max_iterations5# 最多执行5步防止死循环)# 执行第一个任务询问日期responseagent.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 日。几个关键参数说明参数作用verboseTrue打印 Thought → Action → Observation 的完整链条强烈推荐学习阶段开启便于理解 Agent 的决策过程handle_parsing_errorsTrue当模型输出格式不符合预期时自动重试能显著提高稳定性max_iterations5防止 Agent 陷入无限循环达到最大步数后会强制停止temperature0让模型输出更确定适合逻辑任务如需更多创意可调高0~25. 实战让 Agent 完成复合任务现在来测试一个需要多步骤推理的复杂任务——先查日期再做计算。responseagent.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# 创建记忆组件memoryConversationBufferMemory(memory_keychat_history,# 记忆内容的存储键名return_messagesTrue# 以消息对象形式返回历史记录)# 使用支持对话的 Agent 类型agent_with_memoryinitialize_agent(tools,llm,agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION,# 对话式 ReActmemorymemory,verboseTrue,handle_parsing_errorsTrue,max_iterations5)# 连续对话测试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,encodingutf-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_errorsTrue已打开。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 llmChatZhipuAI(modelglm-4-flash,temperature0)Agent 和工具的定义部分完全不需要修改做到了模型层面的即插即用。9. 总结与下一步学习路线本文回顾通过这篇教程你从零开始完成了以下里程碑理解了 AI Agent 的核心概念和 ReAct 工作模式搭建了完整的 Python 开发环境并验证通过用tool装饰器定义了两个实用工具使用initialize_agent组装了第一个可运行的 Agent成功执行了单步和复合多步任务为 Agent 添加了记忆能力支持多轮对话学习了如何自定义更多工具以及排查常见问题下一步学习建议深入 Agent 架构学习 Plan-and-Execute、AutoGPT 等更复杂的 Agent 范式。构建完整应用将 Agent 接入你的业务 API打造企业级内部助手。打造 UI 界面用 Gradio、Chainlit 或 Streamlit 为你的 Agent 搭建一个可视化操作界面。整体架构速览制定计划任务完成用户输入任务Agent 大脑LLM选择工具工具1计算器工具2日期查询工具3文件读取返回观察结果输出最终答案现在你已经掌握了搭建 AI Agent 的完整技能。打开你的 IDE从第一行代码开始创造一个属于你自己的智能体吧