AI Agent白手起家71: LangGraph 云平台与本地开发实战

纲要

• LangGraph 云平台概览
  • 核心组件：LangGraph Server、CLI、Studio
  • 解决痛点：专注逻辑，减少基础设施维护
• 本地开发：使用 LangGraph Server
  • 安装 CLI
  • 创建项目与模板
  • 启动本地服务器
  • 通过 SDK 与服务器交互
• 快速启动：模板与脚手架
  • 可用模板列表
  • 基于 memory-agent-python 模板启动
• LangGraph Studio 调试与可视化
  • 图结构可视化
  • 状态追踪与交互式调试
  • 工具调用监控
• 完整可运行示例
  • 环境准备
  • 构建一个简单的聊天 Agent 服务
  • 使用 Python SDK 或 HTTP 客户端调用
• 总结与相关度说明

LangGraph 云平台概览

LangGraph 是 LangChain 生态中用于构建多智能体工作流的核心框架。为了加速生产级部署，官方推出了 LangGraph Cloud Platform，包含三大组件：

• LangGraph Server：预置的服务器层，内置流式传输、后台任务、状态持久化、人机交互等基础能力，无需手动搭建 FastAPI 或类似服务。
• LangGraph CLI：命令行工具，提供脚手架和模板，用于快速创建项目。
• LangGraph Studio：可视化调试和追踪工具，与 LangSmith 深度集成，实时展示图数据流和状态变化。

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

本地开发：使用 LangGraph Server

安装 CLI

首先，安装 langgraph-cli 命令行工具：

pip install langgraph-cli

创建新项目

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

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

可用模板包括 react-agent-python、memory-agent-python、basic-python 等，可在 LangGraph GitHub 仓库 中查看完整列表。

配置环境变量

在项目目录下创建 .env 文件，填入大模型 API Key：

OPENAI_API_KEY=sk-xxxx
LANGCHAIN_TRACING_V2=true   # 可选
LANGCHAIN_API_KEY=ls__xxxx  # 可选

启动本地服务器

安装依赖后，使用 langgraph dev 启动本地开发服务器（默认监听 2024 端口）：

pip install -e .
langgraph dev

出现 Uvicorn running on http://0.0.0.0:2024 字样即表示成功。此时可通过 http://localhost:2024/docs 查看自动生成的 API 文档。

使用 Python SDK 与服务器交互

安装 langgraph-sdk 客户端库，远程调用本地服务器上的 Agent：

pip install langgraph-sdk

from langgraph_sdk import get_client

client = get_client(url="http://localhost:2024")
thread = {"configurable": {"thread_id": "1"}}

async def main():
    async for chunk in client.runs.stream(
        None,
        "agent",  # 图名称，与项目中的 graph 变量一致
        input={"messages": [{"role": "user", "content": "你好，请做个自我介绍"}]},
        stream_mode="values",
        config=thread,
    ):
        if "messages" in chunk.data and chunk.data["messages"]:
            last_msg = chunk.data["messages"][-1]
            print(last_msg["content"])

import asyncio
asyncio.run(main())

服务器日志中会实时显示每次工具调用和模型推理的详细信息。

快速启动：模板与脚手架

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

模板名称	描述
react-agent-python	基础 React Agent，带工具调用
memory-agent-python	带长期记忆的 Agent
basic-python	最简 LangGraph 项目

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

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

项目结构已预置好了图定义、记忆存储和环境配置，只需修改 .env 中的 Key 即可使用。

LangGraph Studio 可视化调试

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

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

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

完整可运行示例

下面我们手动构建一个简单的聊天智能体，并使用 langgraph.serve 将其作为本地服务运行，然后通过 HTTP 客户端进行测试。这种方式无需复杂的 CLI 项目，直接运行脚本即可。

服务端脚本 server.py

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

load_dotenv()

class ChatState(TypedDict):
    messages: List

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

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

# 编译并添加检查点
app = graph.compile(checkpointer=MemorySaver())

# 启动服务（默认端口 2024）
if __name__ == "__main__":
    serve(app, host="0.0.0.0", port=2024)

在运行前，确保已安装所需依赖并配置 .env：

pip install langgraph langchain-openai python-dotenv uvicorn
echo 'OPENAI_API_KEY=your-key-here' > .env
python server.py

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

客户端测试脚本 client.py

使用 requests 库直接调用 REST API，无需额外 SDK：

# client.py
import requests
import json

BASE = "http://localhost:2024"
thread_id = "test-session"

def send_message(content: str):
    # 使用 /runs/stream 端点
    url = f"{BASE}/runs/stream"
    payload = {
        "assistant_id": "agent",
        "input": {
            "messages": [{"role": "user", "content": content}]
        },
        "config": {
            "configurable": {
                "thread_id": thread_id
            }
        },
        "stream_mode": "values"
    }
    headers = {"Content-Type": "application/json"}
    response = requests.post(url, json=payload, headers=headers, stream=True)
    for line in response.iter_lines():
        if line:
            data = json.loads(line.decode("utf-8"))
            if "messages" in data and data["messages"]:
                # 只输出最后一条消息的内容
                last_msg = data["messages"][-1]
                print(last_msg["content"])

if __name__ == "__main__":
    send_message("你好，我是小明。")
    send_message("刚才说过的名字是什么？")

运行客户端脚本：

python client.py

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

总结

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

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