LangChain LangGraph Agent开发全流程：从工具定义到图谱编排2026实战

LangChain LangGraph Agent开发全流程：从工具定义到图谱编排2026实战

LangGraph是LangChain生态中专门用于构建有状态、多步骤AI Agent的框架，它将Agent的执行流程抽象为状态图（StateGraph），支持循环、分支、并行等复杂控制流。2026年，LangGraph已成为Agent开发的事实标准，其 create_react_agent 函数将推理循环、工具调用和响应格式化封装为一键编排，开发者从工具定义到部署上线的全流程只需数小时。本教程将完整演示LangGraph Agent的开发全流程。

一键编排
create_react_agent
多工具
自动选择调用
MemorySaver
记忆持久化
图谱可视化
StateGraph编排

一、LangGraph概述与核心架构

LangGraph构建在LangChain的基础之上，但引入了图结构来管理Agent执行流程。其核心抽象包括：State（在节点间传递的共享状态）、Node（执行具体逻辑的函数节点）、Edge（连接节点的边，支持条件分支）。这种设计使Agent的执行路径可视化、可调试、可中断恢复。

与原始LangChain的AgentExecutor相比，LangGraph的优势在于：支持循环结构（ReAct推理循环）、原生状态管理、断点恢复、人工干预（human-in-the-loop）以及图谱可视化。2026年LangChain官方已将LangGraph作为Agent开发的首选方案。

二、工具定义：@tool装饰器与Tool类

工具是Agent与外部世界交互的接口。LangGraph继承LangChain的工具定义体系，提供两种定义方式：

方式一：@tool装饰器（推荐）

from langchain_core.tools import tool

@tool
def search_web(query: str) -> str:
    """搜索互联网获取实时信息。
    
    Args:
        query: 搜索关键词
    """
    # 接入搜索API（如Tavily、SerpAPI）
    return f"关于'{query}'的搜索结果..."

@tool
def query_database(sql: str) -> str:
    """执行SQL查询获取数据库信息"""
    # 实际接入数据库执行查询
    return f"查询结果: {sql}"

@tool
def run_python_code(code: str) -> str:
    """执行Python代码并返回结果"""
    try:
        result = eval(code)
        return str(result)
    except Exception as e:
        return f"执行错误: {e}"

  
方式二：Tool类（适合封装已有函数）


LangChain LangGraph Agent开发全流程：从工具定义到图谱编排2026实战

  
from langchain_core.tools import Tool

def _api_call(endpoint: str) -> str:
    import requests
    resp = requests.get(f"https://api.example.com/{endpoint}")
    return resp.text

api_tool = Tool(
    name="api_call",
    description="调用外部REST API获取数据",
    func=_api_call
)

  
无论哪种方式，工具的 name、description 和 参数类型注解 都至关重要——模型依靠这些信息决定何时调用哪个工具。


  
三、Agent创建：create_react_agent

  
有了模型和工具，创建Agent只需一行核心代码：

  
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# 初始化模型
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 定义工具列表
tools = [search_web, query_database, run_python_code, api_tool]

# 一键创建Agent
agent = create_react_agent(llm, tools)

# 调用Agent
response = agent.invoke({
    "messages": [{"role": "user", "content": "查询用户表中有多少条记录，然后计算平均值"}]
})
print(response["messages"][-1].content)

  
create_react_agent 内部自动完成三件事：（1）将工具绑定到模型（bind_tools）；（2）构建agent节点处理推理和工具调用决策；（3）构建tools节点执行工具并返回结果。Agent在运行时自动判断是否需要调用工具、调用哪个工具，直到完成任务。


  
四、记忆配置：MemorySaver持久化

  
通过 checkpointer 参数配置检查点，Agent即可具备跨会话记忆能力：

  
from langgraph.checkpoint.memory import MemorySaver

memory = MemorySaver()
agent = create_react_agent(llm, tools, checkpointer=memory)

# 多轮对话 - 通过thread_id保持上下文
config = {"configurable": {"thread_id": "user_001"}}

# 第一轮
agent.invoke(
    {"messages": [{"role": "user", "content": "帮我搜索一下2026年AI Agent最新进展"}]},
    config=config
)

# 第二轮 - Agent记住上一轮的搜索内容
result = agent.invoke(
    {"messages": [{"role": "user", "content": "根据刚才的搜索结果，总结三个重点"}]},
    config=config
)

  
生产环境建议使用持久化存储后端，如 SqliteSaver（SQLite）或 PostgresSaver（PostgreSQL），确保服务重启后记忆不丢失。


  
五、多工具编排与自动选择

  
LangGraph Agent的强大之处在于多工具自动编排。当配置多个工具时，模型会根据用户意图自动选择最合适的工具，甚至在一次任务中串联调用多个工具：

  

    
工具类型典型用途示例

    
      
搜索工具获取实时信息Tavily Search

      
代码执行工具运行计算/数据处理Python REPL

      
数据库查询工具读取业务数据SQL Database

      
API调用工具对接外部服务REST/Webhook

      
文件操作工具读写本地文件File I/O

    
  

  
例如用户问"查询上周销售额并生成图表"，Agent会自动先调用数据库查询工具获取数据，再调用代码执行工具用matplotlib生成图表，整个过程无需人工干预。


  
六、图谱可视化与状态管理

  
LangGraph的图谱可以可视化展示，帮助开发者理解和调试Agent的执行流程：

  
# 获取Agent的图谱结构
graph = agent.get_graph()

# 可视化（需要安装pygraphviz）
from IPython.display import Image
Image(graph.draw_mermaid_png())

# 查看状态 schema
print(agent.get_schema())

# 流式输出 - 实时查看Agent推理过程
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "分析最近30天的用户增长趋势"}]},
    config=config,
    stream_mode="values"
):
    last_msg = chunk["messages"][-1]
    if hasattr(last_msg, "tool_calls"):
        print(f"调用工具: {last_msg.tool_calls}")
    elif last_msg.content:
        print(f"输出: {last_msg.content[:100]}")

  
状态管理是LangGraph的核心优势——每次工具调用后，状态自动保存到检查点。如果执行中途出错，可以从最近检查点恢复，无需从头开始。这种断点恢复能力对长时间运行的任务至关重要。


  
七、部署上线：LangGraph Server

  
LangGraph提供生产级部署方案 LangGraph Server，支持将Agent打包为独立服务，具备自动扩缩容、状态持久化、流式输出等能力：

  
# langgraph.json 配置文件
{
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "env": ".env"
}

# agent.py
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.postgres import PostgresSaver

graph = create_react_agent(llm, tools, checkpointer=PostgresSaver(...))

# 启动服务: langgraph up
# 部署API自动提供 /invoke /stream /history 等端点

  
部署后可通过REST API或SDK调用Agent，支持流式输出（SSE）、异步调用和历史记录查询，满足生产环境的各种集成需求。


  
八、FAQ常见问题


  

    
Q1：LangGraph和LangChain AgentExecutor有什么区别？

    
AgentExecutor是LangChain早期的Agent执行器，已不推荐使用。LangGraph是其继任者，支持循环图结构、原生状态管理、断点恢复、人工干预和可视化调试。2026年所有新项目应使用LangGraph。

  


  

    
Q2：@tool装饰器的docstring有什么作用？


LangChain LangGraph Agent开发全流程：从工具定义到图谱编排2026实战

    
docstring是工具描述的核心来源，模型通过它判断何时调用该工具。描述应清晰说明工具功能、适用场景和参数含义。建议同时添加Args段落说明每个参数，LangGraph会自动提取为工具schema。

  


  

    
Q3：Agent如何决定调用哪个工具？

    
模型通过bind_tools机制将工具schema注入上下文，在推理时根据用户意图和工具描述匹配最合适的工具。temperature=0可提高工具选择的确定性，减少误调用。

  


  

    
Q4：如何限制Agent的工具调用次数？

    
通过 recursion_limit 参数控制，如 config={"recursion_limit": 20}。默认值25，超出会抛出RecursionError。合理设置可防止无限循环和token浪费。

  


  

    
Q5：LangGraph Server需要付费吗？

    
LangGraph本身是开源免费的。LangGraph Server（自托管）也免费。LangGraph Cloud（托管云服务）提供免费额度和付费计划，适合不想管理基础设施的团队。两者API兼容，可随时迁移。

  


  
本教程完整演示了LangGraph Agent从工具定义、Agent创建、记忆配置、多工具编排、图谱可视化到部署上线的全流程。2026年，LangGraph已成为构建生产级Agent的标准框架，其图谱编排能力和状态管理体系为复杂AI应用提供了坚实基础。