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具备几个关键特征：

1. 自主性（Autonomy）：在给定目标后，能够自行规划步骤，无需人类步步指导。
2. 工具使用（Tool Use）：可以调用外部工具，如搜索引擎、计算器、数据库、API等，来扩展自身能力边界。
3. 记忆与状态（Memory & State）：能够记住之前的交互历史、任务上下文和自身状态，从而进行连贯的多轮任务处理。
4. 反应与规划（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 python=3.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系列为例，其他模型（如国内大模型、开源模型）接入方式类似。

1. 访问OpenAI平台注册并获取API Key。
2. 在项目根目录创建.env文件，用于安全存储密钥：

# .env 文件 OPENAI_API_KEY=你的sk-xxx密钥

3. 在代码中通过python-dotenv加载环境变量。

2.4 项目结构初始化

建议采用清晰的项目结构：

ai-agent-project/ ├── .env # 环境变量（切勿提交至Git） ├── requirements.txt # 项目依赖 ├── src/ # 源代码 │ ├── agents/ # Agent定义 │ ├── tools/ # 自定义工具 │ ├── memory/ # 记忆模块 │ └── main.py # 主入口 ├── notebooks/ # Jupyter实验笔记 └── README.md

使用以下命令生成requirements.txt：

pip 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( model="gpt-3.5-turbo", # 或 "gpt-4", "gpt-4-turbo" temperature=0.7, # 创造性，0-1之间，越高越随机 api_key=os.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_name="chat_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_history=chat_history, user_input=current_input ) response = llm.invoke(formatted_prompt) print(response.content)

3.3 链（Chains）

链将多个组件（模型、提示词、工具等）按顺序组合起来，完成一个特定任务。这是构建复杂逻辑的基础。

from langchain.chains import LLMChain # 创建一个简单的链：提示词 + 模型 chain = LLMChain(llm=llm, prompt=prompt_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_key="chat_history", return_messages=True # 返回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来创建一个基于ReAct（Reasoning + 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( agent=agent, tools=tools, verbose=True, # 设置为True可以看到Agent的思考过程，非常有用！ handle_parsing_errors=True # 优雅地处理解析错误 )

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，星期三。

通过verbose=True，我们清晰地看到了Agent的思考链（Thought）、行动（Action）和观察（Observation）。这就是ReAct模式在运行。

恭喜！你已经成功创建了一个能够自主选择并使用工具的AI Agent。但这只是一个开始。现实中的任务往往更复杂，需要多个步骤、状态管理和协作。接下来，我们将使用更强大的LangGraph来构建支持多步骤工作流的智能体。

5. 进阶：使用LangGraph构建多步骤工作流Agent

当任务需要一系列有序或条件判断步骤时，简单的ReAct Agent可能不够灵活。LangGraph允许我们将Agent的工作流定义为一个有向图，节点代表步骤（如调用LLM、执行工具），边代表步骤之间的流转条件。

5.1 设计一个数据分析Agent工作流

假设我们要构建一个“数据分析助手”Agent，其工作流程如下：

1. 理解需求：解析用户请求，判断是否需要获取数据。
2. 获取数据：如果需要，调用工具（如搜索、查询数据库）获取数据。
3. 分析数据：对获取的数据进行分析（计算、总结、找规律）。
4. 生成报告：将分析结果格式化为用户友好的报告。
5. 循环判断：根据分析结果，决定是否需要进一步深入分析或结束。

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: bool

5.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(content=system_prompt), HumanMessage(content=user_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(content=prompt)]) 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(content=prompt)]) state["final_report"] = response.content state["should_continue"] = False # 报告生成后，工作流结束 return state

5.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_mode="values"): 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过程中，你一定会遇到各种问题。下面是一些常见问题及其解决方案。

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）：使用LangSmith（LangChain官方平台）或OpenTelemetry等工具，可视化Agent的完整决策链路，便于调试和优化。
• 设置超时与重试：对LLM调用和工具调用设置超时，并实现指数退避重试策略。

7.5 部署与扩展

• 异步化：使用async/await（LangChain支持异步接口）提高并发处理能力。
• 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 折。 👉 点击领海量免费额度