AI Agent从无到有71: LangGraph 云平台与本地开发实战

关注

原创 2026-08-17 19:06:57 478 阅读 AI 写同款· GEO 优化 ›

RAG、Agent、MCP与Skill：企业AI落地的四层解题逻辑在企业AI工程化实践中，RAG（检索增强生成）、Agent（智能体）、MCP（模型控制协议）和Skill（原子能力）并非并列技术选型，而是面向不同层级业务问题的系统性解法。RAG解决知识碎片化导致的决策依据缺失，本质是动态语义索引；Agent应对流程断点，实为状态驱动的任务协调器；MCP弥合异构系统间的语义鸿沟，提供跨平台动作指令标准；Skill则锚定能力边界，强调契约化、可组合的最小执行单元。四者协同构成‘知识→流程→连接→执行’的技术栈闭环，适用于金融风控、智能制造、医疗慢病管理等强业务耦合场景。本文基阅读详情

纲要

LangGraph 云平台概览
- 核心组件：LangGraph Server、CLI、Studio
- 适用场景：专注业务逻辑，减少基础设施维护负担
本地开发：使用 LangGraph Server
- CLI 安装与环境要求
- 项目创建与模板选择
- 启动本地开发服务器
- 通过 SDK 与服务器交互
模板与脚手架
- 可用模板概览
- 基于模板创建项目
LangGraph Studio 调试与可视化
- 图结构可视化
- 状态追踪与交互式调试
- 工具调用监控
完整可运行示例
- 环境准备
- 构建基础聊天 Agent 服务
- 使用 Python SDK 与 HTTP 客户端调用
API 速览
参考文档

LangGraph 云平台概览

LangGraph 是 LangChain 生态中用于构建多智能体工作流的核心编排框架。为加速生产级部署，官方推出了 LangGraph Cloud Platform（即 LangSmith Cloud 中的 Agent 部署能力），其核心组件包括：

LangGraph Server（Agent Server）：预置的服务器层，内置流式传输、后台任务、状态持久化、人机交互等基础能力，开发者无需手动搭建 FastAPI 或类似服务。
LangGraph CLI：命令行工具，提供项目脚手架、本地服务器管理及部署能力。
LangGraph Studio（现已整合至 LangSmith Studio）：可视化调试和追踪工具，与 LangSmith 深度集成，实时展示图数据流和状态变化。

这些工具让开发者能够将精力集中在智能体逻辑（图的结构与节点）上，而无需关注服务器部署、负载均衡等底层细节。对于商业项目，可选择将服务部署到 LangGraph Cloud（SaaS 模式）；个人开发者也可在本地运行全部功能。

本地开发：使用 LangGraph Server

安装 CLI

LangGraph CLI 可通过 pip 安装。需要注意，本地开发模式（langgraph dev）需要安装带 inmem 扩展的版本：

pip install -U "langgraph-cli[inmem]"

安装完成后，可通过以下命令验证：

langgraph --help

创建新项目

使用 langgraph new 命令从官方模板创建项目：

langgraph new my-agent-app --template new-langgraph-project-python
cd my-agent-app

如果不指定 --template 参数，CLI 会以交互式菜单列出所有可用模板供选择。可用模板包括 new-langgraph-project-python（基础单节点项目）、react-agent（ReAct 风格代理）等。

配置环境变量

在项目目录下找到 .env.example 文件，复制为 .env 并填入必要的 API Key：

LANGSMITH_API_KEY=lsv2_xxxx
OPENAI_API_KEY=sk-xxxx   # 如使用 OpenAI 模型

注：LangSmith API Key 可在 smith.langchain.com/settings 免费注册获取。

启动本地服务器

安装依赖后，使用 langgraph dev 启动本地开发服务器：

pip install -e .
langgraph dev

langgraph dev 是一个轻量级内存服务器，支持热重载，无需 Docker，适合快速迭代开发。默认监听 127.0.0.1:2024 端口。成功启动后，终端会输出以下信息：

Ready!
- API: http://127.0.0.1:2024
- Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
- API Docs: http://127.0.0.1:2024/docs

此时可通过 http://127.0.0.1:2024/docs 查看自动生成的 API 文档。

使用 Python SDK 与服务器交互

安装 langgraph-sdk 客户端库：

pip install -U langgraph-sdk

langgraph-sdk 提供了异步客户端 get_client 和同步客户端 get_sync_client。以下示例演示了如何通过异步客户端调用本地 Agent：

import asyncio
from langgraph_sdk import get_client

# 连接本地服务器
client = get_client(url="http://127.0.0.1:2024")

# 获取已注册的 assistant（每个 graph 会自动创建一个 assistant）
assistants = await client.assistants.search()
agent = assistants[0]

# 创建新线程
thread = await client.threads.create()

async def main():
    input_data = {"messages": [{"role": "human", "content": "你好，请做个自我介绍"}]}
    async for chunk in client.runs.stream(
        thread["thread_id"],
        agent["assistant_id"],
        input=input_data,
        stream_mode="values",
    ):
        if chunk.data and "messages" in chunk.data:
            last_msg = chunk.data["messages"][-1]
            if isinstance(last_msg, dict):
                print(last_msg.get("content", last_msg))
            else:
                print(last_msg)

asyncio.run(main())

模板与脚手架

CLI 内置了多个模板，涵盖常见场景：

模板名称	描述
`new-langgraph-project-python`	基础单节点项目，适合新手入门
`react-agent`	ReAct 风格代理，可灵活扩展多种工具
`memory-agent`	ReAct 风格代理，带跨线程记忆存储能力

以 react-agent 为例，创建并运行：

langgraph new react-bot --template react-agent
cd react-bot
pip install -e .
langgraph dev

项目结构已预置好图定义和基础配置，只需修改 .env 中的 API Key 即可使用。

LangGraph Studio 可视化调试

在启动 langgraph dev 后，终端会输出一个 LangSmith Studio 链接。打开后可看到：

左侧图结构：完整的多智能体流程图，节点与边一目了然。
对话输入区：可直接发送消息进行交互测试。
右侧执行面板：实时展示数据流动，每一步的输入输出、工具调用、状态变更均可视化。
状态检查：可查看任意时刻的完整状态 JSON，支持“时间旅行”（Time Travel）调试，从任意节点重新执行。

Studio 对于复杂工作流的调试非常有帮助，尤其是分析工具调用的正确性和循环逻辑。

完整可运行示例

下面构建一个简单的聊天智能体，并通过 langgraph dev 将其作为本地服务运行，然后通过 Python SDK 进行测试。

项目结构

my-chat-agent/
├── langgraph.json          # CLI 配置文件
├── agent.py                # 图定义
├── requirements.txt        # 依赖声明
├── .env                    # 环境变量
└── pyproject.toml          # 项目配置（可选）

配置文件 `langgraph.json`

langgraph dev 默认读取当前目录下的 langgraph.json 配置文件：

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "env": ".env"
}

dependencies：指定依赖路径，"." 表示查找当前目录下的 pyproject.toml、setup.py 或 requirements.txt。
graphs：将图 ID "agent" 映射到 agent.py 中导出的 graph 变量。

服务端脚本 `agent.py`

# agent.py
import os
from typing import List, TypedDict
from dotenv import load_dotenv
from langchain_core.messages import HumanMessage, AIMessage
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, END
from langgraph.checkpoint.memory import MemorySaver

load_dotenv()

class ChatState(TypedDict):
    messages: List

def chatbot(state: ChatState) -> dict:
    llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

# 构建图
graph_builder = StateGraph(ChatState)
graph_builder.add_node("chatbot", chatbot)
graph_builder.set_entry_point("chatbot")
graph_builder.add_edge("chatbot", END)

# 编译并添加检查点（MemorySaver 用于状态持久化）
graph = graph_builder.compile(checkpointer=MemorySaver())

依赖文件 `requirements.txt`

langgraph>=0.3.0
langchain-openai
python-dotenv

启动服务

pip install -r requirements.txt
langgraph dev

服务启动后，可通过 http://127.0.0.1:2024 访问。

客户端测试脚本 `client.py`

# client.py
import asyncio
from langgraph_sdk import get_client

async def main():
    client = get_client(url="http://127.0.0.1:2024")
    
    # 获取 assistant
    assistants = await client.assistants.search()
    agent = assistants[0]
    
    # 创建线程以保持会话状态
    thread = await client.threads.create()
    
    # 发送第一条消息
    input1 = {"messages": [{"role": "human", "content": "你好，我是小明。"}]}
    async for chunk in client.runs.stream(
        thread["thread_id"],
        agent["assistant_id"],
        input=input1,
        stream_mode="values",
    ):
        if chunk.data and "messages" in chunk.data:
            last = chunk.data["messages"][-1]
            print(last.get("content") if isinstance(last, dict) else last)
    
    # 发送第二条消息（测试上下文记忆）
    input2 = {"messages": [{"role": "human", "content": "刚才说过的名字是什么？"}]}
    async for chunk in client.runs.stream(
        thread["thread_id"],
        agent["assistant_id"],
        input=input2,
        stream_mode="values",
    ):
        if chunk.data and "messages" in chunk.data:
            last = chunk.data["messages"][-1]
            print(last.get("content") if isinstance(last, dict) else last)

if __name__ == "__main__":
    asyncio.run(main())

运行客户端脚本：

python client.py

你将看到服务端记录对话历史，并正确回答上下文问题。

API 速览

本节梳理本文涉及的核心 API。

`langgraph_sdk.get_client`

所属库：langgraph-sdk

方法签名：

from langgraph_sdk import get_client

client = get_client(url: Optional[str] = None, api_key: Optional[str] = None)

参数：

参数	类型	说明
`url`	`Optional[str]`	服务器 URL。本地 `langgraph dev` 默认端口为 2024
`api_key`	`Optional[str]`	API Key（部署到 LangSmith Cloud 时需要）

返回值：LangGraphClient 异步客户端实例

示例：

from langgraph_sdk import get_client

client = get_client(url="http://127.0.0.1:2024")

`LangGraphClient.runs.stream`

所属库：langgraph-sdk

方法签名：

async for chunk in client.runs.stream(
    thread_id: str,
    assistant_id: str,
    input: dict,
    stream_mode: str = "values",
    config: Optional[dict] = None,
)

参数：

参数	类型	说明
`thread_id`	`str`	线程 ID，用于状态持久化
`assistant_id`	`str`	Assistant ID，对应 `langgraph.json` 中定义的图
`input`	`dict`	输入数据，如 `{"messages": [...]}`
`stream_mode`	`str`	流式模式，可选 `"values"`、`"updates"` 等
`config`	`Optional[dict]`	运行时配置

返回值：异步生成器，逐块返回流式响应

示例：

async for chunk in client.runs.stream(
    thread_id="thread_123",
    assistant_id="asst_456",
    input={"messages": [{"role": "human", "content": "Hello"}]},
    stream_mode="values",
):
    print(chunk)

参考文档

官方文档

参考链接

总结

LangGraph Cloud Platform 为多智能体应用提供了一套从开发、调试到部署的全流程工具链。借助 CLI 模板和本地服务器，开发者可以快速启动项目，专注于图结构的设计，而无需手动处理 HTTP 服务、状态管理等重复工作。Studio 的可视化调试大幅提升了复杂工作流的开发效率。无论是个人学习还是商业落地，这套方案都值得尝试。

本文覆盖了 LangGraph 云平台、CLI 模板、本地服务器、Studio 调试等核心要点，并提供了可验证的代码示例。

收录于