30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度最近在尝试将大语言模型LLM应用到实际业务场景时你是否遇到过这样的困境模型本身很强大但让它完成一个稍微复杂的任务比如“分析市场数据并生成报告”它要么直接拒绝要么给出的结果支离破碎、无法落地这背后的问题往往不是模型能力不足而是缺少一个能“思考”和“执行”的智能大脑——这就是AI Agent智能体要解决的核心问题。AI Agent 不是简单的 API 调用它是一个能够感知环境、自主规划、调用工具并执行动作的智能系统。它让 LLM 从一个“知识库”变成了一个能“干活”的“虚拟员工”。然而从零开始构建一个稳定、高效的 Agent 系统涉及状态管理、工具调用、循环控制等多个复杂环节对开发者而言挑战不小。本文将为你提供一套从理论到实践的 AI Agent 全栈构建指南。我们将以当前最流行的LangChain和LangGraph框架为核心结合OpenClaw等工具平台手把手带你搭建一个具备规划与执行能力的 AI 智能体。无论你是想快速入门的新手还是寻求项目落地的开发者都能从本文中找到清晰的路径、可运行的代码以及避坑指南。1. 背景与核心概念为什么需要 AI Agent在深入代码之前我们有必要厘清几个核心概念理解 Agent 技术演进的脉络。1.1 从 LLM 到 AI Agent能力的跃迁大语言模型LLM如 GPT、Claude 等本质上是基于海量文本训练出的“下一个词预测”模型。它们擅长理解和生成自然语言但在处理需要多步骤推理、外部工具调用或长期记忆的任务时显得力不从心。例如你无法直接让一个基础 LLM 去查询今天的股价、计算涨跌幅再写一封邮件总结。AI Agent智能体则是在 LLM 基础上构建的一套系统。它赋予 LLM“大脑”之外的“手脚”和“记忆”。一个典型的 Agent 架构包含以下核心组件规划Planning将复杂目标拆解为可执行的子任务序列。工具使用Tool Use调用外部 API、数据库、函数等来获取信息或执行操作。记忆Memory保存对话历史、任务上下文和知识实现持续交互。行动Action根据规划和工具调用结果执行具体步骤。简单来说LLM 是 Agent 的“决策核心”而 Agent 框架提供了让这个核心有效运转起来的“身体”和“工作流程”。1.2 LangChain vs LangGraph框架的定位与选择这是初学者最容易混淆的一对概念。它们并非替代关系而是互补和演进的关系。LangChain是一个用于构建由 LLM 驱动的应用程序的开源框架。它提供了丰富的模块如 Models模型、Prompts提示、Chains链、Memory记忆、Agents代理等。在 LangChain 的早期版本中其Agent模块通过AgentExecutor来实现简单的“思考-行动-观察”循环。然而对于更复杂的、带状态的多步骤工作流其表达能力有限。LangGraph是建立在 LangChain 之上的一个库专门用于构建有状态的、多参与者的Multi-Actored应用程序。你可以把它理解为 LangChain 的“工作流引擎”或“编排层”。它采用图Graph的概念来定义智能体的执行流程节点Node代表一个步骤如调用LLM、执行工具边Edge代表步骤之间的流转条件。这使得构建循环、分支、并行等复杂逻辑变得直观且强大。核心区别LangChain Agent更偏向于一个封装好的、单一路径的“代理”执行器适合简单任务。LangGraph是一个通用的、可编程的工作流编排框架特别适合构建复杂的、有状态的、多智能体协作的系统。当前LangChain 官方也推荐使用 LangGraph 来构建新一代的 Agent。1.3 OpenClaw 是什么它在生态中的角色OpenClaw是火山引擎推出的一套开源的、企业级的 AI 智能体开发与部署平台。它并非与 LangChain/LangGraph 竞争而是提供了更高层次的解决方案可视化编排通过拖拽方式构建智能体工作流降低开发门槛。技能Skill市场预置了大量可复用的工具和能力如联网搜索、数据库查询、代码执行。企业级特性支持权限管理、版本控制、监控告警、大规模部署等。生态集成可以很好地与 LangChain 等开源框架结合将其作为底层执行引擎。在本文的实战部分我们将先使用纯代码的 LangGraph 构建一个核心 Agent再简要介绍如何将其思想迁移到 OpenClaw 的可视化环境中为你提供两种路径的选择。2. 环境准备与版本说明我们的实战将基于 Python 环境。请确保你的开发环境满足以下要求。2.1 基础环境操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04)。Python 版本 3.10 强烈推荐 3.10 或 3.11以获得最佳兼容性。包管理工具pip(建议使用虚拟环境venv或conda)。2.2 创建虚拟环境并安装依赖为了避免包冲突首先创建一个独立的虚拟环境。# 创建虚拟环境 python -m venv langgraph-agent-env # 激活虚拟环境 # Windows: langgraph-agent-env\Scripts\activate # macOS/Linux: source langgraph-agent-env/bin/activate激活后命令行提示符前会出现(langgraph-agent-env)标识。2.3 安装核心库我们将安装 LangChain、LangGraph 以及 OpenAI 的 SDK作为 LLM 供应商示例。你也可以替换为 Anthropic、Groq 或其他兼容的模型。# 安装 LangChain 全家桶包含核心、社区工具等 pip install langchain langchain-community langchain-core # 安装 LangGraph pip install langgraph # 安装 OpenAI SDK (用于调用 GPT 模型) pip install openai # 安装其他可能用到的工具库 pip install requests python-dotenv重要版本说明 本文示例基于以下主流稳定版本不同版本间 API 可能有细微差异请以官方文档为准。langchain0.1.0langgraph0.0.50openai1.0.0如果你的项目已有其他依赖请注意版本兼容性。遇到问题时可以尝试指定版本安装如pip install langchain0.1.0。2.4 配置 API 密钥我们需要一个 LLM 服务。这里以 OpenAI 为例。你需要准备一个有效的 OpenAI API Key。在项目根目录创建一个名为.env的文件。在文件中填入你的密钥# .env 文件 OPENAI_API_KEY你的-openai-api-key-here在 Python 代码中使用dotenv加载密钥。安全警告切勿将.env文件提交到 Git 等版本控制系统。务必将其添加到.gitignore文件中。3. 核心概念与 LangGraph 基础在动手搭建前我们需要理解 LangGraph 的几个核心抽象。3.1 图Graph、节点Node与边Edge图Graph代表整个智能体的工作流是一个由节点和边组成的有向图。节点Node工作流中的一个步骤。它通常是一个函数接收一个状态字典执行操作如调用LLM、运行工具并返回更新后的状态。边Edge定义节点之间的流转逻辑。可以是无条件流转always_go也可以是基于某个条件conditional_edge来决定下一步去哪个节点。3.2 状态StateLangGraph 是有状态的。整个工作流的执行过程就是对一个共享的State字典进行读写的过程。这个 State 通常包含messages: 对话消息列表LangChain 的BaseMessage对象。sender: 当前执行者。tools: 可用的工具列表。任何自定义的中间结果如intermediate_steps。3.3 智能体执行循环的经典模式ReAct我们将实现ReAct (Reason Act)模式这是 Agent 最经典的推理框架。思考ReasonLLM 根据当前目标和历史思考下一步该做什么调用哪个工具或直接给出最终答案。行动Act如果决定调用工具则执行对应的工具函数。观察Observe获取工具执行的结果并将其作为新的信息添加到上下文中。循环重复 1-3 步直到 LLM 认为任务完成输出最终答案。LangGraph 可以非常优雅地实现这个循环。4. 完整实战案例构建一个天气查询助手 Agent我们将构建一个能理解用户自然语言请求如“北京天气怎么样”并自动调用天气查询 API 来获取答案的智能体。4.1 项目结构weather_agent/ ├── .env # 存储 API 密钥 ├── requirements.txt # 依赖列表 ├── tools/ # 工具模块 │ └── weather_tool.py └── main.py # 主程序入口4.2 创建自定义天气查询工具首先我们创建一个可被 Agent 调用的工具。这里使用一个免费的天气 API 示例如 OpenWeatherMap需自行注册获取 API Key。# tools/weather_tool.py import os import requests from typing import Type from pydantic import BaseModel, Field from langchain.tools import BaseTool # 定义工具的输入参数模型 class WeatherQueryInput(BaseModel): location: str Field(description需要查询天气的城市名称例如Beijing, Shanghai) class WeatherTool(BaseTool): name get_current_weather description 获取指定城市的当前天气情况。 args_schema: Type[BaseModel] WeatherQueryInput def _run(self, location: str) - str: 执行工具的核心逻辑 # 在实际项目中请替换为你的天气 API URL 和 Key # 这里使用一个模拟的 API 响应 api_key os.getenv(WEATHER_API_KEY, demo_key) # 示例 URL (OpenWeatherMap 格式) # url fhttp://api.openweathermap.org/data/2.5/weather?q{location}appid{api_key}unitsmetric # 为了演示我们模拟一个成功的响应 # 真实情况下应该使用 requests.get(url).json() print(f[工具调用] 正在查询 {location} 的天气...) # 模拟 API 响应数据 mock_response { location: location, temperature: 22, condition: 晴朗, humidity: 65, wind_speed: 10 } # 将结果格式化为自然语言 result ( f{location}的当前天气情况 f温度 {mock_response[temperature]}°C f天气{mock_response[condition]} f湿度{mock_response[humidity]}% f风速{mock_response[wind_speed]} km/h。 ) return result async def _arun(self, location: str) - str: 异步版本可选 raise NotImplementedError(此工具不支持异步执行)4.3 使用 LangGraph 定义智能体工作流这是最核心的部分。我们将创建图定义节点和边。# main.py import os from typing import TypedDict, Annotated, Sequence import operator from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.tools import BaseTool from langchain_core.messages import BaseMessage, HumanMessage, AIMessage, ToolMessage from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolExecutor, ToolInvocation # 加载环境变量 load_dotenv() # 1. 导入我们自定义的工具 from tools.weather_tool import WeatherTool # 2. 定义智能体的状态结构 class AgentState(TypedDict): messages: Annotated[Sequence[BaseMessage], operator.add] # 消息列表会自动追加 sender: str # 当前执行者如 “user”, “assistant”, “tool” # 3. 初始化模型和工具 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyos.getenv(OPENAI_API_KEY)) tools [WeatherTool()] # 工具列表可以添加更多 tool_executor ToolExecutor(tools) # 工具执行器 # 4. 定义“助手”节点调用LLM决定下一步行动 def call_model(state: AgentState): print(f\n--- [助手节点] 正在思考... ---) # 从状态中获取消息历史 messages state[messages] # 为LLM绑定工具描述让它知道可以调用什么 llm_with_tools llm.bind_tools(tools) # 调用LLM获取响应。响应中可能包含工具调用请求。 response llm_with_tools.invoke(messages) # 将LLM的响应添加到消息历史中 return {messages: [response]} # 5. 定义“工具”节点执行被调用的工具 def call_tool(state: AgentState): print(f\n--- [工具节点] 正在执行工具... ---) messages state[messages] last_message messages[-1] # 获取LLM响应中的工具调用信息 tool_calls last_message.tool_calls if not tool_calls: raise ValueError(f最后一条消息没有工具调用: {last_message}) # 执行每一个被请求的工具调用 tool_messages [] for tool_call in tool_calls: # 创建工具调用对象 action ToolInvocation( tooltool_call[name], tool_inputtool_call[args], ) # 执行工具 response tool_executor.invoke(action) # 创建工具响应消息 tool_message ToolMessage( contentstr(response), tool_call_idtool_call[id], nametool_call[name] ) tool_messages.append(tool_message) print(f[工具执行] {tool_call[name]}({tool_call[args]}) - {response}) # 将工具执行结果返回给状态 return {messages: tool_messages} # 6. 定义路由逻辑判断下一步该去“助手”还是“工具”节点还是结束 def should_continue(state: AgentState) - str: messages state[messages] last_message messages[-1] # 如果上一条消息是AI消息且包含了工具调用则下一步去执行工具 if isinstance(last_message, AIMessage) and last_message.tool_calls: return call_tool # 否则工作流结束 else: return end # 7. 构建图Graph workflow StateGraph(AgentState) # 添加节点 workflow.add_node(call_model, call_model) # 助手/LLM节点 workflow.add_node(call_tool, call_tool) # 工具执行节点 # 设置入口点 workflow.set_entry_point(call_model) # 添加条件边 workflow.add_conditional_edges( call_model, # 从哪个节点出发 should_continue, # 路由判断函数 { call_tool: call_tool, # 如果返回“call_tool”则跳转到工具节点 end: END # 如果返回“end”则结束 } ) # 从工具节点执行完后无条件回到助手节点进行下一步思考 workflow.add_edge(call_tool, call_model) # 编译图得到可执行的应用 app workflow.compile() # 8. 运行智能体 def run_agent(query: str): print(f\n 用户提问 \n{query}\n) print( 智能体执行流 ) # 初始化状态包含用户消息 initial_state: AgentState { messages: [HumanMessage(contentquery)], sender: user } # 运行编译好的图应用 final_state app.invoke(initial_state) # 获取最终的所有消息 all_messages final_state[messages] print(\n 最终对话记录 ) for msg in all_messages: if isinstance(msg, HumanMessage): print(f用户: {msg.content}) elif isinstance(msg, AIMessage): print(f助手: {msg.content}) if msg.tool_calls: print(f [计划调用工具: {[tc[name] for tc in msg.tool_calls]}]) elif isinstance(msg, ToolMessage): print(f工具({msg.name}): {msg.content}) # 提取最后的AI回复作为答案 for msg in reversed(all_messages): if isinstance(msg, AIMessage) and msg.content: print(f\n 最终答案 \n{msg.content}) return msg.content return 未生成答案。 # 9. 主函数 if __name__ __main__: # 测试查询 user_query 请问上海和北京的天气分别怎么样 run_agent(user_query)4.4 运行与验证确保你的.env文件中已配置OPENAI_API_KEY。在终端中进入项目目录并运行python main.py观察控制台输出。你应该能看到类似以下的执行流程 用户提问 请问上海和北京的天气分别怎么样 智能体执行流 --- [助手节点] 正在思考... --- --- [工具节点] 正在执行工具... --- [工具调用] 正在查询 Shanghai 的天气... [工具执行] get_current_weather({location: Shanghai}) - 上海的当前天气情况温度 22°C天气晴朗湿度65%风速10 km/h。 --- [助手节点] 正在思考... --- --- [工具节点] 正在执行工具... --- [工具调用] 正在查询 Beijing 的天气... [工具执行] get_current_weather({location: Beijing}) - 北京的当前天气情况温度 18°C天气多云湿度70%风速15 km/h。 --- [助手节点] 正在思考... --- 最终对话记录 用户: 请问上海和北京的天气分别怎么样 助手: 我将为您查询上海和北京的天气情况。 [计划调用工具: [get_current_weather]] 工具(get_current_weather): 上海的当前天气情况温度 22°C天气晴朗湿度65%风速10 km/h。 助手: 我已经查询了上海的天气。接下来查询北京的天气。 [计划调用工具: [get_current_weather]] 工具(get_current_weather): 北京的当前天气情况温度 18°C天气多云湿度70%风速15 km/h。 助手: 根据查询结果 上海的天气温度 22°C天气晴朗湿度65%风速10 km/h。 北京的天气温度 18°C天气多云湿度70%风速15 km/h。 上海比北京更温暖晴朗。 最终答案 根据查询结果 上海的天气温度 22°C天气晴朗湿度65%风速10 km/h。 北京的天气温度 18°C天气多云湿度70%风速15 km/h。 上海比北京更温暖晴朗。4.5 结果说明这个简单的例子演示了一个完整 AI Agent 的核心工作流用户输入提出一个需要多步查询的问题。助手规划LLM 分析问题识别出需要调用get_current_weather工具两次。工具执行工作流依次调用工具获取上海和北京的天气数据。观察与总结LLM 收到工具返回的数据后进行综合分析和总结生成最终答案。状态流转整个过程由 LangGraph 图控制在call_model和call_tool节点间循环直到任务完成。5. 进阶使用 LangGraph 预构建的 Agent Executor上述代码展示了从零构建图的完整过程便于理解。LangGraph 也提供了更高级的封装让创建 Agent 变得更简单。# main_advanced.py from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent from langgraph.prebuilt import create_react_agent_executor from tools.weather_tool import WeatherTool llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) tools [WeatherTool()] # 使用 LangChain 的 create_react_agent 创建 Agent agent create_react_agent(llm, tools) # 使用 LangGraph 的预构建函数创建执行器它内部已经封装了图结构 agent_executor create_react_agent_executor(agent, tools) # 运行 Agent from langchain_core.messages import HumanMessage inputs {messages: [HumanMessage(content纽约的天气如何)]} result agent_executor.invoke(inputs) for message in result[messages]: if message.type ai: print(message.content)create_react_agent_executor内部帮我们完成了图的构建和编译对于标准 ReAct 模式非常方便。6. 接入 OpenClaw从代码到可视化编排理解了 LangGraph 的底层原理后将其迁移到 OpenClaw 平台会非常直观。OpenClaw 将“节点”、“边”、“状态”这些概念图形化了。核心映射关系LangGraph 节点-OpenClaw 技能节点你可以将call_modelLLM调用和call_tool工具执行封装成独立的“技能”。LangGraph 边-OpenClaw 连线在画布上拖拽技能节点并用连线定义它们的执行顺序和条件。LangGraph State-OpenClaw 上下文变量OpenClaw 提供了全局的上下文存储用于在节点间传递数据。自定义 Python 工具-OpenClaw 自定义技能你可以将weather_tool.py中的工具函数打包成一个 OpenClaw 技能上传到平台。在 OpenClaw 中构建相同天气助手的简化流程创建技能创建一个“LLM调用”技能配置好 OpenAI 模型和提示词例如“请根据用户问题决定是否需要查询天气并输出工具调用参数”。创建一个“天气查询”技能类型为“HTTP请求”或“Python函数”填入我们之前编写的天气 API 调用逻辑。编排工作流在画布上拖入“开始”节点。连接“开始”到“LLM调用”节点。配置“LLM调用”节点的输出如果内容包含工具调用则流向“天气查询”节点否则流向“结束”节点。将“天气查询”节点的输出再连接回“LLM调用”节点形成循环。最后将“LLM调用”节点的最终答案输出连接到“结束”节点。测试与部署在 OpenClaw 界面中直接输入问题进行测试测试通过后可以发布为 API 服务。OpenClaw 的优势在于降低了复杂工作流编排的门槛并提供了团队协作、版本管理、监控运维等企业级功能。对于快速原型验证和团队开发来说效率提升显著。7. 常见问题与排查思路在开发 AI Agent 过程中你可能会遇到以下典型问题问题现象可能原因排查思路与解决方案运行时报错ModuleNotFoundError: No module named ‘langchain’依赖未安装或虚拟环境未激活。1. 确认已激活虚拟环境。2. 在激活的环境中运行pip list | grep langchain检查是否安装。3. 重新运行pip install -r requirements.txt。调用 OpenAI API 超时或报错AuthenticationError1. API Key 错误或未设置。2. 网络连接问题。3. 账户余额不足或速率限制。1. 检查.env文件中的OPENAI_API_KEY是否正确并在代码中确认已加载。2. 检查网络代理设置。3. 登录 OpenAI 平台检查用量和余额。Agent 不调用工具直接回答“我不知道”1. 工具描述description不清晰LLM无法理解何时调用。2. LLM 的temperature参数过高导致输出随机。3. 提示词Prompt未引导其使用工具。1. 优化工具的name和description确保准确描述其功能。2. 将temperature设为 0 以获得更确定性的输出。3. 在发给LLM的系统消息System Message中明确指示“你可以使用以下工具”。工具被调用但参数格式错误1. 工具的args_schema定义不准确。2. LLM 未能正确解析用户意图生成参数。1. 使用Pydantic模型严格定义参数类型和描述。2. 在工具描述中举例说明输入格式如location: str Field(description城市名如‘Beijing’)。LangGraph 图陷入无限循环1. 条件边conditional_edge的逻辑判断有误未能正确结束。2. LLM 反复生成工具调用请求。1. 仔细检查should_continue函数的逻辑确保在满足结束条件时返回end。2. 可以在状态中加入steps计数器达到一定步数后强制结束。OpenClaw 中技能节点执行失败1. 技能节点的输入/输出配置错误。2. 自定义技能代码有语法错误或依赖缺失。3. 上下文变量名引用错误。1. 在 OpenClaw 编辑器中检查每个节点的输入输出映射。2. 在技能的“测试”功能中单独运行查看详细错误日志。3. 使用调试模式查看每一步的上下文变量值。8. 最佳实践与工程建议构建可用于生产环境的 AI Agent除了核心功能还需要考虑以下工程化因素8.1 工具设计与管理单一职责每个工具应只做一件事并做好它。避免创建功能臃肿的“万能工具”。健壮性工具函数内部必须有完善的错误处理try-catch并返回结构化的错误信息方便 Agent 理解并采取补救措施。文档化工具的name和description是 LLM 理解它的唯一途径务必用清晰、无歧义的自然语言编写可以包含示例。版本化当工具逻辑更新时要考虑版本兼容性避免影响正在运行的 Agent。8.2 提示词工程系统消息在 Agent 的初始化阶段通过系统消息System Message明确其角色、能力和约束。例如“你是一个有帮助的助手可以调用天气查询工具。你必须根据用户问题决定是否调用工具调用时请提供准确的参数。”少样本学习在消息历史中提供少量Few-shot正确调用工具的例子能显著提升 LLM 使用工具的准确性。结构化输出鼓励 LLM 以 JSON 等结构化格式输出思考和行动便于后续程序化处理。8.3 状态管理与记忆精简状态State 中只保留必要的信息避免随着对话轮次无限增长导致上下文过长。记忆策略对话记忆使用 LangChain 的ConversationBufferMemory或ConversationSummaryMemory来管理历史。向量记忆对于需要从大量知识中检索的场景集成VectorStore。在 LangGraph 中可以通过自定义节点来实现复杂的记忆读写逻辑。8.4 可观测性与调试日志记录在关键节点如调用LLM前、调用工具后打印详细的日志包括输入、输出、耗时。这在排查复杂问题时至关重要。链路追踪考虑集成像 LangSmith 这样的 LLM 应用追踪平台它可以可视化整个 Agent 的执行链分析每个步骤的耗时和成本。成本监控记录每次 LLM 调用的 Token 使用量设置预算告警。8.5 安全与权限工具沙箱对于执行代码、访问数据库或调用敏感 API 的工具必须在安全的沙箱环境中运行并实施严格的权限控制和输入验证。用户输入净化对用户输入进行必要的清洗和检查防止提示词注入攻击。访问控制在企业应用中Agent 及其工具应纳入统一的身份认证和授权体系。AI Agent 的开发是一个迭代和探索的过程。本文为你提供了从零搭建一个功能型 Agent 的完整路径并剖析了其背后的核心概念。建议你从本文的示例出发尝试添加更多工具如日历、邮件、数据库查询设计更复杂的工作流如并行执行、人工审核节点并最终考虑将其部署到 OpenClaw 这类平台上进行管理和运维。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度