生命不息，折腾不止。前两课把 Agent 画出来、装上了长期记忆，今天把它从「本地 run 一下」升级成「对外提供一个标准 HTTP API」，真正离上线就差最后一步。

一、为什么不直接把脚本 run 起来，非要打包成 API

还在上一课那种「写个 graph.invoke() 自己跑」的阶段，Agent 只能伺候你一个人；打包成 API 之后，前端页面、后端服务、定时任务、飞书机器人、甚至另一个 Agent，都能用一个 HTTP 请求把它调起来。

更关键的是，LangGraph 打包后自带一套标准 REST 接口，把多轮会话、长任务、人审这些「上线才碰到」的脏活都替你兜住了：

  • threads（会话）：同一串对话走一个 thread，多轮上下文不丢；
  • runs + checkpoint（运行/断点）：第一课讲的 checkpoint 在这里变成「跑一半断了，还能接着跑」；
  • background runs（后台运行）：长任务丢后台，轮询拿结果，不用一直占着连接。

一句话概括：把「能聊的脚本」变成「能接进业务的服务」。

二、认识 LangGraph 的命令行「五件套」和一个 json

先装 CLI，二选一：

1
2
3
4
5
# Python 方式
uv tool install langgraph-cli        # 或 pip install "langgraph-cli[inmem]"

# Node 方式（装好后命令名是 langgraphjs）
npx @langchain/langgraph-cli

五个常用命令，各管一段：

命令 干啥的 要不要 Docker
langgraph dev 本地轻量开发服务器，热重载，默认 2024 端口 不要
langgraph up 本地起「全栈」：API 服务器 + Postgres + Redis，默认 8123，最接近生产 要
langgraph build 把项目打成 Docker 镜像 要
langgraph deploy 一键构建 + 部署到 LangSmith 云端，返回一个 API URL 不要（会自动远程构建）
langgraph dockerfile 导出 Dockerfile，方便你自己改 不要

核心是项目根目录一个 langgraph.json，它告诉 CLI「你的图在哪、依赖是啥、环境变量从哪读」：

1
2
3
4
5
6
7
8
{
  "dependencies": ["./my_agent", "langchain-openai"],
  "graphs": {
    "agent": "./my_agent/graph.py:graph"
  },
  "env": "./.env",
  "python_version": "3.11"
}
  • graphs 是重头戏："agent" 是这个图对外暴露的名字，后面 ./my_agent/graph.py:graph 是「文件路径 : 图对象名」，冒号前面是文件，冒号后面是那个 graph 变量；
  • dependencies 里除了 pip 包名，还能写本地包目录（./my_agent），CLI 会自动把它装进环境；
  • env 指向 .env，模型 key 之类都往里放。

注：2025 年 10 月起官方把 LangGraph Platform 改名叫 LangSmith Deployment，命令没变，还是这套 langgraph 前缀。

三、先本地跑：langgraph dev 热重载

沿用前两课那个带记忆的 react agent，只要把 graph 用变量 export 出来、配好上面的 langgraph.json，一条命令就起服务：

1
2
langgraph dev
# 默认跑在 http://localhost:2024

起好后自带 Studio 调试界面，也能直接打 API 验证：

1
2
3
4
5
6
7
curl -s -X POST http://localhost:2024/runs/stream \
  -H 'Content-Type: application/json' \
  -d '{
    "assistant_id": "agent",
    "input": {"messages": [{"role": "human", "content": "帮我查下今天的天气"}]},
    "stream_mode": "updates"
  }'

两个要点：assistant_id 就是 langgraph.json 里 graphs 的 key（上面写的 agent）；stream_mode: "updates" 表示按节点吐增量，调试时看得最清楚。改代码自动重载，状态先存内存/本地目录，适合边写边调。

四、验证生产：langgraph up 起全栈

dev 太轻，想提前发现「依赖装没装全、连库对不对」这类只有生产才爆的问题，用 up：

1
2
3
langgraph up             # 默认 8123，起 API + Postgres + Redis
langgraph up --recreate  # 有重大改动时重建镜像再起
langgraph up --watch     # 改文件自动重启

起好后 http://localhost:8123，把上面 runs/stream 那个 curl 的端口换掉就能用。区别在于：持久化走真 Postgres、实时流走 Redis，行为和生产一致，是上线前的最后一道体检。

模型怎么连中转站：.env 里把 base_url 指到 OpenAI 兼容接口即可，例如：

1
2
3
4
# .env
OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://ai.aklibk.com/v1
MODEL=gpt-4o-mini

langchain-openai 认 OPENAI_BASE_URL 这个环境变量。Claude/GPT 这类国外模型走中转站，就能国内直连 + 免绑卡 + 人民币按量付费，不用折腾外币卡；国产模型（DeepSeek 等）也一视同仁，换个 base_url 和 model 名就能多模型对接，价格更便宜。（具体变量名以官方文档为准，部分版本也支持在 ChatOpenAI 里直接传 base_url 参数。）

五、上线：先 build 镜像，再 deploy 或自托管

本地验证 OK 后，两条路：

  1. 托管（最省心）：langgraph deploy，一条命令完成构建镜像 → 推托管平台 → 建 deployment，最后拿到一个 API URL 直接调用。
  2. 自托管（自己服务器）：先用 langgraph build -t my-agent 打成镜像，再 Docker 跑起来：
1
2
3
docker run -d --name my-agent -p 8123:8000 --env-file .env \
  -e REDIS_URI=redis://... -e DATABASE_URI=postgres://... \
  my-agent

自托管要自己配 Postgres（存 checkpoint）和 Redis（流式广播），分别对应 DATABASE_URI、REDIS_URI 两个环境变量。到这里，第二课埋的长期记忆（Store）才真正落地成「隔天也认得你」的持久数据。

六、常见坑（避雷）

  1. langgraph up 报 Docker 没起来：up 依赖本地 Docker，先 docker ps 确认守护进程在跑；纯调试用 langgraph dev 不依赖 Docker。
  2. assistant_id 对不上：API 里这个值必须跟 langgraph.json 里 graphs 的 key 一字不差，写完先在 Studio 里点一下确认能出图。
  3. 改了 langgraph.json 不生效：dependencies 或 python_version 变动后，up 可能还用旧镜像，加 --recreate 重建。
  4. 端口冲突：8123 / 2024 被占时用 -p / --port 换（如 langgraph up -p 8000，dev 同理，以 CLI 官方文档为准）。
  5. 本地能跑、一部署就 ImportError：dev 直接跑你本机环境，但 up / build 是干净的 Docker 环境，依赖漏写进 dependencies 就会报错——这是「部署当场翻车」的头号原因。

生命不息，折腾不止。下一篇「LangGraph 实战第四课」：一个任务拆给多个 Agent 并行干，Supervisor 老板 Agent 负责派活收结果，把单打独斗升级成流水线。