LangGraph Server 是一个专门用来部署和运行 AI 智能体的服务。简单说，你写了一个能对话、能调用工具的 AI 应用（比如客服机器人），用 LangGraph Server 就能一键把它变成一个真正的 API 服务，可以通过 HTTP 请求来调用它。LangGraph server还包含了LangSmith，它可以把流程图可视化，能够方便的追踪运行情况、运行指标和日志等。基于LangGraph框架。并且支持热重载，在server启动的情况下，修改代码保存后就能够在网页上面直接看出来。

它帮你解决了：

• 不用自己搭服务器框架（FastAPI、WebSocket 这些）
• 自动处理对话的存储和恢复
• 提供可视化调试界面，能看 AI 每一步在想什么

---

第一步：安装命令行工具

在开始之前，你需要先安装 LangGraph 的命令行工具：

# 用 uv 安装（推荐）
uv tool install "langgraph-cli[inmem]"

# 或者用 pipx 安装（效果一样）
pipx install "langgraph-cli[inmem]"

为什么要装这个？ 后面的 langgraph new、langgraph dev 这些命令都来自这个工具包。[inmem] 表示安装内存存储的额外功能，方便本地开发。

装好后可以验证一下：

langgraph --version
# 应该显示版本号，比如 0.1.0

---

第二步：初始化项目

# 创建项目
langgraph new my-agent-project --template new-langgraph-project-python
cd my-agent

这一步做了什么？

• 创建了项目文件夹
• 生成了 pyproject.toml 和 uv.lock（管理依赖）
• 创建了 .venv 虚拟环境并装好依赖
• 生成了 langgraph.json 配置文件
• 创建了 src/agent.py 示例代码

---

第三步：理解核心概念——为什么有个“图”？

LangGraph 的核心思想是：把 AI 的思考过程画成一张流程图。

比如一个简单的客服机器人：

用户发消息 → 调用大模型 → 需要查订单？→ 是 → 调用查订单工具 → 返回结果
                            ↓ 否
                         直接回复

这张流程图在 LangGraph 里就叫“图”（Graph）。每个方框叫“节点”（Node），箭头叫“边”（Edge）。

为什么要用图？

• 比写一堆 if-else 更清晰
• 方便调试：你能看到 AI 走到了哪个节点
• 容易修改：加一个功能就是加一个节点和几条连线

---

第四步：写你的 AI 逻辑

打开 src/agent.py，默认代码是这样的：

"""LangGraph single-node graph template.

Returns a predefined response. Replace logic and configuration as needed.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Dict

from langgraph.graph import StateGraph
from langgraph.runtime import Runtime
from typing_extensions import TypedDict


# 第一步：定义配置参数
# 这些是可以在调用时动态修改的配置，比如切换模型、调整温度等
class Context(TypedDict):
    """Context parameters for the agent.

    Set these when creating assistants OR when invoking the graph.
    See: https://langchain-ai.github.io/langgraph/cloud/how-tos/configuration_cloud/
    """

    my_configurable_param: str  # 可以改成你需要的配置项，比如 model_name


# 第二步：定义状态
# 状态就是数据在这个图里流转时的"包裹"，每个节点接收状态，处理后返回新状态
@dataclass
class State:
    """Input state for the agent.

    Defines the initial structure of incoming data.
    See: https://langchain-ai.github.io/langgraph/concepts/low_level/#state
    """

    changeme: str = "example"  # 改成你需要的字段，比如 messages、query 等


# 第三步：定义节点
# 节点是图中的一个个处理单元，每个节点接收状态，返回更新后的状态
async def call_model(state: State, runtime: Runtime[Context]) -> Dict[str, Any]:
    """Process input and returns output.

    Can use runtime context to alter behavior.
    """
    # 这里写你的 AI 逻辑
    # 比如调用大模型、查数据库、执行工具等
    return {
        "changeme": "output from call_model. "
        f"Configured with {(runtime.context or {}).get('my_configurable_param')}"
    }


# 第四步：构建图
# 把节点用边连接起来，形成流程图
graph = (
    StateGraph(State, context_schema=Context)  # 创建图，指定状态和配置的类型
    .add_node(call_model)                      # 把节点加进去
    .add_edge("__start__", "call_model")       # 设置入口：从开始到 call_model
    .compile(name="New Graph")                 # 编译成可运行的应用
)

这个文件在做什么？

1. 定义了一个叫 chatbot 的节点，它接收对话历史，返回回复
2. 画了一张只有这一个节点的流程图
3. 编译成可运行的应用

实际开发中，你会有多个节点（比如“判断意图”、“查数据库”、“生成回复”），通过箭头连起来。

你需要改的地方：

1. State（状态）：改成你需要的字段

   @dataclass
   class State:
       messages: list = []      # 对话历史
       user_query: str = ""     # 用户输入
   

2. Context（配置）：改成你需要的可调参数

   class Context(TypedDict):
       model: str               # 用哪个模型
       temperature: float       # 温度参数
   

3. call_model（节点函数）：写上你的 AI 逻辑

   async def call_model(state: State, runtime: Runtime[Context]) -> Dict[str, Any]:
       # 获取配置
       model = runtime.context.get("model", "gpt-4")
       
       # 调用大模型
       response = await llm.ainvoke(state.messages)
       
       # 返回更新后的状态
       return {"messages": state.messages + [response]}
   

---

第五步：本地开发和调试

# 启动开发服务器
uv run langgraph dev

启动后你会看到三个地址：

• http://localhost:2024 — API 服务地址
• http://localhost:2024/docs — 自动生成的 API 文档（可以在这里测试）
• https://...studio... — LangGraph Studio 可视化调试界面

LangGraph Studio 是什么？
它是一个网页版的可视化工具，打开后你能看到：

• 你的流程图长什么样
• 用户输入后，消息怎么在各个节点间流动
• 每个节点返回了什么数据
• 调用了哪些工具

不用自己打日志，界面里全能看到。

---

第六步：部署上线

方式一：LangGraph Cloud（官方托管）

# 把代码推送到 GitHub
git add .
git commit -m "first commit"
git push

# 登录 LangSmith 平台
# 选择你的仓库，点击部署
# 自动获得一个 https://xxx.langgraph.app 的地址

方式二：自己用 Docker 部署

# 在项目目录运行
langgraph up

# 访问 http://localhost:8123

---

命令速查

你想做什么	用什么命令
安装工具	uv tool install "langgraph-cli[inmem]"
新建项目	langgraph new 项目名
添加新依赖	uv add 包名
启动开发服务器	uv run langgraph dev
本地生产测试	langgraph up
运行 Python 脚本	uv run python xxx.py

---

你可能遇到的问题

Q: langgraph 命令找不到？
说明没装好，重新运行 uv tool install "langgraph-cli[inmem]"

Q: 为什么要用 uv run 前缀？
因为项目依赖装在 .venv 虚拟环境里，uv run 会自动用虚拟环境里的命令和 Python，不用手动激活。

Q: LangSmith 和 LangGraph 什么关系？
LangGraph 是框架（写代码用的），LangSmith 是平台（部署、调试、监控用的）。本地开发时打开的 Studio 界面就是 LangSmith 提供的。部署到云端也是用 LangSmith 的平台。可以理解为：LangGraph 是引擎，LangSmith 是控制台。