AI Agent开发实战：从零构建具备自主规划与工具调用能力的智能体

30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度最近在尝试将大模型应用到实际业务中时发现单纯调用API生成文本已经无法满足复杂任务的需求。比如想让AI自动分析数据、生成报告并发送邮件或者根据用户问题自动查询知识库并给出精准答案这些都需要AI具备自主规划、使用工具和执行多步骤任务的能力。这正是AI Agent智能体技术要解决的核心问题。然而网上关于Agent开发的资料要么过于零散要么停留在理论层面缺乏一套从环境搭建到项目落地的完整实操指南。本文旨在填补这一空白为你提供一份系统化的AI Agent开发实战教程。无论你是刚接触大模型的初学者还是希望提升智能体开发能力的进阶开发者都能从中获益。我们将从最基础的概念讲起逐步深入到框架使用、工具集成、任务编排等核心环节并提供大量可运行的代码示例。学完本教程你将能够独立构建具备自主行动能力的AI Agent应用。1. AI Agent 核心概念与价值在深入代码之前我们必须先理解AI Agent究竟是什么以及它为何能成为大模型应用的下一个爆发点。1.1 什么是AI Agent简单来说AI Agent是一个能够感知环境、自主决策并执行行动以实现特定目标的智能实体。你可以把它想象成一个“数字员工”。与传统的单次问答式大模型不同AI Agent具备几个关键特征自主性Autonomy在给定目标后能够自行规划步骤无需人类步步指导。工具使用Tool Use可以调用外部工具如搜索引擎、计算器、数据库、API等来扩展自身能力边界。记忆与状态Memory State能够记住之前的交互历史、任务上下文和自身状态从而进行连贯的多轮任务处理。反应与规划Reactivity Planning既能对环境变化做出即时反应也能为复杂目标制定长期规划。1.2 为什么需要AI Agent大模型本身是强大的“大脑”但它存在局限知识可能过时、无法直接操作外部系统、计算容易出错、处理长逻辑链困难。AI Agent通过赋予大模型“手脚”工具和“记事本”记忆使其能够解决复杂问题将一个大问题拆解为多个可执行的小步骤。连接数字世界通过API与软件、硬件进行交互真正“做事”。持续学习与适应从历史交互中积累经验优化未来的决策。1.3 典型应用场景自动化客服与销售自动理解用户复杂咨询查询知识库、生成方案、甚至创建工单。个人智能助理管理日程、总结邮件、自动订餐、生成周报。数据分析与报告自动获取数据、清洗、分析并生成可视化报告。研发辅助根据需求自动搜索技术方案、生成代码片段、运行测试。游戏与模拟创建具有自主行为的非玩家角色NPC。理解了Agent的价值接下来我们就要进入实战环节。工欲善其事必先利其器首先来搭建开发环境。2. 环境准备与核心工具栈AI Agent开发涉及多个层次从底层的大模型接入到上层的Agent框架。我们选择一套稳定、流行且易于上手的工具栈。2.1 基础环境操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04)。本文示例在 macOS/Linux 环境下演示Windows用户请注意命令差异建议使用WSL2。编程语言Python 3.8。Agent生态目前主要由Python驱动。包管理工具pip(Python自带) 或conda(推荐用于管理复杂环境)。2.2 核心库与框架我们将主要使用LangChain和LangGraph这两个框架。LangChain是当前最主流的AI应用开发框架提供了构建Agent所需的几乎所有组件。LangGraph是LangChain中用于构建有状态、多环节工作流的库非常适合构建复杂的Agent。首先创建一个新的虚拟环境并安装核心依赖# 创建并激活虚拟环境 (以 conda 为例) conda create -n ai-agent python3.10 conda activate ai-agent # 安装 LangChain 及其相关组件 pip install langchain langchain-community langchain-core # 安装 LangGraph 用于构建工作流 pip install langgraph # 安装 OpenAI 库用于调用GPT模型 pip install openai # 安装用于网页内容提取的工具库 pip install beautifulsoup4 requests # 安装环境变量管理库推荐 pip install python-dotenv版本说明AI领域库更新迅速以上版本为撰写时的稳定版本。实际开发中请关注官方文档使用pip install -U命令更新。核心思路是安装langchain,langgraph, 以及对应大模型如openai和工具如requests的库。2.3 大模型接入准备你需要一个大型语言模型的API密钥。本文以OpenAI的GPT系列为例其他模型如国内大模型、开源模型接入方式类似。访问OpenAI平台注册并获取API Key。在项目根目录创建.env文件用于安全存储密钥# .env 文件 OPENAI_API_KEY你的sk-xxx密钥在代码中通过python-dotenv加载环境变量。2.4 项目结构初始化建议采用清晰的项目结构ai-agent-project/ ├── .env # 环境变量切勿提交至Git ├── requirements.txt # 项目依赖 ├── src/ # 源代码 │ ├── agents/ # Agent定义 │ ├── tools/ # 自定义工具 │ ├── memory/ # 记忆模块 │ └── main.py # 主入口 ├── notebooks/ # Jupyter实验笔记 └── README.md使用以下命令生成requirements.txtpip freeze requirements.txt环境搭建完毕我们已经具备了开发Agent的所有基础条件。接下来让我们深入LangChain框架理解构建Agent的核心组件。3. LangChain核心组件拆解LangChain像一副乐高积木提供了丰富的组件。要搭建Agent我们需要先认识其中最重要的几块积木模型Models、提示词Prompts、链Chains、工具Tools和记忆Memory。3.1 模型LLMs ChatModels这是Agent的“大脑”。LangChain统一了不同厂商模型的调用接口。# src/main.py from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os load_dotenv() # 加载 .env 中的环境变量 # 初始化Chat模型推荐使用Chat模型更适合对话 llm ChatOpenAI( modelgpt-3.5-turbo, # 或 gpt-4, gpt-4-turbo temperature0.7, # 创造性0-1之间越高越随机 api_keyos.getenv(OPENAI_API_KEY) ) # 进行一次简单的对话 from langchain_core.messages import HumanMessage message [HumanMessage(content你好请介绍一下你自己。)] response llm.invoke(message) print(response.content)3.2 提示词Prompts与提示模板提示词是引导模型行为的指令。使用模板可以动态生成提示词。from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 定义一个包含对话历史和用户问题的提示模板 prompt_template ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的AI助手名字叫‘小智’。), MessagesPlaceholder(variable_namechat_history), # 历史消息占位符 (human, {user_input}), ]) # 使用模板 from langchain_core.messages import AIMessage, HumanMessage chat_history [ HumanMessage(content今天的天气怎么样), AIMessage(content我是一个AI无法获取实时天气哦。) ] current_input 那你能做什么 formatted_prompt prompt_template.format_messages( chat_historychat_history, user_inputcurrent_input ) response llm.invoke(formatted_prompt) print(response.content)3.3 链Chains链将多个组件模型、提示词、工具等按顺序组合起来完成一个特定任务。这是构建复杂逻辑的基础。from langchain.chains import LLMChain # 创建一个简单的链提示词 模型 chain LLMChain(llmllm, promptprompt_template) # 运行链 result chain.invoke({ chat_history: chat_history, user_input: 用一句话总结AI Agent是什么。 }) print(result[text])3.4 工具Tools工具是Agent的“手脚”。它可以是一个函数、一个API调用或任何可执行的操作。创建自定义工具from langchain.tools import tool from datetime import datetime tool def get_current_time(format: str %Y-%m-%d %H:%M:%S) - str: 获取当前的日期和时间。可以指定格式默认是‘年-月-日 时:分:秒’。 now datetime.now() return now.strftime(format) # 使用工具 print(get_current_time.invoke({})) # 默认格式 print(get_current_time.invoke({format: %H:%M})) # 只输出时分使用内置工具from langchain_community.tools import DuckDuckGoSearchRun search_tool DuckDuckGoSearchRun() result search_tool.invoke(LangChain最新版本是什么) print(result[:500]) # 打印前500个字符3.5 记忆Memory记忆使Agent能够记住之前的对话或事件。LangChain提供了多种记忆后端。from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory( memory_keychat_history, return_messagesTrue # 返回Message对象而非字符串 ) # 保存上下文 memory.chat_memory.add_user_message(我喜欢编程。) memory.chat_memory.add_ai_message(太棒了编程很有趣。) # 加载上下文 loaded_memory memory.load_memory_variables({}) print(loaded_memory)掌握了这些核心组件我们就可以像搭积木一样将它们组合成一个初具雏形的智能体。接下来我们将创建第一个能使用工具的Agent。4. 实战构建你的第一个AI Agent现在我们将综合运用前面所学的组件构建一个能够使用“获取当前时间”工具的简单Agent。4.1 定义工具列表首先明确Agent可以使用的工具。# src/tools/custom_tools.py from langchain.tools import tool from datetime import datetime import math tool def get_current_time() - str: 当用户询问当前时间、日期或今天星期几时使用此工具。 now datetime.now() return f当前时间是{now.strftime(%Y-%m-%d %H:%M:%S)}星期{[一,二,三,四,五,六,日][now.weekday()]}。 tool def calculate(expression: str) - str: 计算一个数学表达式。例如‘3 5 * 2’ 或 ‘sqrt(16)’。支持加减乘除(-*/)和乘方(**)。 # 警告使用eval存在安全风险此处仅用于演示。生产环境应使用更安全的解析器如ast.literal_eval或数学库。 try: # 为安全起见限制可用的内置函数 allowed_names {sqrt: math.sqrt, pow: pow, abs: abs} result eval(expression, {__builtins__: {}}, {**allowed_names, **math.__dict__}) return f计算结果{expression} {result} except Exception as e: return f计算错误无法解析表达式 ‘{expression}’。请确保它是有效的数学表达式。错误详情{e} # 将工具放入列表 tools [get_current_time, calculate]4.2 创建Agent执行器我们将使用LangChain的create_react_agent来创建一个基于ReActReasoning Acting范式的Agent。ReAct是让Agent在思考生成推理轨迹和行动调用工具之间交替进行的经典模式。# src/agents/basic_agent.py from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_core.prompts import PromptTemplate from src.tools.custom_tools import tools # 导入我们定义的工具 from src.main import llm # 导入之前初始化的模型 # 1. 获取一个预设的ReAct提示词模板 # LangChain Hub 是一个提示词仓库我们可以从中拉取优秀的模板 react_prompt hub.pull(hwchase17/react) # 2. 使用工具、模型和提示词创建Agent agent create_react_agent(llm, tools, react_prompt) # 3. 创建Agent执行器它负责运行Agent并处理工具调用 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设置为True可以看到Agent的思考过程非常有用 handle_parsing_errorsTrue # 优雅地处理解析错误 )4.3 运行并测试Agent现在让我们来测试这个Agent。# 测试查询1需要使用工具 print( 测试1询问时间 ) result1 agent_executor.invoke({input: 现在几点了}) print(f最终答案{result1[output]}\n) # 测试查询2需要计算 print( 测试2数学计算 ) result2 agent_executor.invoke({input: 请计算一下15的平方加上20除以4等于多少}) print(f最终答案{result2[output]}\n) # 测试查询3无需工具直接回答 print( 测试3普通问答 ) result3 agent_executor.invoke({input: AI是什么意思}) print(f最终答案{result3[output]}\n)运行上述代码确保已设置OPENAI_API_KEY你将看到类似以下输出 测试1询问时间 Entering new AgentExecutor chain... 我需要使用获取当前时间的工具来回答这个问题。 Action: get_current_time Action Input: {} Observation: 当前时间是2024-05-27 14:30:15星期三。 Thought:我已经获得了当前时间可以回答用户了。 Final Answer: 当前时间是2024年5月27日 14:30:15星期三。 Finished chain. 最终答案当前时间是2024年5月27日 14:30:15星期三。通过verboseTrue我们清晰地看到了Agent的思考链Thought、行动Action和观察Observation。这就是ReAct模式在运行。恭喜你已经成功创建了一个能够自主选择并使用工具的AI Agent。但这只是一个开始。现实中的任务往往更复杂需要多个步骤、状态管理和协作。接下来我们将使用更强大的LangGraph来构建支持多步骤工作流的智能体。5. 进阶使用LangGraph构建多步骤工作流Agent当任务需要一系列有序或条件判断步骤时简单的ReAct Agent可能不够灵活。LangGraph允许我们将Agent的工作流定义为一个有向图节点代表步骤如调用LLM、执行工具边代表步骤之间的流转条件。5.1 设计一个数据分析Agent工作流假设我们要构建一个“数据分析助手”Agent其工作流程如下理解需求解析用户请求判断是否需要获取数据。获取数据如果需要调用工具如搜索、查询数据库获取数据。分析数据对获取的数据进行分析计算、总结、找规律。生成报告将分析结果格式化为用户友好的报告。循环判断根据分析结果决定是否需要进一步深入分析或结束。5.2 定义图状态State首先我们需要定义一个状态State来在整个工作流中传递信息。我们使用TypedDict来定义。# src/agents/graph_state.py from typing import TypedDict, List, Annotated import operator from langchain_core.messages import BaseMessage class AgentState(TypedDict): Agent工作流的状态定义。 # 用户原始输入 input: str # 消息历史用于对话上下文 messages: Annotated[List[BaseMessage], operator.add] # 从工具或LLM获取的中间数据 raw_data: str # 分析结果 analysis: str # 最终输出 final_report: str # 控制流程的标志例如是否继续分析 should_continue: bool5.3 定义工作流节点Nodes每个节点是一个函数接收当前State返回更新后的State。# src/agents/analysis_nodes.py from langchain_core.messages import HumanMessage, AIMessage, SystemMessage from .graph_state import AgentState from src.tools.custom_tools import search_tool # 假设我们有一个搜索工具 from src.main import llm def understand_request(state: AgentState) - AgentState: 节点1理解用户请求并规划是否需要获取数据。 user_input state[input] system_prompt 你是一个数据分析助手。请分析用户的请求判断是否需要从外部获取数据例如搜索网络信息。 如果需要在你的回复开头加上‘NEED_DATA:’然后简要说明需要什么数据。 如果不需要直接回答你对用户请求的理解。 messages [ SystemMessage(contentsystem_prompt), HumanMessage(contentuser_input) ] response llm.invoke(messages) # 更新消息历史 state[messages].append(response) # 简单判断是否需要数据根据响应前缀 if response.content.startswith(NEED_DATA:): state[raw_data] 待获取 state[analysis] response.content.replace(NEED_DATA:, ).strip() else: state[analysis] response.content state[should_continue] False # 无需进一步步骤可以直接结束 state[final_report] response.content return state def fetch_data(state: AgentState) - AgentState: 节点2根据分析结果调用工具获取数据。 if state[raw_data] 待获取: search_query state[analysis] # 用分析结果作为搜索词 try: data search_tool.invoke(search_query) state[raw_data] data[:1000] # 限制数据长度 except Exception as e: state[raw_data] f获取数据失败{e} return state def analyze_data(state: AgentState) - AgentState: 节点3分析获取到的数据。 raw_data state[raw_data] user_request state[input] prompt f你是一名数据分析师。以下是用户请求和获取到的相关数据。 用户请求{user_request} 原始数据{raw_data} 请对数据进行分析提取关键信息总结要点。你的分析将用于生成最终报告。 分析结果 response llm.invoke([HumanMessage(contentprompt)]) state[analysis] response.content return state def generate_report(state: AgentState) - AgentState: 节点4根据分析结果生成最终报告。 analysis state[analysis] user_request state[input] prompt f根据以下用户请求和分析结果生成一份简洁、清晰、面向非技术用户的最终报告。 用户原始问题{user_request} 内部分析结果{analysis} 最终报告 response llm.invoke([HumanMessage(contentprompt)]) state[final_report] response.content state[should_continue] False # 报告生成后工作流结束 return state5.4 构建并编译图Graph现在我们将节点连接起来定义流程。# src/agents/analysis_agent.py from langgraph.graph import StateGraph, END from .graph_state import AgentState from .analysis_nodes import understand_request, fetch_data, analyze_data, generate_report # 1. 创建图 workflow StateGraph(AgentState) # 2. 添加节点 workflow.add_node(understand, understand_request) workflow.add_node(fetch_data, fetch_data) workflow.add_node(analyze, analyze_data) workflow.add_node(report, generate_report) # 3. 设置入口点 workflow.set_entry_point(understand) # 4. 定义边流程逻辑 def route_after_understand(state: AgentState): 在‘理解需求’节点后判断下一步去哪。 if state.get(raw_data) 待获取: return fetch_data else: # 如果不需要数据直接跳到生成报告其实报告内容就是分析结果 # 这里为了简化我们直接结束或者跳到一个只输出结果的节点。 # 我们选择直接结束。 return END workflow.add_conditional_edges( understand, route_after_understand, { fetch_data: fetch_data, END: END } ) # 5. 添加其他顺序边 workflow.add_edge(fetch_data, analyze) workflow.add_edge(analyze, report) workflow.add_edge(report, END) # 6. 编译图 app workflow.compile()5.5 运行图工作流# 运行复杂Agent print( 运行数据分析Agent ) initial_state: AgentState { input: 请分析一下最近三个月人工智能领域的主要投资趋势。, messages: [], raw_data: , analysis: , final_report: , should_continue: True, } # 运行图并显示执行过程 for event in app.stream(initial_state, stream_modevalues): event.get(final_report, event) # 打印最终报告 # 在实际中你可以看到每个节点执行后的状态变化 print(f[状态更新] 当前节点输出: {event.get(analysis, N/A)[:100]}...) final_state app.invoke(initial_state) print(\n 最终报告 ) print(final_state[final_report])通过LangGraph我们构建了一个结构清晰、可扩展的多步骤Agent。你可以轻松地添加更多节点如数据清洗、可视化生成或更复杂的条件分支。6. 常见问题与排查思路在开发AI Agent过程中你一定会遇到各种问题。下面是一些常见问题及其解决方案。问题现象可能原因排查步骤与解决方案ModuleNotFoundError: No module named langchain1. 未安装LangChain。2. 在错误的Python环境中运行。1. 确认虚拟环境已激活conda activate ai-agent。2. 使用pip list | grep langchain检查是否安装。3. 重新安装pip install langchain langchain-community。AuthenticationError或Invalid API Key1. API密钥未设置或错误。2. 环境变量未正确加载。3. 账户余额不足或权限问题。1. 检查.env文件格式是否正确密钥前无空格。2. 在代码开头打印os.getenv(“OPENAI_API_KEY”)前几位确认已加载。3. 登录OpenAI控制台检查密钥状态和余额。Agent一直循环思考不输出结果1. ReAct提示词未引导Agent正确结束。2. 工具描述不清晰导致Agent无法选择。3. 模型温度temperature过高思维过于发散。1. 检查使用的提示词模板如hwchase17/react确保包含明确的结束指令如Final Answer:。2. 优化工具函数的docstring使其描述极其精准。3. 将temperature调低如0.1增加确定性。在AgentExecutor中设置max_iterations如5防止无限循环。工具调用失败或参数解析错误1. 工具函数参数类型与模型生成的Action Input不匹配。2. 工具函数内部抛出异常。1. 在工具装饰器tool中确保参数有清晰的类型提示和描述。2. 在工具函数内部做好异常捕获返回友好的错误信息给Agent。3. 开启verboseTrue观察模型生成的Action Input是否合法。LangGraph工作流卡住或状态不更新1. 状态State结构定义与节点返回值不匹配。2. 条件边conditional edges的判断逻辑有误导致无法进入下一个节点。3. 节点函数未返回更新后的state。1. 确保所有节点函数都接收并返回完整的AgentState字典。2. 在条件判断函数中打印日志检查路由逻辑。3. 使用app.stream()模式运行观察每个节点执行后的状态变化。处理速度慢Token消耗大1. 每次调用都包含冗长的历史消息。2. 工具返回的数据量过大全部塞入上下文。3. 使用了过大的模型如GPT-4。1. 使用ConversationSummaryMemory或ConversationBufferWindowMemory来限制历史长度。2. 在工具中或节点处理时对返回的数据进行摘要或截断。3. 对于简单任务先尝试使用gpt-3.5-turbo。优化提示词减少冗余。7. 最佳实践与工程化建议构建可用于生产环境的AI Agent需要超越“跑通Demo”的层面关注可靠性、效率和可维护性。7.1 提示词工程优化清晰的角色与指令在System Prompt中明确Agent的角色、能力和约束。结构化输出要求模型以JSON、XML或特定标记格式输出便于后续程序化解析。prompt 请将分析结果按以下JSON格式输出 { “trends”: [“趋势1”, “趋势2”], “summary”: “一句话总结”, “confidence”: 0.9 } 用户问题{question} 少样本学习Few-Shot在提示词中提供1-3个高质量的输入输出示例能显著提升模型在复杂任务上的表现。7.2 工具设计原则单一职责一个工具只做一件事。例如search_web和query_database应该分开。健壮性工具函数必须包含完善的错误处理try-except并返回对Agent友好的错误信息而不是抛出异常。安全性绝不执行未经净化的用户输入如eval(user_input)。对访问外部API的工具实施速率限制和权限控制。敏感操作如发送邮件、数据库写入需增加确认步骤或人工审核环节。7.3 记忆与状态管理选择合适的记忆类型ConversationBufferMemory保存所有对话简单但消耗大。ConversationBufferWindowMemory只保留最近K轮对话平衡上下文与消耗。ConversationSummaryMemory动态总结历史对话适合长对话。VectorStoreRetrieverMemory将记忆向量化存储可基于语义检索相关记忆适合知识密集型Agent。定期清理状态对于长时间运行的Agent要设计状态清理机制防止内存泄漏。7.4 可观测性与调试全面日志记录记录每个Agent的输入、输出、工具调用、耗时和Token使用量。链路追踪Tracing使用LangSmithLangChain官方平台或OpenTelemetry等工具可视化Agent的完整决策链路便于调试和优化。设置超时与重试对LLM调用和工具调用设置超时并实现指数退避重试策略。7.5 部署与扩展异步化使用async/awaitLangChain支持异步接口提高并发处理能力。API服务化使用FastAPI或Flask将Agent封装为HTTP API提供标准接口。from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class AgentRequest(BaseModel): input: str app.post(/chat) async def chat_with_agent(request: AgentRequest): result await agent_executor.ainvoke({input: request.input}) return {output: result[output]}配置化管理将模型参数、工具列表、提示词模板等抽取到配置文件如YAML中避免硬编码。从理解Agent的核心概念到搭建环境、学习LangChain组件、构建第一个工具调用Agent再到使用LangGraph设计复杂工作流最后探讨工程化实践我们完成了一次完整的AI Agent开发之旅。这只是一个起点Agent的世界广阔无垠下一步你可以探索多Agent协作、与真实业务系统CRM、ERP深度集成、利用检索增强生成RAG构建知识库专家等更高级的主题。记住最好的学习方式是动手实践尝试用Agent去自动化你日常工作中一个重复性的小任务你会收获更多。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度