11.LangGraph 平台功能

LangGraph 平台是 LangGraph 生态系统中承上启下的关键组件。当在本地开发环境中完成图结构的构建与调试后，下一步自然是将应用部署到生产环境。LangGraph 平台不仅提供了从代码到服务的完整部署链路，还内置了可视化调试、助手管理、线程追踪等一整套运维工具。这套平台的设计初衷，是让开发者专注于业务逻辑本身，而非纠缠于基础设施的搭建。

LangGraph 平台架构

理解 LangGraph 平台的架构，有助于在部署和运维时做出更合理的技术决策。整个平台采用控制平面与数据平面分离的设计模式，这种架构在云原生应用中相当常见，但 LangGraph 针对智能体应用的特殊性做了专门优化。

核心组件

LangGraph 平台由六个紧密协作的组件构成。LangGraph Server 是整个平台的核心，它封装了一套标准化的 API，用于管理智能体的生命周期、状态持久化和任务调度。这个服务器不是简单的 HTTP 服务，而是集成了任务队列、检查点机制和流式响应的完整运行时环境。

LangGraph CLI 是开发者与平台交互的主要工具。通过简单的命令，可以完成从本地开发到生产部署的全流程。CLI 内部封装了 Docker 操作、依赖管理和配置解析等复杂逻辑，对外提供简洁的接口。

LangGraph Studio 是专为智能体调试设计的可视化 IDE。它能实时展示图的执行路径、节点状态变化和消息流转，支持与 LangSmith 集成进行深度追踪。Studio 的两种工作模式——图模式和聊天模式——分别面向开发者和业务用户。

Python/JS SDK 提供了编程式访问平台的能力。无论是创建助手、管理线程，还是触发后台任务，都可以通过 SDK 在代码中完成。SDK 同时支持同步和异步调用，适配不同的编程范式。

Remote Graph 是一个巧妙的设计，它让远程部署的图可以像本地对象一样被调用。这种抽象屏蔽了网络通信的细节，使得在本地代码中组合多个远程服务变得异常简单。

控制平面和数据平面则是平台运维的两大支柱。控制平面负责部署管理、配置下发和状态监控，数据平面则承载实际的计算负载和数据存储。

控制平面与数据平面

控制平面运行在 LangChain 的云基础设施上，提供 Web UI 和 REST API 两种交互方式。通过控制平面，可以创建部署、更新配置、查看日志和监控资源使用。每个部署在创建时，控制平面会自动生成一个独立的 Postgres 数据库实例，用于存储检查点和长期记忆。

数据平面由部署在客户环境中的 LangGraph Server 实例组成。这些服务器通过轮询机制与控制平面保持同步，获取最新的配置和代码版本。数据平面包含完整的运行时环境：Postgres 数据库、Redis 任务队列和自动扩缩容的计算资源。对于 Cloud SaaS 部署，数据平面也托管在 LangChain 的云上；而对于自托管方案，数据平面则部署在客户自己的云账户中。

这种分离设计带来了几个好处。首先，敏感数据可以保留在客户的环境中，满足合规要求。其次，计算资源可以根据负载独立扩缩，不影响控制平面的稳定性。最后，平台升级可以在控制平面统一进行，无需逐个修改数据平面实例。

云 SaaS 部署流程

Cloud SaaS 是 LangGraph 平台最便捷的部署方式。整个流程基于 GitHub 的代码托管和 Webhook 触发，实现了真正的持续部署。从本地提交代码到服务更新，通常只需几分钟时间。

部署准备

部署前需要确保代码能在本地正常运行。langgraph dev 命令是验证的关键，如果图在本地无法编译或执行，部署到云端必然失败。代码必须托管在 GitHub 上，无论是公开仓库还是私有仓库都支持。私有仓库需要授权 LangChain 的 GitHub App 访问，这个操作需要仓库所有者权限。

项目根目录必须包含 langgraph.json 配置文件。这个文件是平台的部署清单，指定了依赖项、图定义、环境变量等关键信息。一个典型的配置如下：

{
  "dependencies": ["langchain_openai", "./src"],
  "graphs": {
    "agent": "./src/agent.py:graph"
  },
  "env": ".env"
}

dependencies 数组可以包含 PyPI 包名或本地路径，graphs 对象将图 ID 映射到具体的 Python 模块和变量名。环境变量文件则用于存储 API 密钥等敏感信息。

创建部署

登录 LangSmith 后，在左侧导航栏选择 LangGraph Platform，点击 New Deployment 开始创建。部署表单需要填写几个关键信息：

部署名称是平台的唯一标识，建议使用项目名加环境后缀，如 customer-support-prod。Git 分支指定了代码来源，平台会监听这个分支的推送事件。langgraph.json 路径需要精确到文件名，如果文件在子目录中，要填写相对路径。

自动更新选项建议开启，这样每次推送代码都会触发新版本的部署。环境变量部分，API 密钥等敏感信息必须标记为 secret，这些值会被加密存储，不会在日志或 API 响应中泄露。

部署类型分为 Development 和 Production 两种。Development 类型使用抢占式实例，成本低廉但可能随时被中断，适合测试环境。Production 类型提供高可用配置，支持自动扩缩容到 10 个副本，数据库有自动备份和多可用区部署，适合生产负载。

版本管理

每次部署都会创建一个 Revision。Revision 是不可变的，包含了代码、配置和依赖的完整快照。当需要回滚时，只需将某个历史 Revision 标记为活跃状态即可。这种设计让部署变得可预测、可回溯。

在部署详情页，可以查看每个 Revision 的构建日志、运行时日志和资源指标。构建失败时，日志会明确显示是依赖安装问题还是图编译错误。运行时日志则记录了每个节点的执行情况和状态变化，是排查生产问题的重要依据。

Studio 可视化工具

LangGraph Studio 是平台最具特色的功能之一。它不仅仅是一个调试工具，更是理解复杂智能体行为的窗口。通过 Studio，可以直观地看到图的结构、节点的执行顺序和状态的演变过程。

连接方式

Studio 支持两种连接模式。对于云端部署的应用，直接在部署详情页点击 LangGraph Studio 按钮即可打开，Studio 会自动连接到对应的 API 端点。对于本地开发，需要先运行 langgraph dev 启动本地服务器，然后通过 URL 参数指定 baseUrl。

本地服务器的默认地址是 http://127.0.0.1:2024，在浏览器中访问 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 就能连接到本地实例。如果使用 Safari 浏览器，需要加上 --tunnel 参数创建安全隧道，因为 Safari 对 localhost 的连接有安全限制。

Studio 的界面分为左右两栏。左侧是图的可视化展示，节点和边的布局清晰呈现了执行逻辑。右侧是交互面板，可以输入消息、查看状态历史和调试详细信息。每次运行后，节点的颜色会变化，显示执行路径和耗时。

两种工作模式

图模式是 Studio 的完整形态，展示了所有技术细节。可以看到每个节点的输入输出、状态更新和工具调用。点击节点能查看详细的执行日志，包括 LLM 的完整响应和工具返回结果。这种模式适合开发者深入调试，定位性能瓶颈或逻辑错误。

聊天模式则面向业务用户和快速测试。界面简化为对话形式，隐藏了图的复杂性，只展示智能体的最终回复。虽然看不到节点细节，但可以通过下拉菜单切换不同的助手配置，快速验证各种场景下的行为。聊天模式仅支持状态模式包含 MessagesState 的图。

Studio 与 LangSmith 的集成让调试更加强大。每次运行都会自动记录到 LangSmith，可以查看完整的调用链、Token 消耗和延迟指标。对于失败的运行，可以直接在 Studio 中加载对应的线程状态，复现问题现场。

助手线程管理平台

助手和线程是 LangGraph 平台管理的两个核心抽象。助手封装了可复用的配置，线程则维护了对话的上下文状态。理解这两个概念，是构建生产级智能体应用的关键。

助手配置管理

助手是图的实例化配置。同一个图可以创建多个助手，每个助手有不同的系统提示、模型参数或工具集。例如，一个客服图可以实例化为"技术支持助手"和"账单查询助手"，它们共享相同的处理逻辑，但使用不同的知识库和回复风格。

创建助手可以通过 SDK 或 Web UI。SDK 方式适合自动化脚本：

from langgraph_sdk import get_client

client = get_client(url="https://your-deployment.host.langchain.com")
assistant = await client.assistants.create(
    graph_id="agent",
    name="Tech Support Assistant",
    config={
        "configurable": {
            "system_prompt": "You are a technical support specialist...",
            "model": "gpt-4-turbo"
        }
    }
)

这段代码创建了一个名为 Tech Support Assistant 的助手，覆盖了图的默认配置。graph_id 必须对应 langgraph.json 中定义的图。config 对象的结构由图的运行时上下文决定，通常包含模型名称、系统提示和工具开关等参数。

在 Web UI 中创建助手更直观。在部署的 Assistants 标签页，点击 New Assistant 按钮，填写名称、描述和配置即可。UI 提供了表单验证，确保配置格式正确。创建后，助手会出现在列表中，点击 Studio 按钮可以直接用这个助手启动对话。

助手版本控制

助手支持版本管理，每次更新都会创建新版本。版本号从 1 开始递增，活跃版本是实际使用的配置。这种机制让配置变更变得安全，可以先在测试环境验证新版本，再切换到生产环境。

更新助手配置时，必须提供完整的 config 对象，平台不会自动合并旧配置。例如，要修改系统提示，需要这样调用：

await client.assistants.update(
    assistant_id="62e209ca-9154-432a-b9e9-2d75c7a9219b",
    config={
        "configurable": {
            "system_prompt": "New prompt...",
            "model": "gpt-4-turbo",
            "temperature": 0.7
        }
    }
)

如果只想修改其中一个字段，仍然需要传递完整的配置。这种设计虽然略显繁琐，但避免了配置漂移，确保每个版本都是自包含的。

回滚到历史版本使用 set_latest 方法：

await client.assistants.set_latest(assistant_id, version=1)

版本切换是即时生效的，无需重启服务。这对于快速响应业务需求或修复配置错误非常有用。

线程状态管理

线程是 LangGraph 平台的状态容器。每个线程维护独立的对话历史和状态快照，不同线程之间的状态完全隔离。线程可以长期存在，即使服务重启，状态也能从数据库恢复。

创建线程很简单：

thread = await client.threads.create()
thread_id = thread["thread_id"]

线程创建后是空的，没有初始状态。可以在创建时指定 checkpoint_id 来复用已有状态，实现对话的克隆或分支。

提交运行时，必须指定线程 ID 和助手 ID：

async for event in client.runs.stream(
    thread_id,
    assistant_id,
    input={"messages": [{"role": "user", "content": "Hello"}]},
    stream_mode="updates"
):
    print(event.data)

平台会自动加载线程的最新状态，应用助手的配置，执行图逻辑，并将更新写回线程。整个过程是原子性的，即使执行失败，状态也不会处于不一致的中间态。

线程的状态可以通过 client.threads.get_state() 查看，返回包含消息历史、节点计数和元数据的完整快照。对于需要人工审核的场景，可以在关键节点暂停执行，等待外部系统修改状态后再继续。

LangGraph 平台通过助手和线程的抽象，将配置与状态分离，让智能体应用具备了生产环境所需的灵活性、可观测性和可维护性。无论是快速迭代新功能，还是排查线上问题，这套机制都提供了有力的支持。

本章介绍了 LangGraph 平台的核心功能，从架构设计到具体实践，涵盖了部署、调试和管理智能体应用的完整链路。平台的价值在于将基础设施的复杂性封装起来，让开发者能专注于业务创新。下一章将深入探讨生产部署策略，包括自托管方案、容器化最佳实践和环境配置管理，帮助将应用稳定地推向大规模用户。