[LangGraph] 应用结构

核心模块

使用 langsmith 部署 langgraph 应用的时候，需要提供以下信息：

1. langgraph.json：这是一个配置文件，用于指定应用所需的依赖、graph 和环境变量。相当于告诉系统：

   1. 这个应用需要哪些依赖
   2. 有哪些graph
   3. graph对应的映射关系
   4. 环境变量

2. 实现应用逻辑的一个或多个 graph。

   1. StateGraph
   2. FunctionAPI

3. 一个依赖声明文件，列出运行该应用所需的依赖项。

   1. JS / TS：package.json
   2. Python：pyproject.toml / requirements.txt

4. 应用运行所需的环境变量。

   1. 本地开发：.env
   2. 生产部署：平台注入

为什么 langgraph 官方强调这样的应用结构？

因为 langgraph 从一开始就假设一件事：你的 Agent 应用是：

1. 长期运行
2. 有状态
3. 可部署

所以它必须解决三件工程问题：

1. 别人如何加载你的 Graph？
2. 运行环境如何自动安装依赖？
3. 部署平台如何知道你要暴露哪些能力？

所以才会有 langgraph.json 这个配置文件。

推荐目录结构

my-app/
├── src
│   ├── utils
│   │   ├── tools.ts   // 工具
│   │   ├── nodes.ts   // 节点函数
│   │   └── state.ts   // State 定义
│   └── agent.ts       // 构建 graph 的入口
├── package.json       // 依赖
├── .env               // 本地环境变量
└── langgraph.json     // LangGraph 配置

目录说明

1. Graph 的“入口文件”一定要清晰

   1. 比如 agent.ts

   2. 要么导出一个编译后的图的实例

   3. 要么导出一个工厂函数，执行该工厂函数能够得到一个图的实例

2. src 怎么拆是你的自由

3. langgraph.json 一定在根目录

langgraph.json

一个最简单的示例

{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./src/agent.js:agent"
  },
  "env": {
    "OPENAI_API_KEY": "secret-key"
  }
}

langgraph 并不是只关心你写了什么 Graph，它更关心这个 Graph 能不能被别人可靠地运行。所以它要求你明确：

• Graph 在哪
• 依赖怎么装
• 变量从哪来

支持多个Graph的应用

一个 langgraph 应用 ≠ 只有一个 Graph，一个 langgraph 应用可以是多个 Graph 的集合。

常见的使用多图的真实场景

1. 场景 1：不同业务流程，不同 Graph。逻辑完全不同，硬塞进一个 Graph 会非常痛苦

   • 客服对话 Agent

   • 工单处理 Agent

   • 内容生成 Agent

2. 场景 2：同一业务，不同版本，多 Graph 就是天然的版本隔离

   • chat_v1：基础版

   • chat_v2：支持工具

   • chat_experimental：实验版本

3. 场景 3：对外暴露不同能力。Graph 本身就像“函数”，应用是“函数集合”

   • 一个 Graph 给 Web UI 用

   • 一个 Graph 给 API 调用

   • 一个 Graph 给内部系统自动跑

langgraph 如何支持多 Graph？

{
  "graphs": {
    "chat_agent": "./src/chatAgent.js:agent",
    "order_agent": "./src/orderAgent.js:agent",
    "summary_agent": "./src/summaryAgent.js:agent"
  }
}

graphs 就是这个应用的“Graph 注册表”：

• key：Graph 名字，作为对外标识
• value：Graph 的加载方式

多Graph项目结构

下面是一个多 graph 的企业级应用所推荐的目录结构：

my-app/
├── src
│   ├── client
│   │   └── run.ts                 # CLI / Web / API 入口
│   │
│   ├── graphs                     # LangGraph 核心：多 Graph
│   │   ├── chat                   # 对话型 Graph
│   │   │   ├── state.ts
│   │   │   ├── nodes.ts
│   │   │   └── agent.ts
│   │   │
│   │   ├── order                  # 流程型 Graph（业务流）
│   │   │   ├── state.ts
│   │   │   ├── nodes.ts
│   │   │   └── agent.ts
│   │   │
│   │   └── summary                # 能力型 Graph（可作为子图）
│   │       └── agent.ts
│   │
│   ├── shared                     # 共享层（不含业务流程）
│   │   ├── llm.ts                 # LLM 创建与配置
│   │   │
│   │   ├── tools                  # 工具目录
│   │   │   ├── index.ts           # 工具统一出口
│   │   │   │
│   │   │   ├── travel             # 按领域拆
│   │   │   │   ├── weather.tool.ts
│   │   │   │   ├── ticket.tool.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── order
│   │   │   │   ├── create.tool.ts
│   │   │   │   ├── query.tool.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── common
│   │   │   │   ├── search.tool.ts
│   │   │   │   └── time.tool.ts
│   │   │   │
│   │   │   └── types.ts           # Tool schema / 类型定义
│   │   │
│   │   ├── utils                  # 共享工具函数（非 LangGraph Tool）
│   │   │   ├── logger.ts
│   │   │   └── http.ts
│   │   │
│   │   └── config                 # 配置集中管理（可选）
│   │       └── env.ts
│   │
│   └── index.ts                   # 应用启动（可选）
│
├── tests                          # 测试目录（与 src 平级）
│   ├── chat
│   │   ├── chat.agent.test.ts     # Graph 级测试
│   │   ├── chat.nodes.test.ts     # Node 级测试
│   │   └── chat.state.test.ts     # State / reducer / zod 测试
│   │
│   ├── order
│   │   ├── order.agent.test.ts
│   │   └── order.flow.test.ts
│   │
│   ├── summary
│   │   └── summary.agent.test.ts
│   │
│   ├── tools
│   │   ├── weather.tool.test.ts
│   │   └── order.tool.test.ts
│   │
│   ├── shared
│   │   └── llm.test.ts            # LLM测试，测试创建和使用大模型的方式是不是可控、可替换、可测试的
│   │
│   └── fixtures                   # 测试夹具：专门给测试用的样本/假数据/模拟环境
│       ├── messages.ts
│       ├── mockState.ts
│       └── mockTools.ts
│
├── langgraph.json                 # Graph 注册
├── package.json
├── pnpm-lock.yaml
├── .env
└── README.md

这个结构背后的设计思想：

1. 一个 Graph 对应一个独立目录，天然隔离，天然可维护

   • 该图自己的 state

   • 该图自己的 nodes

   • 该图自己的 agent 入口

2. shared 放跨 Graph 复用的东西，例如：

   • LLM 实例
   • 通用工具
   • 公共 Prompt

3. langgraph.json 只做注册

   {
     "graphs": {
       "chat": "./src/graphs/chat/agent.js:agent",
       "order": "./src/graphs/order/agent.js:agent",
       "summary": "./src/graphs/summary/agent.js:agent"
     }
   }
   

注意点

1. Graph 之间不要互相调用，组合靠上层，不靠 Graph 内部

2. Graph 内部追求自洽

3. 应用层只做针对图的路由以及管理工作

应用层：注册+暴露

注册：langgraph.json

暴露：图的入口文件

---

-EOF-