30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度最近在尝试将大语言模型应用到实际业务场景时很多开发者发现单纯调用API生成文本已经不够用了。我们常常需要模型能够“思考”能够“行动”能够像人一样按步骤完成任务比如自动分析数据、调用工具、处理异常并最终给出结果。这就是AI Agent智能体要解决的问题。然而从概念到落地中间横亘着工具链选择、架构设计、状态管理等一系列难题网上资料虽多但往往不成体系让人望而却步。本文将为你提供一份从零到一的AI Agent实战指南。我们不空谈理论而是手把手带你搭建一个具备完整工作流的智能体系统。我们将融合LangChain的便捷组件、LangGraph的强大工作流引擎并引入火山引擎的OpenClaw工具平台构建一个能感知、规划、执行、学习的实用智能体。无论你是想入门Agent开发还是希望将智能体集成到现有项目这篇文章都能提供清晰的路径和可运行的代码。1. 背景与核心概念为什么需要AI Agent在深入代码之前我们有必要厘清几个核心概念理解为什么单纯的“提示词工程”已经无法满足复杂需求。1.1 什么是AI Agent智能体你可以把AI Agent想象成一个虚拟的、具备一定自主性的“数字员工”。它不仅仅是一个问答机器而是一个系统其核心能力包括感知Perception理解用户的指令输入和当前的环境状态如工具调用结果、历史对话。规划Planning将复杂目标拆解为一系列可执行的子任务或步骤。行动Action执行具体的操作例如调用一个计算器API、查询数据库、运行一段代码。反思Reflection评估行动结果判断是否达成目标是否需要调整策略。这与传统的单次LLM调用有本质区别。传统调用是“一问一答”而Agent是“多轮交互与决策”。1.2 LangChain、LangGraph与OpenClaw的角色在构建Agent时我们不会从零造轮子而是借助成熟的框架和平台。LangChain一个用于开发由语言模型驱动的应用程序的框架。它提供了大量的“组件”如提示词模板、文档加载器、向量存储、以及各种链Chains。在Agent语境下LangChain提供了构建Agent所需的基础工具Tools、记忆Memory和代理Agent执行器。它解决了“用什么”的问题。LangGraph这是LangChain团队推出的一个用于构建有状态、多参与者Agent应用程序的库。你可以把它理解为Agent的“工作流引擎”或“大脑皮层”。它用图Graph的概念来建模Agent的决策流程其中节点代表步骤如调用LLM、执行工具边代表控制流根据上一步结果决定下一步去哪。它解决了“如何思考与流转”的问题。OpenClaw火山引擎一个面向AI应用开发的工具与模型服务平台。它提供了丰富的预置工具如联网搜索、图像处理、代码执行等和便捷的模型部署、管理能力。在本文中我们将它作为Agent强大的“工具库”和“执行臂”。它解决了“能做什么”的问题。简单比喻LangChain提供了建造Agent的砖块和水泥LangGraph提供了建筑的设计图纸和施工流程OpenClaw则提供了建筑内的高级电器和智能设备。1.3 本教程的目标与最终成果本教程将带你完成一个综合性实战案例构建一个“技术助手”智能体。这个智能体能够理解用户关于技术问题的复杂查询。自动判断是否需要联网搜索最新信息使用OpenClaw工具。在需要时进行搜索并整合搜索到的信息与模型自身知识。生成结构清晰、信息准确的最终回答。通过这个案例你将掌握使用LangChainLangGraphOpenClaw构建智能体的完整闭环。2. 环境准备与版本说明工欲善其事必先利其器。我们先来搭建开发环境。2.1 基础环境要求操作系统Windows 10/11 macOS 或 Linux (如 Ubuntu 20.04) 均可。本文命令以Linux/macOS的bash为例Windows用户可在PowerShell或WSL中运行。Python版本推荐使用Python 3.10或3.11。这是大多数AI库兼容性最好的版本。避免使用Python 3.12等过新版本可能遇到依赖冲突。包管理工具使用pip进行包安装。建议先升级pippip install --upgrade pip。代码编辑器VS Code、PyCharm等任选。2.2 安装核心库创建一个新的虚拟环境是一个好习惯可以避免包冲突。# 创建并激活虚拟环境 (以venv为例) python -m venv ai_agent_env source ai_agent_env/bin/activate # Linux/macOS # ai_agent_env\Scripts\activate # Windows # 安装LangChain和LangGraph。注意LangGraph通常与LangChain一起安装。 pip install langchain langgraph # 安装LangChain社区版包含更多社区维护的工具和集成。 pip install langchain-community # 安装OpenAI库我们将使用OpenAI的模型作为Agent的“大脑” # 注意你需要拥有OpenAI API Key。 pip install openai # 安装用于解析网页内容的库我们的搜索工具可能会用到。 pip install beautifulsoup4 httpx版本说明截至2024年5月langchain: 版本 0.1.0。LangChain版本迭代较快核心API在0.1.x后趋于稳定。langgraph: 版本 0.0.20。它是较新的库API也在快速演进中。openai: 版本 1.0.0。注意OpenAI库进行了重大版本更新旧版代码可能需要调整。如果遇到版本冲突可以使用pip freeze查看已安装版本并参考官方文档调整。2.3 获取并配置API密钥我们的Agent需要“大脑”LLM和“工具”OpenClaw。OpenAI API Key访问 OpenAI Platform 注册并获取API Key。在代码中通过环境变量配置这是最安全的方式。# 在终端中设置环境变量 (临时) export OPENAI_API_KEY你的-sk-xxx密钥 # Windows: set OPENAI_API_KEY你的-sk-xxx密钥火山引擎OpenClaw访问 火山引擎OpenClaw 了解详情。你可能需要注册火山引擎账号。OpenClaw通常提供API访问端点Endpoint和密钥。其工具可以通过HTTP接口调用。本文为了简化我们将模拟一个“搜索工具”来代表OpenClaw的能力。在实际应用中你需要根据OpenClaw的官方文档将其工具封装成LangChain可调用的Tool对象。2.4 项目结构初始化创建一个清晰的项目文件夹。ai_agent_project/ ├── main.py # 主程序入口 ├── agent_graph.py # LangGraph图定义 ├── tools.py # 自定义工具定义包括模拟的OpenClaw工具 ├── config.py # 配置文件API密钥等 └── requirements.txt # 项目依赖列表在requirements.txt中记录依赖langchain0.1.0 langgraph0.0.20 openai1.0.0 langchain-community beautifulsoup4 httpx python-dotenv # 推荐用于从.env文件加载环境变量3. 核心组件拆解Tool, Agent, Graph在搭建完整智能体之前我们先深入理解LangChain和LangGraph中的几个核心概念。3.1 工具Tool—— Agent的手和脚工具是Agent与外界交互的接口。任何可以被调用的函数、API都可以封装成Tool。一个最简单的Tool示例# tools.py from langchain.tools import tool from typing import Optional tool def search_web(query: str, max_results: Optional[int] 3) - str: 使用模拟的搜索引擎代表OpenClaw查询网络信息。 在实际应用中这里应替换为真实的OpenClaw搜索API调用。 Args: query: 搜索查询词。 max_results: 返回的最大结果数。 Returns: 返回搜索结果的摘要文本。 # 这里是模拟实现。真实情况应调用OpenClaw API。 print(f[模拟搜索] 正在搜索: {query}) # 模拟网络延迟 import time time.sleep(1) # 模拟返回一些结果 simulated_results f 根据对 {query} 的模拟搜索发现以下信息 1. 相关概念A的解释是... 2. 最新的技术动态B指出... 3. 官方文档C中提到了... return simulated_results # 计算器工具 tool def calculator(expression: str) - str: 计算一个数学表达式的值。 try: # 警告使用eval有安全风险仅用于演示。生产环境应用安全库如ast.literal_eval或专用计算库。 result eval(expression) return f{expression} {result} except Exception as e: return f计算错误: {e}关键点使用tool装饰器将一个普通函数转换为LangChain Tool。函数的文档字符串docstring非常重要Agent的LLM会通过它来理解这个工具的用途和参数。输入参数和返回类型应尽量明确。3.2 代理Agent—— 决策核心在LangGraph中“代理”通常被建模为图中的一个节点这个节点的核心工作是根据当前状态决定下一步做什么。这个决策通常由LLM驱动。LangGraph提供了StateGraph来构建图并推荐使用create_react_agent或类似高阶函数来快速创建一个基于ReActReasoning Acting范式的Agent节点。ReAct范式简介Agent循环进行“思考Thought-行动Action-观察Observation”的步骤直到问题解决。3.3 图Graph与状态State—— 工作流引擎这是LangGraph的核心抽象。状态State一个字典dict包含了工作流执行过程中所有需要传递的信息。例如{messages: [...], user_query: ..., search_results: ...}。LangGraph要求你预先定义一个State的TypedDict来描述状态结构。节点Node图中的一个步骤可以是一个函数。它接收当前State执行一些操作如调用LLM、运行工具然后返回更新后的State。边Edge连接节点的路径决定工作流的走向。边可以是固定的也可以根据State的内容动态决定条件边。我们将通过构建一个具体的图来理解这一切。4. 完整实战构建技术助手智能体现在我们将把所有部分组合起来构建我们的“技术助手”智能体。4.1 定义状态State首先我们需要定义工作流中流转的数据结构。# agent_graph.py from typing import TypedDict, List, Annotated, Union from langchain_core.messages import BaseMessage, HumanMessage, AIMessage, ToolMessage import operator # 定义状态结构。我们使用TypedDict来获得更好的类型提示。 class AgentState(TypedDict): # 消息列表记录整个对话和工具调用历史 messages: Annotated[List[BaseMessage], operator.add] # 用户的原始查询 user_query: str # 存储从工具如搜索获得的结果 tool_results: str # 一个标志位表示Agent是否应该继续运行 should_continue: bool解释messages: 这是LangChain对话的核心。Annotated[List[BaseMessage], operator.add]是一个神奇的声明它告诉LangGraph当多个节点修改messages时应该用操作符即列表拼接来合并更新而不是覆盖。这确保了对话历史的完整性。user_query: 保存用户最初的问题。tool_results: 临时存储工具执行后的输出。should_continue: 控制工作流何时结束。4.2 创建工具和模型接下来我们初始化LLM模型和工具集。# agent_graph.py (续) from langchain_openai import ChatOpenAI from langchain.tools import Tool from tools import search_web, calculator # 导入我们之前定义的工具 import os # 初始化LLM。我们使用GPT-4 Turbo以获得更好的推理能力你也可以用gpt-3.5-turbo。 # 确保环境变量OPENAI_API_KEY已设置。 llm ChatOpenAI(modelgpt-4-turbo-preview, temperature0) # 将工具函数包装成LangChain Tool列表 tools [search_web, calculator] # 为LLM绑定工具这样LLM在生成内容时就知道可以调用哪些工具。 llm_with_tools llm.bind_tools(tools)4.3 定义图的节点Nodes我们将定义两个主要节点Agent节点负责思考并决定是回答问题还是调用工具。工具执行节点负责执行Agent选择的工具并将结果返回。# agent_graph.py (续) from langgraph.prebuilt import ToolExecutor from langgraph.graph import StateGraph, END # 创建工具执行器它知道如何调用我们的工具列表。 tool_executor ToolExecutor(tools) def agent_node(state: AgentState) - AgentState: Agent节点调用LLM让它根据对话历史和当前状态决定下一步。 print(\n--- Agent正在思考 ---) # 从状态中获取消息历史 messages state[messages] # 调用绑定了工具的LLM response llm_with_tools.invoke(messages) # 将LLM的响应添加到消息历史中 new_messages [response] return {messages: new_messages} # 返回更新后的状态部分 def tool_node(state: AgentState) - AgentState: 工具执行节点执行Agent在上一步中决定要调用的工具。 print(\n--- 正在执行工具 ---) # 获取上一条消息应该是AIMessage且包含工具调用请求 last_message state[messages][-1] # 检查最后一条消息是否包含工具调用 if not hasattr(last_message, tool_calls) or not last_message.tool_calls: raise ValueError(f最后一条消息没有工具调用: {last_message}) tool_calls last_message.tool_calls tool_messages [] # 遍历所有被调用的工具可能同时调用多个 for tool_call in tool_calls: tool_name tool_call[name] tool_args tool_call[args] print(f执行工具: {tool_name} 参数: {tool_args}) # 使用ToolExecutor执行工具 result tool_executor.invoke(tool_call) # 创建ToolMessage包含工具执行结果并关联到对应的tool_call_id tool_message ToolMessage( contentstr(result), tool_call_idtool_call[id], nametool_name ) tool_messages.append(tool_message) # 返回工具执行结果消息 return {messages: tool_messages}4.4 定义图的边Edges与构建完整图现在我们需要定义节点之间的流转逻辑Agent思考后如果调用了工具就转到工具节点如果直接回答了就结束。# agent_graph.py (续) from langgraph.graph import StateGraph, END def should_continue(state: AgentState) - str: 条件路由函数根据Agent的最后一条消息决定下一步是调用工具还是结束。 返回下一个节点的名称。 last_message state[messages][-1] # 如果最后一条消息包含工具调用就去执行工具 if hasattr(last_message, tool_calls) and last_message.tool_calls: return call_tool # 否则工作流结束 return END # 创建状态图 workflow StateGraph(AgentState) # 添加节点 workflow.add_node(agent, agent_node) workflow.add_node(call_tool, tool_node) # 设置入口点 workflow.set_entry_point(agent) # 添加条件边 workflow.add_conditional_edges( agent, should_continue, # 路由判断函数 { call_tool: call_tool, # 如果返回call_tool则前往call_tool节点 END: END # 如果返回END则结束 } ) # 从工具执行节点无条件跳回Agent节点进行下一步思考 workflow.add_edge(call_tool, agent) # 编译图得到一个可执行的对象 app workflow.compile()图结构解析从agent节点开始。agent节点运行后通过should_continue函数判断。如果LLM决定调用工具就前往call_tool节点。call_tool节点执行完毕后自动跳回agent节点。agent节点再次思考整合工具返回的结果并决定下一步。如此循环直到LLM给出最终答案should_continue返回END工作流终止。这就是LangGraph的核心魅力用清晰的图结构定义了Agent的复杂推理循环。4.5 主程序与运行测试最后我们编写主程序来启动这个智能体。# main.py from agent_graph import app # 导入我们编译好的图应用 from langchain_core.messages import HumanMessage import asyncio async def run_agent(query: str): 异步运行Agent处理查询。 # 初始化状态 initial_state { messages: [HumanMessage(contentquery)], user_query: query, tool_results: , should_continue: True, } print(f用户提问: {query}) print(*50) # 流式运行图应用可以看到每一步的输出 async for event in app.astream(initial_state, stream_modevalues): # 打印每个节点执行后的状态中的最新消息 if messages in event and event[messages]: last_msg event[messages][-1] # 根据消息类型美化输出 if last_msg.type ai: if hasattr(last_msg, tool_calls) and last_msg.tool_calls: print(f Agent决定调用工具: {last_msg.tool_calls}) else: print(f Agent回答: {last_msg.content}) elif last_msg.type tool: print(f️ 工具返回: {last_msg.content[:200]}...) # 截断长输出 print(-*30) # 获取最终状态和最终消息 final_state await app.ainvoke(initial_state) final_message final_state[messages][-1] print(*50) print( 最终答案:) print(final_message.content) if __name__ __main__: # 测试查询 test_queries [ LangChain和LangGraph的主要区别是什么, # 可能触发搜索 计算一下 125 * 8 360 等于多少, # 应触发计算器 今天的天气怎么样, # 我们的模拟搜索工具会处理 ] # 运行第一个查询作为示例 query test_queries[0] asyncio.run(run_agent(query))4.6 运行与结果分析在终端运行程序cd /path/to/ai_agent_project python main.py预期输出示例用户提问: LangChain和LangGraph的主要区别是什么 --- Agent正在思考 --- Agent决定调用工具: [{name: search_web, args: {query: LangChain LangGraph 区别, max_results: 3}, id: call_xyz...}] ------------------------------ --- 正在执行工具 --- 执行工具: search_web 参数: {query: LangChain LangGraph 区别, max_results: 3} ️ 工具返回: 根据对 LangChain LangGraph 区别 的模拟搜索发现以下信息 1. LangChain 是一个用于构建LLM应用的框架提供链、代理、工具等组件... 2. LangGraph 是构建在LangChain之上的库用于创建有状态、多参与者的工作流... 3. 主要区别在于LangChain关注组件化而LangGraph关注流程编排... ------------------------------ --- Agent正在思考 --- Agent回答: 根据最新的信息LangChain和LangGraph的主要区别在于定位和抽象层级...整合了搜索结果的详细回答 最终答案: LangChain和LangGraph的主要区别在于... 此处是整合后的完整、准确的回答流程解读AgentLLM收到问题“LangChain和LangGraph的区别”。LLM判断自身知识可能不够实时或全面决定调用search_web工具。工具节点执行模拟搜索返回结果。Agent节点再次被激活它收到了工具返回的结果将其与自身知识结合生成最终答案。由于这次LLM直接给出了答案没有新的工具调用should_continue返回END工作流结束。5. 常见问题与排查思路在构建和运行AI Agent时你可能会遇到以下问题问题现象可能原因排查思路与解决方案ModuleNotFoundError: No module named langchain1. 未安装LangChain。2. 在错误的Python环境非虚拟环境中运行。1. 确认已激活虚拟环境source ai_agent_env/bin/activate。2. 在虚拟环境中重新安装pip install langchain langgraph。AuthenticationError或Invalid API KeyOpenAI API Key 未设置或错误。1. 检查环境变量OPENAI_API_KEY是否正确设置echo $OPENAI_API_KEY。2. 确保Key有效且有余额。3. 尝试在代码中直接传入Key仅用于测试ChatOpenAI(api_keysk-...)。Agent陷入无限循环不停调用工具1. LLM如gpt-3.5-turbo推理能力不足无法正确判断何时结束。2. 工具的描述docstring不够清晰导致LLM误用。3. 图的条件边逻辑有误。1.升级模型尝试使用gpt-4-turbo-preview。2.优化工具描述在工具的docstring中清晰说明其用途、输入和输出。3.添加最大迭代限制在LangGraph中可以在编译图时设置checkpointer或在外层包装循环计数逻辑。工具调用失败报参数错误1. LLM生成的工具调用参数格式与工具函数定义不匹配。2. 工具函数参数类型声明不明确。1.检查工具定义确保tool装饰的函数有清晰的类型提示和docstring。2.使用Pydantic模型对于复杂参数可以用BaseModel定义LangChain支持将其作为Tool的args_schema。State更新不符合预期对Annotated的归约操作符如operator.add理解有误。记住operator.add用于列表拼接。如果你希望某个状态字段被覆盖而不是追加就不要用Annotated直接定义类型如field_name: str。OpenClaw真实API集成失败API端点、请求格式、认证方式不正确。1. 仔细阅读OpenClaw官方API文档。2. 先用curl或requests库单独测试API调用是否成功。3. 将成功的调用逻辑封装到tool装饰的函数中。程序报错graph相关错误LangGraph API 发生变更。LangGraph仍在快速发展中。务必查阅对应版本的官方文档 LangGraph官方文档 。6. 最佳实践与工程建议将AI Agent从Demo推向生产环境需要考虑更多工程化因素。6.1 工具设计与管理单一职责每个工具应只做一件事并做好。这有助于LLM准确理解和使用。详尽描述工具的docstring是LLM理解它的唯一途径。务必清晰描述功能、输入参数名称、类型、含义、返回值格式。错误处理工具内部必须有健壮的错误处理try-except并返回对人类和LLM都有意义的错误信息而不是堆栈跟踪。速率限制与重试对于调用外部API的工具必须实现速率限制、指数退避重试机制避免被服务商封禁。6.2 提示词Prompt工程系统消息System Message在对话开始时通过系统消息明确设定Agent的角色、能力和行为规范。例如“你是一个专业的技术助手在回答技术问题前可以优先使用搜索工具获取最新信息。”少样本Few-shot示例在系统消息或初始消息中提供一两个Agent正确使用工具的对话示例可以显著提升其工具调用的准确性和规范性。6.3 图的健壮性与可观测性设置超时与最大步数在app.invoke()或循环外设置超时和最大迭代次数防止Agent因逻辑错误或LLM“发疯”而无限运行。日志记录记录每个节点的输入/输出、工具调用详情、LLM的请求与响应。这对于调试和优化至关重要。考虑使用langchain.callbacks。可视化LangGraph提供了将图可视化的方法workflow.get_graph().draw_mermaid()在开发阶段利用它来理解你的工作流。6.4 生产环境部署配置管理将API密钥、模型名称、超时时间等配置项从代码中剥离使用环境变量或配置文件如pydantic-settings管理。异步与并发LangGraph天然支持异步。在生产Web服务中确保使用异步框架如FastAPI来调用app.ainvoke()以高效处理并发请求。缓存对于昂贵的LLM调用或工具调用如搜索相同内容考虑引入缓存层如Redis但要注意缓存内容的时效性。6.5 安全与合规用户输入净化对传入Agent的用户查询进行基本的过滤防止提示词注入攻击。工具权限控制不是所有工具都应对所有用户开放。在设计架构时要考虑基于用户或上下文的工具权限过滤。数据隐私如果工具会处理用户隐私数据或向外部API发送数据必须明确告知用户并获得同意确保符合数据保护法规如GDPR。审核日志记录所有用户查询、Agent决策、工具调用和最终输出用于审计和后续模型改进。7. 总结与进阶方向至此你已经完成了一个功能完整的AI Agent的搭建。我们回顾一下核心步骤定义状态用TypedDict明确工作流中需要流转的数据。创建工具用tool装饰器将功能函数封装成Agent可调用的工具。构建图使用StateGraph定义节点Agent思考、工具执行和边条件路由、固定流转。编译运行将图编译成可执行应用并输入初始状态来运行。这个“技术助手”Agent只是一个起点。基于此架构你可以轻松地进行扩展集成真实OpenClaw工具将search_web函数替换为真实的OpenClaw API调用让你的Agent具备强大的官方工具集。实现多Agent协作LangGraph的核心优势之一是支持多参与者。你可以创建多个具备不同专长如“研究员Agent”、“代码专家Agent”、“文案Agent”的Agent节点让它们在同一个图中协同工作解决更复杂的问题。加入长期记忆通过集成langchain.memory模块如ConversationBufferWindowMemory让Agent记住跨会话的对话历史。连接知识库使用LangChain的RAG检索增强生成组件让Agent能够从你的私有文档如公司Wiki、产品手册中获取信息并回答。构建Web界面使用Gradio或Streamlit快速为你的Agent构建一个聊天机器人界面。AI Agent的开发是一场结合了软件工程、提示词工程和LLM能力的探索。从今天这个可运行的原型出发不断迭代你的工具集、优化提示词、完善工作流你将能够打造出真正强大、实用的智能体应用。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度