LangGraph 本地服务运行：让 Agent "开门营业"

简单来说

这篇文章教你如何把你的 LangGraph AI Agent "开店营业"——也就是把你写好的 AI 智能体跑起来变成一个可以被外部调用的 API 服务。这样前端、其他程序、甚至 curl 命令都能和你的 AI 对话了。

一句话总结：从"代码文件"变成"在线服务"的过程。

🎯 本节目标

学完本节，你将能够：

使用 LangGraph CLI 启动本地开发服务器
在 LangSmith Studio 可视化调试你的 Agent
通过 REST API 或 SDK 调用你的 Agent
理解开发环境和生产环境的区别

核心痛点与解决方案

痛点：写完 Agent 代码后，怎么让别人用？

想象你辛辛苦苦写了一个超级聪明的 AI Agent，它能帮人分析数据、回答问题、执行任务。但是现在它只是躺在你电脑里的一堆 .ts 文件。

问题	具体表现
测试麻烦	每次都要改代码重新运行
无法联调	前端同事问：API 接口在哪？
调试困难	只能 console.log 满天飞
状态管理	对话保持上下文？自己手动管理，头大

解决：LangGraph CLI 一键开服

之前的痛苦	现在的快乐
代码改完要重启	热更新，改完自动生效
没有 API 接口	自动生成 REST API
看不到执行流程	Studio UI 可视化调试
状态管理很头疼	内置持久化支持

痛点与解决方案对比：无服务器开发 vs 使用 LangGraph CLI

生活化类比：私房菜厨师开店

把你的 AI Agent 想象成一个"私房菜厨师"：

技术概念	类比	解释
你写的 Agent 代码	精心研发的菜谱	你的手艺和配方
langgraph.json	餐厅菜单	告诉顾客你能做什么菜
npm create langgraph	开一家标准化餐厅	有厨房、点单系统、前台
langgraph dev	正式开门营业！	接受顾客点单
http://localhost:2024	餐厅门牌号	顾客找到你的地址
Studio UI	厨房监控摄像头	看到每道菜怎么做出来
REST API / SDK	顾客点单方式	打电话点单 or 小程序点单

从代码到服务：Agent 启动后的三种访问路径

快速上手：7 步启动服务

Step 1：安装 LangGraph CLI

bash

npm install --save-dev @langchain/langgraph-cli

💡 人话解读： 买下一套餐厅管理软件。

Step 2：创建 LangGraph 应用

bash

npm create langgraph

这会从模板创建一个新项目，包含基础的 Agent 结构。

💡 人话解读： 按照模板装修一家新餐厅。

如果你已经有项目了，可以自动生成配置文件：

bash

npm create langgraph config

这会扫描你的项目，找到所有 LangGraph Agent 并生成 langgraph.json：

json

{
  "node_version": "24",
  "graphs": {
    "agent": "./src/agent.ts:agent",
    "searchAgent": "./src/search.ts:searchAgent"
  },
  "env": ".env"
}

Step 3：安装依赖

bash

cd path/to/your/app
npm install

💡 人话解读： 采购厨房设备和原材料。

Step 4：创建 .env 文件

在项目根目录创建 .env 文件：

bash

LANGSMITH_API_KEY=lsv2...

💡 人话解读： 办理各种证照（营业执照、卫生许可）。

⚠️ 注意：需要先在 LangSmith 注册账号获取 API Key（免费）。

Step 5：启动服务

bash

npx @langchain/langgraph-cli dev

成功启动后会看到：

        Welcome to

╦  ┌─┐┌┐┌┌─┐╔═╗┬─┐┌─┐┌─┐┬ ┬
║  ├─┤││││ ┬║ ╦├┬┘├─┤├─┘├─┤
╩═╝┴ ┴┘└┘└─┘╚═╝┴└─┴ ┴┴  ┴ ┴

- 🚀 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

💡 人话解读： 开门营业！餐厅地址是 localhost:2024。

7 步启动 LangGraph 本地服务

Step 6：在 Studio 中测试

打开输出中的 Studio UI 链接：

https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

在这里你可以：

📝 直接在界面上和 Agent 对话
🔍 可视化查看每一步的执行流程
🐛 调试复杂的多步骤流程
📊 查看每一步的输入输出

💡 人话解读： 老板坐在监控室看厨房干活。

Step 7：通过 API 调用

现在你的 Agent 已经是一个 API 服务了！

调用方式详解

方式一：使用 JavaScript SDK

bash

npm install @langchain/langgraph-sdk

typescript

import { Client } from "@langchain/langgraph-sdk";

const client = new Client({ apiUrl: "http://localhost:2024" });

const streamResponse = client.runs.stream(
  null,
  "agent",
  {
    input: {
      messages: [
        { role: "user", content: "What is LangGraph?" }
      ]
    },
    streamMode: "messages-tuple",
  }
);

for await (const chunk of streamResponse) {
  console.log(`收到新事件: ${chunk.event}...`);
  console.log(JSON.stringify(chunk.data));
}

💡 代码解读：

Client({ apiUrl }): 创建一个"遥控器"，指向你本地的 AI 服务
client.runs.stream(): 发起一次流式对话请求
null: 无线程模式，不保存对话历史
"agent": 要调用哪个 Agent（对应 langgraph.json 里的 key）
streamMode: "messages-tuple": 流式返回，一边生成一边返回

方式二：使用 REST API

bash

curl -s --request POST \
    --url "http://localhost:2024/runs/stream" \
    --header 'Content-Type: application/json' \
    --data "{
        \"assistant_id\": \"agent\",
        \"input\": {
            \"messages\": [
                {
                    \"role\": \"human\",
                    \"content\": \"What is LangGraph?\"
                }
            ]
        },
        \"stream_mode\": \"messages-tuple\"
    }"

💡 人话解读： 用最原始的 HTTP 请求直接调用 AI 服务，不需要装 SDK，任何能发 HTTP 请求的语言/工具都能用。

三种调用方式：Studio UI、JS SDK、REST API

关键概念解释

langgraph.json 配置文件

这是项目的"身份证"，告诉系统：

json

{
  "node_version": "24",
  "graphs": {
    "agent": "./src/agent.ts:agent",
    "searchAgent": "./src/search.ts:searchAgent"
  },
  "env": ".env"
}

字段	说明
`node_version`	使用的 Node.js 版本
`graphs`	你有哪些 Agent，key 是名称，value 是文件路径:导出名
`env`	环境变量文件位置

In-memory Mode（内存模式）

langgraph dev 启动的是内存模式：

✅ 优点：启动快，适合开发测试
❌ 缺点：数据不持久，关机就没了，不能用于生产

Threadless Run（无线程运行）

typescript

client.runs.stream(null, "agent", ...)

第一个参数传 null 表示无线程模式：

一次性对话，不保存上下文
就像打客服电话，挂了就完了，下次打进来对方不认识你

如果要保持对话上下文，需要传入 thread_id（后续章节会讲）。

核心概念：langgraph.json、内存模式、无线程运行

完整开发流程图

┌─────────────────────────────────────────────────────────────────┐
│                    LangGraph 本地开发流程                         │
└─────────────────────────────────────────────────────────────────┘

    [1] 安装 CLI 工具
         │
         ▼
    ┌─────────────────┐
    │ npm install     │
    │ @langchain/     │
    │ langgraph-cli   │
    └────────┬────────┘
             │
             ▼
    [2] 创建项目
         │
         ▼
    ┌─────────────────┐     生成 langgraph.json
    │ npm create      │ ──────────────────────►  配置文件
    │ langgraph       │                          （菜单）
    └────────┬────────┘
             │
             ▼
    [3] 配置环境
         │
         ▼
    ┌─────────────────┐
    │ 创建 .env       │ ──► LANGSMITH_API_KEY=xxx
    │ 填入 API Keys   │
    └────────┬────────┘
             │
             ▼
    [4] 启动服务
         │
         ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ langgraph dev   │────►│ localhost:2024  │
    └─────────────────┘     │   (API 服务)    │
                            └────────┬────────┘
                                     │
             ┌───────────────────────┼───────────────────────┐
             │                       │                       │
             ▼                       ▼                       ▼
    ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
    │   Studio UI     │     │   JS SDK 调用   │     │   REST API      │
    │  可视化调试      │     │   前端/后端集成  │     │   任意语言调用   │
    └─────────────────┘     └─────────────────┘     └─────────────────┘

真实场景案例：开发智能电商客服

阶段一：开发调试

你（开发者）正在写 Agent 代码...

❌ 不用本地服务器：
- 改一行代码 → 重新跑脚本 → 手动输入测试问题 → 看 console.log
- 改一行代码 → 重新跑脚本 → 手动输入测试问题 → 看 console.log
- ... 累死了 ...

✅ 用本地服务器：
- 启动 langgraph dev（一次）
- 打开 Studio UI
- 直接在界面上聊天测试
- 改代码自动热更新
- 可视化看到 Agent 的思考过程

阶段二：前后端联调

前端同事：API 接口给我一个
你：http://localhost:2024/runs/stream，POST 请求，参数这样传...
前端同事：收到！

（前端开始调试，你继续优化 Agent 逻辑）
（互不干扰，各自并行开发）

阶段三：产品验收

产品经理：我想看看效果
你：打开这个链接 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
产品经理：（直接在网页上和 AI 对话，提出改进意见）
你：（实时看到对话内容，了解问题所在）

效率提升对比

方面	不用本地服务器	用本地服务器
调试效率	低（改代码要重启）	高（热更新）
可视化	无（只能看日志）	完整（Studio UI）
团队协作	困难（代码层面）	简单（API 层面）
测试便利性	低（要写测试代码）	高（界面直接测）

开发协作三阶段：调试、联调、验收

常见问题速查

Q1: Safari 浏览器打不开 Studio？

Safari 对 localhost 有限制，启动时加个参数：

bash

npx @langchain/langgraph-cli dev --tunnel

这会创建一个安全隧道绕过限制。

Q2: 我已经有项目了，不想从模板创建？

用这个命令自动扫描你的项目，生成配置文件：

bash

npm create langgraph config

它会自动找到你代码里的 createAgent()、StateGraph.compile() 等模式。

Q3: 为什么叫 "in-memory mode"？

所有数据都存内存，重启服务就没了。开发够用，生产环境要用 LangSmith Deployment 来持久化存储。

Q4: 如何改变默认端口 2024？

查阅 CLI 的帮助文档：

bash

npx @langchain/langgraph-cli dev --help

核心要点回顾

安装 CLI：npm install --save-dev @langchain/langgraph-cli
创建/配置项目：npm create langgraph 或 npm create langgraph config
启动服务：npx @langchain/langgraph-cli dev
三种访问方式：Studio UI（调试）、SDK（集成）、REST API（通用）
开发 vs 生产：in-memory 模式适合开发，生产要用 LangSmith Deployment

下一步学习

本地服务跑起来了！接下来：

🧠 05-LangGraph 思维模式：学习构建 Agent 的 5 步方法论
🔄 06-工作流与 Agent：掌握 6 种核心工作流模式
💾 15-持久化机制：让你的 Agent 有记忆

一图总结

                    ┌─────────────────────────────┐
                    │    你的 Agent 代码          │
                    │   （私房菜厨师的手艺）       │
                    └──────────────┬──────────────┘
                                   │
                                   ▼
                    ┌─────────────────────────────┐
                    │   langgraph dev 启动        │
                    │   （餐厅正式开业）           │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                    ▼              ▼              ▼
               ┌────────┐    ┌────────┐    ┌────────┐
               │ Studio │    │  SDK   │    │  REST  │
               │（监控） │    │（小程序）│    │（电话） │
               └────────┘    └────────┘    └────────┘
                    │              │              │
                    └──────────────┼──────────────┘
                                   │
                                   ▼
                         和你的 AI 愉快对话！

记住： langgraph dev 就是让你的 AI Agent "从代码变服务"的魔法咒语！

📅 更新时间：2026-02-22

LangGraph 本地服务运行：让 Agent "开门营业" ​

简单来说 ​

🎯 本节目标 ​

核心痛点与解决方案 ​

痛点：写完 Agent 代码后，怎么让别人用？ ​

解决：LangGraph CLI 一键开服 ​

生活化类比：私房菜厨师开店 ​

快速上手：7 步启动服务 ​

Step 1：安装 LangGraph CLI ​

Step 2：创建 LangGraph 应用 ​

Step 3：安装依赖 ​

Step 4：创建 .env 文件 ​

Step 5：启动服务 ​

Step 6：在 Studio 中测试 ​

Step 7：通过 API 调用 ​

调用方式详解 ​

方式一：使用 JavaScript SDK ​

方式二：使用 REST API ​

关键概念解释 ​

langgraph.json 配置文件 ​

In-memory Mode（内存模式） ​

Threadless Run（无线程运行） ​

完整开发流程图 ​

真实场景案例：开发智能电商客服 ​

阶段一：开发调试 ​

阶段二：前后端联调 ​

阶段三：产品验收 ​

效率提升对比 ​

常见问题速查 ​

Q1: Safari 浏览器打不开 Studio？ ​

Q2: 我已经有项目了，不想从模板创建？ ​

Q3: 为什么叫 "in-memory mode"？ ​

Q4: 如何改变默认端口 2024？ ​

核心要点回顾 ​

下一步学习 ​

一图总结 ​

LangGraph 本地服务运行：让 Agent "开门营业"

简单来说

🎯 本节目标

核心痛点与解决方案

痛点：写完 Agent 代码后，怎么让别人用？

解决：LangGraph CLI 一键开服

生活化类比：私房菜厨师开店

快速上手：7 步启动服务

Step 1：安装 LangGraph CLI

Step 2：创建 LangGraph 应用

Step 3：安装依赖

Step 4：创建 .env 文件

Step 5：启动服务

Step 6：在 Studio 中测试

Step 7：通过 API 调用

调用方式详解

方式一：使用 JavaScript SDK

方式二：使用 REST API

关键概念解释

langgraph.json 配置文件

In-memory Mode（内存模式）

Threadless Run（无线程运行）

完整开发流程图

真实场景案例：开发智能电商客服

阶段一：开发调试

阶段二：前后端联调

阶段三：产品验收

效率提升对比

常见问题速查

Q1: Safari 浏览器打不开 Studio？

Q2: 我已经有项目了，不想从模板创建？

Q3: 为什么叫 "in-memory mode"？

Q4: 如何改变默认端口 2024？

核心要点回顾

下一步学习

一图总结