最近在尝试将AI能力集成到实际业务中时发现很多开发者对“AI Agent”这个概念既熟悉又陌生。熟悉的是铺天盖地的宣传陌生的是如何从零开始用主流框架真正搭建一个能跑起来的智能体。网上的资料要么过于学术化要么是零散的代码片段缺乏一个从环境搭建、框架选择到项目落地的完整闭环教程。本文旨在解决这个问题。我们将以2024年最新的技术栈和最佳实践手把手带你构建一个功能完整的AI Agent。无论你是刚接触AI应用开发的新手还是希望系统化掌握Agent开发的中级开发者都能从本文中获得一套可直接复用的方法论和代码。学完本文你将能够独立完成一个具备规划、工具调用和记忆能力的智能体项目。1. AI Agent 核心概念与架构解析在深入代码之前我们必须厘清AI Agent究竟是什么以及它如何工作。这有助于我们理解后续每个技术选型和代码模块的意义。1.1 什么是AI Agent简单来说AI Agent智能体是一个能够感知环境、进行决策并执行动作以实现特定目标的软件实体。它不仅仅是调用一次大语言模型LLMAPI那么简单而是一个具备自主性、反应性和目标导向性的系统。与传统的“一问一答”式Chatbot相比AI Agent的核心区别在于自主规划能够将复杂目标拆解为可执行的步骤序列。工具使用可以调用外部工具如搜索引擎、数据库、API来获取信息或执行操作。持续学习与记忆拥有短期对话上下文和长期向量数据库记忆能在多轮交互中保持状态和学习。一个典型的AI Agent工作流程可以概括为感知Perception→ 思考Reasoning/Planning→ 行动Action→ 观察Observation的循环直到达成目标或无法继续。1.2 主流AI Agent开发框架概览目前社区活跃着多个优秀的Agent开发框架它们封装了底层复杂性让开发者能更专注于业务逻辑。了解它们的特点有助于我们做出选择。LangChain / LangGraph定位生态最丰富、社区最活跃的“全家桶”式框架。它不只是一个Agent框架更提供了从文档加载、文本分割、向量存储到链Chain、代理Agent的一整套工具。特点模块化设计灵活性极高但学习曲线相对陡峭。LangGraph是其用于构建有状态、多参与者工作流即复杂Agent的库。适合场景需要高度定制化、复杂工作流的研究或生产项目。LlamaIndex定位专注于数据连接的框架。其核心优势在于轻松地将私有数据文档、数据库、API与大模型连接构建基于知识的智能体。特点在RAG检索增强生成和数据代理方面非常强大与LangChain常有交集但更聚焦于数据层面。适合场景以查询和推理私有数据为核心的Agent应用。AutoGen (by Microsoft)定位专注于多智能体对话协作的框架。可以轻松创建多个具有不同角色和能力的Agent让它们通过对话来协同解决任务。特点简化了多Agent的编排和对话管理内置了群聊管理器等高级模式。适合场景模拟社会分工、需要多个专家Agent协作的复杂场景。Semantic Kernel (by Microsoft)定位轻量级SDK旨在将传统编程语言C# Python Java的技能与大型语言模型的能力相结合。特点概念上类似于“插件Plugins”和“规划器Planner”更贴近传统软件开发思维易于与现有.NET/Python应用集成。适合场景希望将AI能力渐进式集成到现有产品中的团队。本文的选择为了覆盖最广泛的开发者需求并展示完整的Agent能力我们将以LangChain作为核心框架进行讲解。因为它最通用其概念和模式也易于迁移到其他框架。同时我们会用到LangGraph来构建一个具备循环和状态管理能力的增强型Agent。2. 环境准备与项目初始化工欲善其事必先利其器。我们将创建一个干净、可复现的Python开发环境。2.1 环境与工具清单操作系统Windows 10/11, macOS 或 Linux (Ubuntu 20.04) 均可。本文命令以Linux/macOS为例Windows用户可在PowerShell或WSL中运行。Python版本 3.10。这是大多数AI库的基线要求。推荐使用3.10或3.11以获得最佳兼容性。包管理工具使用pip和venvPython内置管理依赖。强烈建议使用虚拟环境隔离项目。代码编辑器VS Code、PyCharm等任选。大模型API我们需要一个LLM作为Agent的“大脑”。本文将使用OpenAI的GPT-4o/GPT-3.5-Turbo作为示例因为它稳定且易于获取。你也可以替换为通义千问、DeepSeek、文心一言等国内模型的API。你需要准备一个有效的OpenAI API Key。如果没有可以去其官网注册获取。2.2 创建项目并安装依赖首先我们创建一个全新的项目目录并初始化虚拟环境。# 1. 创建项目目录并进入 mkdir ai-agent-tutorial cd ai-agent-tutorial # 2. 创建虚拟环境 (Windows用户使用 python -m venv venv) python3 -m venv venv # 3. 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 升级pip pip install --upgrade pip接下来创建requirements.txt文件列出我们所需的核心依赖。# requirements.txt langchain0.1.0 langchain-openai0.0.5 langchain-community0.0.10 langgraph0.0.26 openai1.6.1 python-dotenv1.0.0 tiktoken0.5.2依赖说明langchain: LangChain核心库。langchain-openai: LangChain的OpenAI官方集成。langchain-community: 社区贡献的第三方集成如工具。langgraph: 用于构建有状态、多步骤工作流我们的Agent核心。openai: OpenAI官方Python SDK。python-dotenv: 用于从.env文件加载环境变量如API Key。tiktoken: OpenAI用于计算Token的库。安装依赖pip install -r requirements.txt2.3 配置API密钥与环境变量永远不要将API密钥硬编码在代码中我们使用.env文件来管理敏感信息。在项目根目录创建.env文件# .env OPENAI_API_KEYsk-your-actual-openai-api-key-here # 后续如需其他API KEY也可在此添加例如 # SERPAPI_API_KEYxxx # TAVILY_API_KEYxxx同时创建一个.gitignore文件确保不会将敏感信息提交到版本控制系统# .gitignore venv/ .env __pycache__/ *.pyc3. 构建你的第一个基础AI Agent让我们从一个最简单的Agent开始一个能使用计算器工具的数学助手。这能帮你快速理解LangChain Agent的核心组件。3.1 理解Agent的核心组件一个基础的LangChain Agent通常由以下几部分组成工具ToolsAgent可以调用的函数。例如计算器、搜索引擎、数据库查询。大语言模型LLMAgent的“大脑”负责理解指令、决定调用哪个工具、解析工具结果。代理Agent将LLM和工具连接起来的逻辑。它定义了Agent的思考模式如ReAct模式。代理执行器Agent Executor运行Agent的循环控制器负责调用工具、处理LLM响应、管理对话历史。3.2 编写代码数学计算Agent创建一个名为basic_agent.py的文件。# basic_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain import hub # 1. 加载环境变量 load_dotenv() # 2. 定义一个简单的计算器工具 def calculator(query: str) - str: 一个简单的计算器能处理基本算术。输入应为字符串形式的数学表达式如 2 3 * 4。 try: # 警告使用eval有安全风险仅用于演示。生产环境应使用安全计算库如ast.literal_eval或numexpr。 result eval(query) return f计算结果: {result} except Exception as e: return f计算错误: {e} # 将函数包装成LangChain Tool对象 calc_tool Tool( nameCalculator, funccalculator, description用于执行数学计算。输入应该是一个可计算的数学表达式字符串例如 15 7 * 3。 ) # 3. 初始化LLM llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 温度设为0使输出更确定适合工具调用 api_keyos.getenv(OPENAI_API_KEY) ) # 4. 获取一个预设的ReAct提示词模板 # LangChain Hub 是一个提示词模板的仓库我们拉取一个标准的ReAct模板。 prompt hub.pull(hwchase17/react) # 5. 创建ReAct模式的Agent agent create_react_agent(llm, tools[calc_tool], promptprompt) # 6. 创建代理执行器 agent_executor AgentExecutor( agentagent, tools[calc_tool], verboseTrue, # 设为True可以看到Agent的思考过程非常有用 handle_parsing_errorsTrue # 优雅处理LLM输出解析错误 ) # 7. 运行Agent if __name__ __main__: print( 数学计算AI助手 ) print(你可以问我数学问题例如123的平方是多少 或 计算(25 17) / 6) print(输入 退出 或 quit 来结束程序。\n) while True: user_input input(\n你的问题: ).strip() if user_input.lower() in [退出, quit, exit]: print(再见) break if not user_input: continue try: # 调用执行器 response agent_executor.invoke({input: user_input}) print(f\n助手: {response[output]}) except Exception as e: print(f出错了: {e})3.3 运行与解析在终端运行你的第一个Agentpython basic_agent.py你会看到类似以下的输出verboseTrue让我们看到了思考过程 数学计算AI助手 你的问题: 如果我有150块钱买了三本书每本35元还剩多少钱 进入新的Agent执行链... 思考我需要计算总花费和剩余金额。用户有150元买了3本书每本35元。首先计算总花费3 * 35 105元。然后计算剩余150 - 105 45元。我可以使用计算器工具来验证。 行动Calculator 行动输入3 * 35 观察计算结果: 105 思考我得到了总花费105元。现在计算剩余金额。 行动Calculator 行动输入150 - 105 观察计算结果: 45 思考我计算出了剩余金额是45元。现在可以给出最终答案。 最终答案买书总共花费105元所以你还剩45元。 助手: 买书总共花费105元所以你还剩45元。关键点解析ReAct模式输出显示了经典的“思考Thought-行动Action-观察Observation”循环。Agent先推理再调用工具根据结果再推理直到得出最终答案。工具调用Agent自动将问题“还剩多少钱”拆解为两个计算步骤并正确使用了Calculator工具。安全性警告代码中使用了eval()这在生产环境中是极其危险的因为它会执行任意代码。这里仅用于演示。实际项目中应使用ast.literal_eval()或专门的数学表达式解析库。4. 进阶实战构建具备记忆与多工具的工作流Agent基础Agent功能单一且每次对话都是独立的。现在我们使用LangGraph来构建一个更强大的Agent它具备记忆能记住对话历史。多工具能使用搜索和计算工具。可控工作流用图Graph来明确定义Agent的状态和流程。4.1 项目结构与设计我们将构建一个“研究助手”Agent它能根据你的问题进行网络搜索并总结信息。ai-agent-tutorial/ ├── .env ├── .gitignore ├── requirements.txt ├── basic_agent.py └── research_agent/ # 新模块 ├── __init__.py ├── graph.py # 定义LangGraph工作流 ├── state.py # 定义Graph的状态 └── tools.py # 定义搜索等工具4.2 定义工具搜索与总结首先我们需要一个搜索工具。这里我们使用Tavily Search API它是一个为AI优化过的搜索API。你也可以用SerpAPI或其他。获取Tavily API Key去Tavily官网注册一个免费账户获取API Key。更新.env文件# .env OPENAI_API_KEYsk-... TAVILY_API_KEYyour_tavily_api_key_here安装Tavily包pip install tavily-python编写research_agent/tools.py# research_agent/tools.py import os from typing import Optional from langchain.tools import Tool from langchain_community.tools.tavily_search import TavilySearchResults from langchain.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper def setup_tools() - list: 初始化并返回工具列表 tools [] # 1. Tavily 网络搜索工具 (推荐结果更简洁) tavily_api_key os.getenv(TAVILY_API_KEY) if tavily_api_key: search_tool TavilySearchResults( api_wrapperTavilySearchResults( tavily_api_keytavily_api_key ), nameweb_search, description使用此工具在互联网上搜索最新信息。对于需要实时、最新数据的问题非常有用。 ) tools.append(search_tool) else: print(警告未设置TAVILY_API_KEY将使用Wikipedia作为备用搜索工具。) # 2. Wikipedia 工具 (作为备用无需API Key但信息可能不是最新) wikipedia WikipediaQueryRun( api_wrapperWikipediaAPIWrapper(top_k_results3, doc_content_chars_max500), namewikipedia, description用于查询百科全书式的通用知识。适合历史、科学概念、人物传记等主题。 ) tools.append(wikipedia) # 3. 计算器工具 (复用之前的但用更安全的方式) from langchain_community.tools import DuckDuckGoSearchRun # 注意这里我们简单引入一个安全的计算工具示例。实际可用 numexpr 库实现。 # 为简化我们暂时不添加专注于搜索。 return tools4.3 定义Graph的状态LangGraph的核心是“状态State”。它定义了在整个工作流中传递和更新的数据。创建research_agent/state.py。# research_agent/state.py from typing import TypedDict, List, Annotated import operator class AgentState(TypedDict): 定义Agent工作流的状态。 # 用户输入的问题 input: str # Agent生成的中间思考步骤 thoughts: Annotated[List[str], operator.add] # 从工具获取的观察结果 observations: Annotated[List[str], operator.add] # 最终输出给用户的答案 answer: str # 当前应该执行哪个节点agent 或 tools next: strAnnotated[List[str], operator.add]这是一个LangGraph的语法糖表示thoughts和observations这两个字段是列表当多个节点修改它们时新内容会被追加add而不是覆盖。这完美契合了Agent多步思考的需求。4.4 构建LangGraph工作流这是最核心的部分。我们将构建一个包含两个主要节点agent_node和tools_node的图并定义它们之间的流转逻辑。创建research_agent/graph.py。# research_agent/graph.py import os from dotenv import load_dotenv from typing import Literal from langchain_openai import ChatOpenAI from langchain.schema import SystemMessage, HumanMessage, AIMessage from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolExecutor, ToolInvocation from .state import AgentState from .tools import setup_tools # 加载环境变量 load_dotenv() class ResearchAssistantGraph: def __init__(self): # 1. 初始化LLM self.llm ChatOpenAI( modelgpt-4o, # 使用更强的模型进行复杂规划 temperature0, api_keyos.getenv(OPENAI_API_KEY) ) # 2. 初始化工具 self.tools setup_tools() self.tool_executor ToolExecutor(self.tools) # 3. 为LLM绑定工具描述让它知道有哪些工具可用 self.llm_with_tools self.llm.bind_tools(self.tools) def _create_system_prompt(self) - str: 创建系统提示词指导Agent的行为 return 你是一个专业的研究助手。你的任务是回答用户的问题并确保信息的准确性和完整性。 你可以使用以下工具来获取信息 1. web_search: 用于搜索互联网上的最新信息。 2. wikipedia: 用于查询百科全书式的通用知识。 请遵循以下步骤 1. 首先理解用户的问题。 2. 如果你已有的知识足以准确回答请直接回答。 3. 如果问题涉及最新动态、具体数据或你不确定的信息请使用合适的工具进行搜索。 4. 根据工具返回的结果组织你的答案。答案应清晰、有条理并注明信息来源如果来自搜索。 5. 如果一次搜索未能完全解答问题你可以进行多轮搜索和思考。 你的最终输出应该是完整的、对用户友好的答案。 def agent_node(self, state: AgentState) - AgentState: Agent节点负责思考并决定下一步行动调用工具或结束。 print(f\n[Agent节点] 正在思考...) # 构建消息历史 messages [ SystemMessage(contentself._create_system_prompt()), HumanMessage(contentstate[input]) ] # 加入之前的思考和观察如果有 for thought, observation in zip(state.get(thoughts, []), state.get(observations, [])): messages.append(AIMessage(contentthought)) messages.append(HumanMessage(contentf观察: {observation})) # 调用LLM它会返回一个可能包含工具调用请求的响应 response self.llm_with_tools.invoke(messages) # 初始化状态更新字典 new_state {thoughts: [response.content], next: agent} # 默认下一轮还是agent # 检查LLM是否想调用工具 if response.tool_calls: print(f[Agent节点] 决定调用工具: {[tc[name] for tc in response.tool_calls]}) # 如果有工具调用下一节点转向 tools_node new_state[next] tools # 保存工具调用的信息传递给工具节点 new_state[tool_calls] response.tool_calls else: print(f[Agent节点] 认为无需调用工具准备生成最终答案。) # 如果没有工具调用说明可以生成最终答案了 new_state[answer] response.content new_state[next] END # 指向结束节点 return new_state def tools_node(self, state: AgentState) - AgentState: 工具节点执行Agent请求的工具调用。 print(f\n[工具节点] 正在执行工具调用...) tool_calls state[tool_calls] observations [] for tc in tool_calls: # 构造工具调用请求 tool_invocation ToolInvocation( tooltc[name], tool_inputtc[args] ) # 执行工具 try: output self.tool_executor.invoke(tool_invocation) observations.append(f工具 {tc[name]} 返回: {output}) print(f - 执行 {tc[name]} 成功。) except Exception as e: error_msg f调用工具 {tc[name]} 时出错: {e} observations.append(error_msg) print(f - 执行 {tc[name]} 失败: {e}) # 更新状态添加观察结果并指示下一轮回到Agent节点进行思考 return {observations: observations, next: agent} def build_graph(self): 构建并返回LangGraph图 # 创建图构建器 workflow StateGraph(AgentState) # 添加节点 workflow.add_node(agent, self.agent_node) workflow.add_node(tools, self.tools_node) # 设置入口点 workflow.set_entry_point(agent) # 定义条件边根据状态中的 next 字段决定下一步去哪 def route_next(state: AgentState) - Literal[tools, agent, __end__]: return state[next] workflow.add_conditional_edges( agent, route_next, { tools: tools, # 如果next是tools就去工具节点 agent: agent, # 如果next是agent就循环回自身继续思考 __end__: END, # 如果next是__end__就结束 } ) workflow.add_edge(tools, agent) # 工具执行完后总是回到Agent节点思考 # 编译图 graph workflow.compile() return graph4.5 创建主程序并运行在项目根目录创建run_research_agent.py作为入口点。# run_research_agent.py import asyncio from research_agent.graph import ResearchAssistantGraph async def main(): print( 研究助手AI Agent (基于LangGraph) ) print(我可以帮你搜索网络和维基百科来回答问题。) print(输入 退出 或 quit 来结束程序。\n) # 1. 初始化并构建图 assistant ResearchAssistantGraph() graph assistant.build_graph() print(Agent图初始化完成等待你的问题...\n) while True: user_input input(\n你的问题: ).strip() if user_input.lower() in [退出, quit, exit]: print(再见) break if not user_input: continue # 2. 准备初始状态 initial_state { input: user_input, thoughts: [], observations: [], answer: , next: agent } print(\n *50) print(f开始处理: {user_input}) print(*50) # 3. 流式执行Graph并打印中间步骤 final_state None async for event in graph.astream_events(initial_state, versionv1): kind event[event] if kind on_chain_end and event[name] agent: # 当agent节点结束时更新最终状态 final_state event[data].get(output) # 你可以取消下面的注释来查看更详细的事件流 # print(f[事件] {event[event]} - {event[name]}) # 4. 输出最终结果 if final_state and answer in final_state: print(\n *50) print(【最终答案】) print(final_state[answer]) print(*50) else: print(\n未能生成最终答案。) if __name__ __main__: asyncio.run(main())4.6 运行与效果演示运行程序python run_research_agent.py输入一个问题例如“2023年诺贝尔物理学奖获奖者是谁他们的主要贡献是什么”你将看到类似以下的流式输出得益于astream_events这清晰地展示了Agent的思考和工作流程 研究助手AI Agent (基于LangGraph) 你的问题: 2023年诺贝尔物理学奖获奖者是谁他们的主要贡献是什么 开始处理: 2023年诺贝尔物理学奖获奖者是谁他们的主要贡献是什么 [Agent节点] 正在思考... [Agent节点] 决定调用工具: [web_search] [工具节点] 正在执行工具调用... - 执行 web_search 成功。 [Agent节点] 正在思考... [Agent节点] 认为无需调用工具准备生成最终答案。 【最终答案】 2023年诺贝尔物理学奖授予了三位科学家皮埃尔·阿戈斯蒂尼Pierre Agostini、费伦茨·克劳斯Ferenc Krausz和安妮·勒惠利尔Anne L’Huillier以表彰他们在“产生阿秒光脉冲以研究物质中电子动力学的实验方法”方面做出的贡献。 他们的主要贡献是开发了能够产生阿秒attosecond1阿秒10^-18秒光脉冲的实验技术这使得科学家能够观测和测量原子和分子内部电子的超快运动过程。这为理解电子行为开辟了全新途径对物理、化学乃至生物过程的研究具有革命性意义。 项目亮点状态管理LangGraph自动维护了thoughts和observations列表实现了多轮对话记忆。清晰的工作流图Graph明确定义了Agent思考 → 调用工具 → 观察结果 → 再思考的循环直到任务完成。可扩展性你可以轻松添加新的工具如数据库查询、代码执行只需在tools.py中定义并在系统提示词中说明即可。可观测性通过verbose输出和事件流我们能清晰看到Agent的决策过程便于调试和优化。5. 常见问题与排查思路在开发AI Agent过程中你一定会遇到各种问题。以下是一些高频问题及其解决方案。问题现象可能原因排查与解决思路ModuleNotFoundError: No module named langchain_community依赖未正确安装或版本冲突。1. 确认虚拟环境已激活。2. 运行pip install -r requirements.txt --upgrade。3. LangChain版本迭代快检查官方文档确认最新包名。有时langchain-community需要单独安装。openai.AuthenticationError: Incorrect API key providedAPI Key错误或未设置。1. 检查.env文件中的OPENAI_API_KEY是否正确前后有无空格。2. 确认在代码中通过load_dotenv()加载了环境变量。3. 尝试在Python交互环境中print(os.getenv(‘OPENAI_API_KEY’))验证是否能读取。Agent陷入无限循环不停调用工具1. 提示词不够清晰未指示何时停止。2. LLM温度temperature过高输出不稳定。3. 工具描述不准确导致LLM误用。1. 在系统提示词中明确给出停止条件如“当你认为信息足够回答问题时请直接给出最终答案”。2. 将LLM的temperature设为0或较低值如0.1。3. 优化工具的描述description使其职责更明确。工具调用失败返回‘XXX’ is not a valid tool工具名称在绑定给LLM时与实际调用不匹配。1. 检查llm.bind_tools(self.tools)中的tools列表是否包含了你要调用的工具。2. 确保工具对象的name属性与LLM试图调用的名称完全一致大小写敏感。网络搜索工具返回空结果或错误1. API Key无效或额度用完。2. 搜索查询词构造不佳。3. 网络超时。1. 检查Tavily/SerpAPI等服务的控制台确认Key有效且有额度。2. 在代码中打印出实际的搜索查询词看是否合理。3. 添加异常处理和重试机制或考虑使用备用工具如我们代码中的Wikipedia。LangGraph状态更新不符合预期对Annotated字段的operator理解有误或节点返回值错误。1. 理解operator.add是追加operator.set是替换。根据字段语义选择。2. 在每个节点函数中确保返回的字典只包含你想要更新的状态字段其他字段会自动保留。处理中文时效果不佳1. 底层LLM对中文支持弱。2. 提示词是英文的。3. 工具返回英文内容。1. 考虑使用对中文优化更好的模型如GPT-4通义千问文心一言等。2. 将系统提示词和用户问题翻译成中文或使用中英双语提示词。3. 在工具调用后可以添加一个“翻译”或“总结”步骤将英文结果转化为中文。6. 最佳实践与工程化建议将AI Agent从Demo推向生产需要关注更多工程细节。6.1 提示词工程提示词是Agent的“指挥棒”其质量直接决定Agent的表现。明确角色与目标开头清晰定义Agent的角色、能力和边界。结构化步骤使用“首先…然后…最后…”等结构引导LLM的思考过程。提供示例在提示词中加入少量示例Few-shot Learning能显著提升复杂任务的表现。格式化输出要求LLM以特定格式如JSON、Markdown输出便于后续程序解析。迭代优化将提示词单独保存在文件中如prompts.yaml方便版本管理和A/B测试。6.2 工具设计单一职责每个工具应只做一件事并做好。功能过于复杂的工具会让LLM困惑。健壮性工具函数内部必须有完善的错误处理try-except并返回对LLM友好的错误信息。描述清晰description字段至关重要。用自然语言准确描述工具的用途、输入格式和输出示例。安全性尤其是执行代码、访问数据库或操作系统的工具必须进行严格的输入验证和权限控制。6.3 状态与记忆管理短期记忆利用LangGraph的状态机制或ConversationBufferMemory来维护对话上下文。长期记忆对于需要跨会话记忆的知识集成向量数据库如Chroma Pinecone。将重要信息向量化存储在需要时检索。状态序列化对于长时间运行的任务考虑将AgentState序列化如保存为JSON到数据库以便中断后恢复。6.4 性能与成本优化缓存对LLM请求和工具调用结果进行缓存例如使用langchain.cache避免重复计算节省成本和延迟。流式输出像我们示例中使用astream_events一样采用流式处理提升用户体验。设置超时与重试为LLM调用和工具调用设置合理的超时并实现重试逻辑。监控与日志记录每一次LLM调用输入/输出、工具调用和Token消耗用于分析和优化。6.5 测试与评估单元测试为每个工具函数编写单元测试。集成测试模拟用户对话测试完整的Agent工作流。评估体系定义关键指标如任务完成率、回答准确率、平均调用步骤数并构建评估数据集持续迭代Agent表现。通过遵循以上实践你构建的AI Agent将更加稳健、高效和可控能够更好地集成到真实的业务流水线中。从最简单的计算器助手到具备规划、搜索和记忆能力的研究助手我们完成了一个AI Agent从概念到实战的完整构建过程。掌握这个流程后你可以在此基础上扩展出更多强大的应用例如客服助手、智能数据分析Agent、自动化流程Agent等。技术的核心在于理解其范式感知-思考-行动循环。无论框架如何变迁这个核心不会变。建议你接下来可以尝试其他框架用AutoGen构建一个多Agent辩论系统或用Semantic Kernel将Agent能力集成到现有.NET应用中。集成更丰富的工具尝试连接数据库、内部API、邮件系统等让Agent真正成为你的业务助手。深入优化提示词这是成本最低、效果最显著的优化方式。研究Chain-of-Thought, Tree-of-Thought等高级提示技术。关注Agent安全随着能力增强必须考虑幻觉Hallucination缓解、有害内容过滤和工具滥用的防护。AI Agent的开发是一场结合了软件工程、提示词艺术和产品思维的奇妙旅程。希望这篇教程能成为你旅程中一块坚实的垫脚石。动手修改代码添加新功能遇到问题就去社区寻找答案这是最快的学习路径。 从零构建AI Agent：基于LangGraph的智能体开发实战指南
最近在尝试将AI能力集成到实际业务中时发现很多开发者对“AI Agent”这个概念既熟悉又陌生。熟悉的是铺天盖地的宣传陌生的是如何从零开始用主流框架真正搭建一个能跑起来的智能体。网上的资料要么过于学术化要么是零散的代码片段缺乏一个从环境搭建、框架选择到项目落地的完整闭环教程。本文旨在解决这个问题。我们将以2024年最新的技术栈和最佳实践手把手带你构建一个功能完整的AI Agent。无论你是刚接触AI应用开发的新手还是希望系统化掌握Agent开发的中级开发者都能从本文中获得一套可直接复用的方法论和代码。学完本文你将能够独立完成一个具备规划、工具调用和记忆能力的智能体项目。1. AI Agent 核心概念与架构解析在深入代码之前我们必须厘清AI Agent究竟是什么以及它如何工作。这有助于我们理解后续每个技术选型和代码模块的意义。1.1 什么是AI Agent简单来说AI Agent智能体是一个能够感知环境、进行决策并执行动作以实现特定目标的软件实体。它不仅仅是调用一次大语言模型LLMAPI那么简单而是一个具备自主性、反应性和目标导向性的系统。与传统的“一问一答”式Chatbot相比AI Agent的核心区别在于自主规划能够将复杂目标拆解为可执行的步骤序列。工具使用可以调用外部工具如搜索引擎、数据库、API来获取信息或执行操作。持续学习与记忆拥有短期对话上下文和长期向量数据库记忆能在多轮交互中保持状态和学习。一个典型的AI Agent工作流程可以概括为感知Perception→ 思考Reasoning/Planning→ 行动Action→ 观察Observation的循环直到达成目标或无法继续。1.2 主流AI Agent开发框架概览目前社区活跃着多个优秀的Agent开发框架它们封装了底层复杂性让开发者能更专注于业务逻辑。了解它们的特点有助于我们做出选择。LangChain / LangGraph定位生态最丰富、社区最活跃的“全家桶”式框架。它不只是一个Agent框架更提供了从文档加载、文本分割、向量存储到链Chain、代理Agent的一整套工具。特点模块化设计灵活性极高但学习曲线相对陡峭。LangGraph是其用于构建有状态、多参与者工作流即复杂Agent的库。适合场景需要高度定制化、复杂工作流的研究或生产项目。LlamaIndex定位专注于数据连接的框架。其核心优势在于轻松地将私有数据文档、数据库、API与大模型连接构建基于知识的智能体。特点在RAG检索增强生成和数据代理方面非常强大与LangChain常有交集但更聚焦于数据层面。适合场景以查询和推理私有数据为核心的Agent应用。AutoGen (by Microsoft)定位专注于多智能体对话协作的框架。可以轻松创建多个具有不同角色和能力的Agent让它们通过对话来协同解决任务。特点简化了多Agent的编排和对话管理内置了群聊管理器等高级模式。适合场景模拟社会分工、需要多个专家Agent协作的复杂场景。Semantic Kernel (by Microsoft)定位轻量级SDK旨在将传统编程语言C# Python Java的技能与大型语言模型的能力相结合。特点概念上类似于“插件Plugins”和“规划器Planner”更贴近传统软件开发思维易于与现有.NET/Python应用集成。适合场景希望将AI能力渐进式集成到现有产品中的团队。本文的选择为了覆盖最广泛的开发者需求并展示完整的Agent能力我们将以LangChain作为核心框架进行讲解。因为它最通用其概念和模式也易于迁移到其他框架。同时我们会用到LangGraph来构建一个具备循环和状态管理能力的增强型Agent。2. 环境准备与项目初始化工欲善其事必先利其器。我们将创建一个干净、可复现的Python开发环境。2.1 环境与工具清单操作系统Windows 10/11, macOS 或 Linux (Ubuntu 20.04) 均可。本文命令以Linux/macOS为例Windows用户可在PowerShell或WSL中运行。Python版本 3.10。这是大多数AI库的基线要求。推荐使用3.10或3.11以获得最佳兼容性。包管理工具使用pip和venvPython内置管理依赖。强烈建议使用虚拟环境隔离项目。代码编辑器VS Code、PyCharm等任选。大模型API我们需要一个LLM作为Agent的“大脑”。本文将使用OpenAI的GPT-4o/GPT-3.5-Turbo作为示例因为它稳定且易于获取。你也可以替换为通义千问、DeepSeek、文心一言等国内模型的API。你需要准备一个有效的OpenAI API Key。如果没有可以去其官网注册获取。2.2 创建项目并安装依赖首先我们创建一个全新的项目目录并初始化虚拟环境。# 1. 创建项目目录并进入 mkdir ai-agent-tutorial cd ai-agent-tutorial # 2. 创建虚拟环境 (Windows用户使用 python -m venv venv) python3 -m venv venv # 3. 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 升级pip pip install --upgrade pip接下来创建requirements.txt文件列出我们所需的核心依赖。# requirements.txt langchain0.1.0 langchain-openai0.0.5 langchain-community0.0.10 langgraph0.0.26 openai1.6.1 python-dotenv1.0.0 tiktoken0.5.2依赖说明langchain: LangChain核心库。langchain-openai: LangChain的OpenAI官方集成。langchain-community: 社区贡献的第三方集成如工具。langgraph: 用于构建有状态、多步骤工作流我们的Agent核心。openai: OpenAI官方Python SDK。python-dotenv: 用于从.env文件加载环境变量如API Key。tiktoken: OpenAI用于计算Token的库。安装依赖pip install -r requirements.txt2.3 配置API密钥与环境变量永远不要将API密钥硬编码在代码中我们使用.env文件来管理敏感信息。在项目根目录创建.env文件# .env OPENAI_API_KEYsk-your-actual-openai-api-key-here # 后续如需其他API KEY也可在此添加例如 # SERPAPI_API_KEYxxx # TAVILY_API_KEYxxx同时创建一个.gitignore文件确保不会将敏感信息提交到版本控制系统# .gitignore venv/ .env __pycache__/ *.pyc3. 构建你的第一个基础AI Agent让我们从一个最简单的Agent开始一个能使用计算器工具的数学助手。这能帮你快速理解LangChain Agent的核心组件。3.1 理解Agent的核心组件一个基础的LangChain Agent通常由以下几部分组成工具ToolsAgent可以调用的函数。例如计算器、搜索引擎、数据库查询。大语言模型LLMAgent的“大脑”负责理解指令、决定调用哪个工具、解析工具结果。代理Agent将LLM和工具连接起来的逻辑。它定义了Agent的思考模式如ReAct模式。代理执行器Agent Executor运行Agent的循环控制器负责调用工具、处理LLM响应、管理对话历史。3.2 编写代码数学计算Agent创建一个名为basic_agent.py的文件。# basic_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain import hub # 1. 加载环境变量 load_dotenv() # 2. 定义一个简单的计算器工具 def calculator(query: str) - str: 一个简单的计算器能处理基本算术。输入应为字符串形式的数学表达式如 2 3 * 4。 try: # 警告使用eval有安全风险仅用于演示。生产环境应使用安全计算库如ast.literal_eval或numexpr。 result eval(query) return f计算结果: {result} except Exception as e: return f计算错误: {e} # 将函数包装成LangChain Tool对象 calc_tool Tool( nameCalculator, funccalculator, description用于执行数学计算。输入应该是一个可计算的数学表达式字符串例如 15 7 * 3。 ) # 3. 初始化LLM llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 温度设为0使输出更确定适合工具调用 api_keyos.getenv(OPENAI_API_KEY) ) # 4. 获取一个预设的ReAct提示词模板 # LangChain Hub 是一个提示词模板的仓库我们拉取一个标准的ReAct模板。 prompt hub.pull(hwchase17/react) # 5. 创建ReAct模式的Agent agent create_react_agent(llm, tools[calc_tool], promptprompt) # 6. 创建代理执行器 agent_executor AgentExecutor( agentagent, tools[calc_tool], verboseTrue, # 设为True可以看到Agent的思考过程非常有用 handle_parsing_errorsTrue # 优雅处理LLM输出解析错误 ) # 7. 运行Agent if __name__ __main__: print( 数学计算AI助手 ) print(你可以问我数学问题例如123的平方是多少 或 计算(25 17) / 6) print(输入 退出 或 quit 来结束程序。\n) while True: user_input input(\n你的问题: ).strip() if user_input.lower() in [退出, quit, exit]: print(再见) break if not user_input: continue try: # 调用执行器 response agent_executor.invoke({input: user_input}) print(f\n助手: {response[output]}) except Exception as e: print(f出错了: {e})3.3 运行与解析在终端运行你的第一个Agentpython basic_agent.py你会看到类似以下的输出verboseTrue让我们看到了思考过程 数学计算AI助手 你的问题: 如果我有150块钱买了三本书每本35元还剩多少钱 进入新的Agent执行链... 思考我需要计算总花费和剩余金额。用户有150元买了3本书每本35元。首先计算总花费3 * 35 105元。然后计算剩余150 - 105 45元。我可以使用计算器工具来验证。 行动Calculator 行动输入3 * 35 观察计算结果: 105 思考我得到了总花费105元。现在计算剩余金额。 行动Calculator 行动输入150 - 105 观察计算结果: 45 思考我计算出了剩余金额是45元。现在可以给出最终答案。 最终答案买书总共花费105元所以你还剩45元。 助手: 买书总共花费105元所以你还剩45元。关键点解析ReAct模式输出显示了经典的“思考Thought-行动Action-观察Observation”循环。Agent先推理再调用工具根据结果再推理直到得出最终答案。工具调用Agent自动将问题“还剩多少钱”拆解为两个计算步骤并正确使用了Calculator工具。安全性警告代码中使用了eval()这在生产环境中是极其危险的因为它会执行任意代码。这里仅用于演示。实际项目中应使用ast.literal_eval()或专门的数学表达式解析库。4. 进阶实战构建具备记忆与多工具的工作流Agent基础Agent功能单一且每次对话都是独立的。现在我们使用LangGraph来构建一个更强大的Agent它具备记忆能记住对话历史。多工具能使用搜索和计算工具。可控工作流用图Graph来明确定义Agent的状态和流程。4.1 项目结构与设计我们将构建一个“研究助手”Agent它能根据你的问题进行网络搜索并总结信息。ai-agent-tutorial/ ├── .env ├── .gitignore ├── requirements.txt ├── basic_agent.py └── research_agent/ # 新模块 ├── __init__.py ├── graph.py # 定义LangGraph工作流 ├── state.py # 定义Graph的状态 └── tools.py # 定义搜索等工具4.2 定义工具搜索与总结首先我们需要一个搜索工具。这里我们使用Tavily Search API它是一个为AI优化过的搜索API。你也可以用SerpAPI或其他。获取Tavily API Key去Tavily官网注册一个免费账户获取API Key。更新.env文件# .env OPENAI_API_KEYsk-... TAVILY_API_KEYyour_tavily_api_key_here安装Tavily包pip install tavily-python编写research_agent/tools.py# research_agent/tools.py import os from typing import Optional from langchain.tools import Tool from langchain_community.tools.tavily_search import TavilySearchResults from langchain.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper def setup_tools() - list: 初始化并返回工具列表 tools [] # 1. Tavily 网络搜索工具 (推荐结果更简洁) tavily_api_key os.getenv(TAVILY_API_KEY) if tavily_api_key: search_tool TavilySearchResults( api_wrapperTavilySearchResults( tavily_api_keytavily_api_key ), nameweb_search, description使用此工具在互联网上搜索最新信息。对于需要实时、最新数据的问题非常有用。 ) tools.append(search_tool) else: print(警告未设置TAVILY_API_KEY将使用Wikipedia作为备用搜索工具。) # 2. Wikipedia 工具 (作为备用无需API Key但信息可能不是最新) wikipedia WikipediaQueryRun( api_wrapperWikipediaAPIWrapper(top_k_results3, doc_content_chars_max500), namewikipedia, description用于查询百科全书式的通用知识。适合历史、科学概念、人物传记等主题。 ) tools.append(wikipedia) # 3. 计算器工具 (复用之前的但用更安全的方式) from langchain_community.tools import DuckDuckGoSearchRun # 注意这里我们简单引入一个安全的计算工具示例。实际可用 numexpr 库实现。 # 为简化我们暂时不添加专注于搜索。 return tools4.3 定义Graph的状态LangGraph的核心是“状态State”。它定义了在整个工作流中传递和更新的数据。创建research_agent/state.py。# research_agent/state.py from typing import TypedDict, List, Annotated import operator class AgentState(TypedDict): 定义Agent工作流的状态。 # 用户输入的问题 input: str # Agent生成的中间思考步骤 thoughts: Annotated[List[str], operator.add] # 从工具获取的观察结果 observations: Annotated[List[str], operator.add] # 最终输出给用户的答案 answer: str # 当前应该执行哪个节点agent 或 tools next: strAnnotated[List[str], operator.add]这是一个LangGraph的语法糖表示thoughts和observations这两个字段是列表当多个节点修改它们时新内容会被追加add而不是覆盖。这完美契合了Agent多步思考的需求。4.4 构建LangGraph工作流这是最核心的部分。我们将构建一个包含两个主要节点agent_node和tools_node的图并定义它们之间的流转逻辑。创建research_agent/graph.py。# research_agent/graph.py import os from dotenv import load_dotenv from typing import Literal from langchain_openai import ChatOpenAI from langchain.schema import SystemMessage, HumanMessage, AIMessage from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolExecutor, ToolInvocation from .state import AgentState from .tools import setup_tools # 加载环境变量 load_dotenv() class ResearchAssistantGraph: def __init__(self): # 1. 初始化LLM self.llm ChatOpenAI( modelgpt-4o, # 使用更强的模型进行复杂规划 temperature0, api_keyos.getenv(OPENAI_API_KEY) ) # 2. 初始化工具 self.tools setup_tools() self.tool_executor ToolExecutor(self.tools) # 3. 为LLM绑定工具描述让它知道有哪些工具可用 self.llm_with_tools self.llm.bind_tools(self.tools) def _create_system_prompt(self) - str: 创建系统提示词指导Agent的行为 return 你是一个专业的研究助手。你的任务是回答用户的问题并确保信息的准确性和完整性。 你可以使用以下工具来获取信息 1. web_search: 用于搜索互联网上的最新信息。 2. wikipedia: 用于查询百科全书式的通用知识。 请遵循以下步骤 1. 首先理解用户的问题。 2. 如果你已有的知识足以准确回答请直接回答。 3. 如果问题涉及最新动态、具体数据或你不确定的信息请使用合适的工具进行搜索。 4. 根据工具返回的结果组织你的答案。答案应清晰、有条理并注明信息来源如果来自搜索。 5. 如果一次搜索未能完全解答问题你可以进行多轮搜索和思考。 你的最终输出应该是完整的、对用户友好的答案。 def agent_node(self, state: AgentState) - AgentState: Agent节点负责思考并决定下一步行动调用工具或结束。 print(f\n[Agent节点] 正在思考...) # 构建消息历史 messages [ SystemMessage(contentself._create_system_prompt()), HumanMessage(contentstate[input]) ] # 加入之前的思考和观察如果有 for thought, observation in zip(state.get(thoughts, []), state.get(observations, [])): messages.append(AIMessage(contentthought)) messages.append(HumanMessage(contentf观察: {observation})) # 调用LLM它会返回一个可能包含工具调用请求的响应 response self.llm_with_tools.invoke(messages) # 初始化状态更新字典 new_state {thoughts: [response.content], next: agent} # 默认下一轮还是agent # 检查LLM是否想调用工具 if response.tool_calls: print(f[Agent节点] 决定调用工具: {[tc[name] for tc in response.tool_calls]}) # 如果有工具调用下一节点转向 tools_node new_state[next] tools # 保存工具调用的信息传递给工具节点 new_state[tool_calls] response.tool_calls else: print(f[Agent节点] 认为无需调用工具准备生成最终答案。) # 如果没有工具调用说明可以生成最终答案了 new_state[answer] response.content new_state[next] END # 指向结束节点 return new_state def tools_node(self, state: AgentState) - AgentState: 工具节点执行Agent请求的工具调用。 print(f\n[工具节点] 正在执行工具调用...) tool_calls state[tool_calls] observations [] for tc in tool_calls: # 构造工具调用请求 tool_invocation ToolInvocation( tooltc[name], tool_inputtc[args] ) # 执行工具 try: output self.tool_executor.invoke(tool_invocation) observations.append(f工具 {tc[name]} 返回: {output}) print(f - 执行 {tc[name]} 成功。) except Exception as e: error_msg f调用工具 {tc[name]} 时出错: {e} observations.append(error_msg) print(f - 执行 {tc[name]} 失败: {e}) # 更新状态添加观察结果并指示下一轮回到Agent节点进行思考 return {observations: observations, next: agent} def build_graph(self): 构建并返回LangGraph图 # 创建图构建器 workflow StateGraph(AgentState) # 添加节点 workflow.add_node(agent, self.agent_node) workflow.add_node(tools, self.tools_node) # 设置入口点 workflow.set_entry_point(agent) # 定义条件边根据状态中的 next 字段决定下一步去哪 def route_next(state: AgentState) - Literal[tools, agent, __end__]: return state[next] workflow.add_conditional_edges( agent, route_next, { tools: tools, # 如果next是tools就去工具节点 agent: agent, # 如果next是agent就循环回自身继续思考 __end__: END, # 如果next是__end__就结束 } ) workflow.add_edge(tools, agent) # 工具执行完后总是回到Agent节点思考 # 编译图 graph workflow.compile() return graph4.5 创建主程序并运行在项目根目录创建run_research_agent.py作为入口点。# run_research_agent.py import asyncio from research_agent.graph import ResearchAssistantGraph async def main(): print( 研究助手AI Agent (基于LangGraph) ) print(我可以帮你搜索网络和维基百科来回答问题。) print(输入 退出 或 quit 来结束程序。\n) # 1. 初始化并构建图 assistant ResearchAssistantGraph() graph assistant.build_graph() print(Agent图初始化完成等待你的问题...\n) while True: user_input input(\n你的问题: ).strip() if user_input.lower() in [退出, quit, exit]: print(再见) break if not user_input: continue # 2. 准备初始状态 initial_state { input: user_input, thoughts: [], observations: [], answer: , next: agent } print(\n *50) print(f开始处理: {user_input}) print(*50) # 3. 流式执行Graph并打印中间步骤 final_state None async for event in graph.astream_events(initial_state, versionv1): kind event[event] if kind on_chain_end and event[name] agent: # 当agent节点结束时更新最终状态 final_state event[data].get(output) # 你可以取消下面的注释来查看更详细的事件流 # print(f[事件] {event[event]} - {event[name]}) # 4. 输出最终结果 if final_state and answer in final_state: print(\n *50) print(【最终答案】) print(final_state[answer]) print(*50) else: print(\n未能生成最终答案。) if __name__ __main__: asyncio.run(main())4.6 运行与效果演示运行程序python run_research_agent.py输入一个问题例如“2023年诺贝尔物理学奖获奖者是谁他们的主要贡献是什么”你将看到类似以下的流式输出得益于astream_events这清晰地展示了Agent的思考和工作流程 研究助手AI Agent (基于LangGraph) 你的问题: 2023年诺贝尔物理学奖获奖者是谁他们的主要贡献是什么 开始处理: 2023年诺贝尔物理学奖获奖者是谁他们的主要贡献是什么 [Agent节点] 正在思考... [Agent节点] 决定调用工具: [web_search] [工具节点] 正在执行工具调用... - 执行 web_search 成功。 [Agent节点] 正在思考... [Agent节点] 认为无需调用工具准备生成最终答案。 【最终答案】 2023年诺贝尔物理学奖授予了三位科学家皮埃尔·阿戈斯蒂尼Pierre Agostini、费伦茨·克劳斯Ferenc Krausz和安妮·勒惠利尔Anne L’Huillier以表彰他们在“产生阿秒光脉冲以研究物质中电子动力学的实验方法”方面做出的贡献。 他们的主要贡献是开发了能够产生阿秒attosecond1阿秒10^-18秒光脉冲的实验技术这使得科学家能够观测和测量原子和分子内部电子的超快运动过程。这为理解电子行为开辟了全新途径对物理、化学乃至生物过程的研究具有革命性意义。 项目亮点状态管理LangGraph自动维护了thoughts和observations列表实现了多轮对话记忆。清晰的工作流图Graph明确定义了Agent思考 → 调用工具 → 观察结果 → 再思考的循环直到任务完成。可扩展性你可以轻松添加新的工具如数据库查询、代码执行只需在tools.py中定义并在系统提示词中说明即可。可观测性通过verbose输出和事件流我们能清晰看到Agent的决策过程便于调试和优化。5. 常见问题与排查思路在开发AI Agent过程中你一定会遇到各种问题。以下是一些高频问题及其解决方案。问题现象可能原因排查与解决思路ModuleNotFoundError: No module named langchain_community依赖未正确安装或版本冲突。1. 确认虚拟环境已激活。2. 运行pip install -r requirements.txt --upgrade。3. LangChain版本迭代快检查官方文档确认最新包名。有时langchain-community需要单独安装。openai.AuthenticationError: Incorrect API key providedAPI Key错误或未设置。1. 检查.env文件中的OPENAI_API_KEY是否正确前后有无空格。2. 确认在代码中通过load_dotenv()加载了环境变量。3. 尝试在Python交互环境中print(os.getenv(‘OPENAI_API_KEY’))验证是否能读取。Agent陷入无限循环不停调用工具1. 提示词不够清晰未指示何时停止。2. LLM温度temperature过高输出不稳定。3. 工具描述不准确导致LLM误用。1. 在系统提示词中明确给出停止条件如“当你认为信息足够回答问题时请直接给出最终答案”。2. 将LLM的temperature设为0或较低值如0.1。3. 优化工具的描述description使其职责更明确。工具调用失败返回‘XXX’ is not a valid tool工具名称在绑定给LLM时与实际调用不匹配。1. 检查llm.bind_tools(self.tools)中的tools列表是否包含了你要调用的工具。2. 确保工具对象的name属性与LLM试图调用的名称完全一致大小写敏感。网络搜索工具返回空结果或错误1. API Key无效或额度用完。2. 搜索查询词构造不佳。3. 网络超时。1. 检查Tavily/SerpAPI等服务的控制台确认Key有效且有额度。2. 在代码中打印出实际的搜索查询词看是否合理。3. 添加异常处理和重试机制或考虑使用备用工具如我们代码中的Wikipedia。LangGraph状态更新不符合预期对Annotated字段的operator理解有误或节点返回值错误。1. 理解operator.add是追加operator.set是替换。根据字段语义选择。2. 在每个节点函数中确保返回的字典只包含你想要更新的状态字段其他字段会自动保留。处理中文时效果不佳1. 底层LLM对中文支持弱。2. 提示词是英文的。3. 工具返回英文内容。1. 考虑使用对中文优化更好的模型如GPT-4通义千问文心一言等。2. 将系统提示词和用户问题翻译成中文或使用中英双语提示词。3. 在工具调用后可以添加一个“翻译”或“总结”步骤将英文结果转化为中文。6. 最佳实践与工程化建议将AI Agent从Demo推向生产需要关注更多工程细节。6.1 提示词工程提示词是Agent的“指挥棒”其质量直接决定Agent的表现。明确角色与目标开头清晰定义Agent的角色、能力和边界。结构化步骤使用“首先…然后…最后…”等结构引导LLM的思考过程。提供示例在提示词中加入少量示例Few-shot Learning能显著提升复杂任务的表现。格式化输出要求LLM以特定格式如JSON、Markdown输出便于后续程序解析。迭代优化将提示词单独保存在文件中如prompts.yaml方便版本管理和A/B测试。6.2 工具设计单一职责每个工具应只做一件事并做好。功能过于复杂的工具会让LLM困惑。健壮性工具函数内部必须有完善的错误处理try-except并返回对LLM友好的错误信息。描述清晰description字段至关重要。用自然语言准确描述工具的用途、输入格式和输出示例。安全性尤其是执行代码、访问数据库或操作系统的工具必须进行严格的输入验证和权限控制。6.3 状态与记忆管理短期记忆利用LangGraph的状态机制或ConversationBufferMemory来维护对话上下文。长期记忆对于需要跨会话记忆的知识集成向量数据库如Chroma Pinecone。将重要信息向量化存储在需要时检索。状态序列化对于长时间运行的任务考虑将AgentState序列化如保存为JSON到数据库以便中断后恢复。6.4 性能与成本优化缓存对LLM请求和工具调用结果进行缓存例如使用langchain.cache避免重复计算节省成本和延迟。流式输出像我们示例中使用astream_events一样采用流式处理提升用户体验。设置超时与重试为LLM调用和工具调用设置合理的超时并实现重试逻辑。监控与日志记录每一次LLM调用输入/输出、工具调用和Token消耗用于分析和优化。6.5 测试与评估单元测试为每个工具函数编写单元测试。集成测试模拟用户对话测试完整的Agent工作流。评估体系定义关键指标如任务完成率、回答准确率、平均调用步骤数并构建评估数据集持续迭代Agent表现。通过遵循以上实践你构建的AI Agent将更加稳健、高效和可控能够更好地集成到真实的业务流水线中。从最简单的计算器助手到具备规划、搜索和记忆能力的研究助手我们完成了一个AI Agent从概念到实战的完整构建过程。掌握这个流程后你可以在此基础上扩展出更多强大的应用例如客服助手、智能数据分析Agent、自动化流程Agent等。技术的核心在于理解其范式感知-思考-行动循环。无论框架如何变迁这个核心不会变。建议你接下来可以尝试其他框架用AutoGen构建一个多Agent辩论系统或用Semantic Kernel将Agent能力集成到现有.NET应用中。集成更丰富的工具尝试连接数据库、内部API、邮件系统等让Agent真正成为你的业务助手。深入优化提示词这是成本最低、效果最显著的优化方式。研究Chain-of-Thought, Tree-of-Thought等高级提示技术。关注Agent安全随着能力增强必须考虑幻觉Hallucination缓解、有害内容过滤和工具滥用的防护。AI Agent的开发是一场结合了软件工程、提示词艺术和产品思维的奇妙旅程。希望这篇教程能成为你旅程中一块坚实的垫脚石。动手修改代码添加新功能遇到问题就去社区寻找答案这是最快的学习路径。