langgraph.json 配置文件详解:字段说明、目录结构与常见启动报错排查

用 langgraph dev 启动 Studio 调试或用 langgraph build 打包时,项目根目录必须有 langgraph.json。本文按官方 CLI 规范讲清 dependencies、graphs、env 等核心字段写法与排错要点。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. 先明确什么时候需要它:只有当你使用官方命令行工具(langgraph dev、langgraph up、langgraph build)或托管平台时才需要 langgraph.json;如果你只是自己写 python app.py 或用自有 FastAPI 包装开源库(见 /guides/langgraph-pricing-open-source-vs-platform),完全不需要这个文件。
  2. 最小可用配置只需三个键:dependencies(装哪些包)、graphs(图变量在哪)、env(环境变量文件在哪)。
  3. graphs 的值格式严格为 "相对文件路径:变量名或工厂函数名",所有相对路径均以 langgraph.json 所在目录为基准解析。
  4. 头号避坑点:写进 graphs 暴露给 CLI 服务器的图,在 builder.compile() 时不要手动传入 InMemorySaver 等自定义检查点,服务端会自动注入统一的持久化存储,手动传反而会冲突报错。

langgraph.json 核心配置字段一览

图:本站根据 LangGraph CLI 配置文件官方文档 整理的示意图

本文根据 LangChain / LangGraph CLI 官方配置文件参考文档整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 官方网站。

适用于谁

  • 搜「langgraph json 配置」「langgraph.json 怎么写」的人;
  • 想运行 langgraph dev 打开可视化面板(用法见 /guides/langgraph-debug-visualize-studio-guide),结果一敲命令就报缺少配置文件或找不到图变量的开发者;
  • 需要在一份服务里同时暴露多个不同业务状态图、或者自定义系统级依赖与鉴权钩子的后端工程师。

一、标准项目目录结构与最小模板

新手配 langgraph.json 最容易卡在「写了 "dependencies": ["."] 却报本地包无法安装」。原因是 "." 代表把当前根目录当成一个标准 Python 项目来解析依赖,因此根目录下应当配套放好 pyproject.toml(或直接在 dependencies 里引用包名与 requirements.txt 所在目录)。

推荐的干净目录结构如下:

text
my-langgraph-app/
├── .env                  # 存放 API Key(务必加入 .gitignore)
├── langgraph.json        # CLI 核心配置文件
├── pyproject.toml        # 声明 langgraph、langchain-openai 等依赖
└── src/
    └── agent.py          # 定义并导出 graph = builder.compile()

对应的最小 langgraph.json 只需寥寥几行(agent.py 内部的状态图写法见 /guides/langgraph-quickstart-install-first-graph):

json
{
  "dependencies": ["."],
  "graphs": {
    "support_bot": "./src/agent.py:graph",
    "code_helper": "./src/coder.py:coder_graph"
  },
  "env": ".env"
}

这里 "graphs" 可以登记多张不同的图:左边键名(如 "support_bot")是你在 Studio 下拉框或 HTTP 接口里看到的助手 ID,右边冒号前是源码路径,冒号后是文件顶层导出的变量名。

二、进阶字段示例:Python 版本、容器指令与异步图工厂

当你的项目需要接外部 MCP 服务(见 /guides/langgraph-mcp-integration-guide)、指定固定 Python 版本打包镜像、或者在系统容器里补装底层 C 库(例如编译驱动或字体包)时,可以扩展使用下面的完整字段:

json
{
  "python_version": "3.12",
  "dependencies": ["."],
  "graphs": {
    "mcp_agent": "./src/mcp_graph.py:make_graph"
  },
  "env": ".env",
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*"
  ],
  "auth": {
    "path": "./src/security.py:auth"
  }
}

里面有两个非常实用的工程技巧:

  1. 冒号后面不仅可以写编译好的变量,还可以写「无参或接收配置的图构造函数」(如上例的 :make_graph):当你的图在初始化阶段必须先异步拉取远程 MCP 工具列表时,无法在模块顶层直接同步写死 graph = ...,写成 async def make_graph(): ... return builder.compile() 交给服务端按需异步构建即可;
  2. dockerfile_lines 只在使用 Docker 构建命令(langgraph build / langgraph up)时生效:如果你平时只跑纯内存热重载的 langgraph dev,CLI 直接复用你当前的本地虚拟环境,不会执行 Docker 指令。

langgraph.json 常见启动报错排查

图:本站根据 LangGraph CLI 官方排错文档 整理的示意图

三、启动前必查的四条避坑清单

  1. 删掉手写的 checkpointer:自己单跑脚本测试时我们常写 builder.compile(checkpointer=InMemorySaver()),但切到 langgraph dev 前请改回无参的 builder.compile()(或把保存器留在 if __name__ == "__main__": 块里),让服务端接管线程持久化与时间旅行快照;
  2. .env 绝不进版本库:langgraph.json 本身只包含相对路径映射,应该提交进 Git 供全组共用;而 "env": ".env" 指向的密钥文件必须写进 .gitignore,团队可另外提交一份空的 .env.example 作为模板;
  3. 跨目录导入用标准包名:当 "dependencies": ["."] 把 src 安装为可编辑包后,agent.py 引用同仓库工具模块时请用规范的包绝对导入或显式相对导入,避免直接裸写依赖启动目录位置的导入路径;
  4. TypeScript 项目怎么配:如果是 JS / TS 版 LangGraph,同样叫 langgraph.json,只需把 python_version 换成 "node_version": "20",并确保根目录存在声明了依赖的 package.json 即可。

平时在本地结合大模型快速生成 pyproject.toml 与排查包版本锁冲突时,如需核对个人官方 ChatGPT 订阅方案,可参考 /chongzhi/chatgpt-plus 页面说明。

常见问题

Q:配置文件不放在项目根目录、放在子文件夹里可以吗?

可以,运行命令时加上 -c(或 --config)参数显式指定路径即可,例如 langgraph dev -c ./deploy/langgraph.json。但请记住文件内部写的 ./src/agent.py 和 .env 依然会相对于 deploy/ 文件夹去寻找,放在仓库根目录最不容易搞错层级。

Q:不想写 pyproject.toml,只用 requirements.txt 怎么填 dependencies?

如果暂时不想配 pyproject.toml,可以在项目目录放好 requirements.txt,或直接在 dependencies 数组里列出第三方包名(如 ["langchain_openai", "./src"]),让 CLI 直接把本地源码目录加入搜索路径并安装指定包。

相关教程

参考资料

  • LangChain / LangGraph 官方文档:CLI & Configuration file reference — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 仓库 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~