应用结构

📚 学习目标

学完这篇文章后，你将能够：

组织一个清晰、可扩展的 LangGraph 项目目录
编写规范的 langgraph.json 和 package.json
管理多环境配置（Development vs Production）

前置知识

在开始学习之前，建议先阅读：

01-langgraph-platform

1 推荐目录结构

一个健壮的 LangGraph 项目应该像这样组织：

my-agent/
├── src/
│   ├── agent.ts           # 图的组装入口 (Entrypoint)
│   ├── nodes/             # 节点逻辑
│   │   ├── chatbot.ts
│   │   └── tools.ts
│   ├── state/             # State 定义
│   │   └── index.ts
│   ├── tools/             # 自定义工具
│   │   └── search.ts
│   └── utils/             # 辅助函数
├── tests/                 # 测试
├── .env                   # 环境变量 (不要提交!)
├── langgraph.json         # 部署配置
├── package.json           # 依赖管理
└── tsconfig.json          # TS 配置

你可以把它理解为三层：

层	目录	关注点
入口层	`src/agent.ts`	只负责组装与导出 graph
能力层	`nodes/` `tools/` `state/`	业务能力、外部工具、状态定义
工程层	`tests/` `langgraph.json` `.env`	运行/部署/测试/配置

2 关键文件详解

`src/agent.ts`

这是图的 "Main" 文件。它负责导入所有节点和边，并 compile 出 app。

import { StateGraph, START } from "@langchain/langgraph";
import { State } from "./state";
import { chatbotNode } from "./nodes/chatbot";

const workflow = new StateGraph(State)
  .addNode("chatbot", chatbotNode)
  .addEdge(START, "chatbot");

export const graph = workflow.compile();

[!TIP] 让 agent.ts 保持“干净”：它只负责组装图，不要塞入业务细节（例如 HTTP 请求、数据库连接创建）。这样更好测试、也更好部署。

`package.json`

确保依赖清晰。

{
  "name": "my-agent",
  "dependencies": {
    "@langchain/langgraph": "^0.2.0",
    "@langchain/openai": "^0.3.0"
  }
}

`langgraph.json`

指向 agent.ts 中导出的 graph。

{
  "graphs": {
    "agent": "./src/agent.ts:graph"
  }
}

如果你有多个图（例如：chat / rag / codegen），可以一起声明：

{
  "graphs": {
    "chat": "./src/graphs/chat.ts:graph",
    "rag": "./src/graphs/rag.ts:graph"
  }
}

3 环境变量与配置

永远不要在代码中硬编码 API Key。

本地开发

使用 .env 文件。

生产环境

在 LangGraph Platform 的控制台（或 Docker 环境变量）中设置 OPENAI_API_KEY 等。

// 推荐使用 zod 验证环境变量
import { z } from "zod";

const envSchema = z.object({
  OPENAI_API_KEY: z.string(),
  TAVILY_API_KEY: z.string().optional(),
});

export const env = envSchema.parse(process.env);

建议你把“配置”分成两类：

配置类型	载体	特点	例子
静态配置	环境变量 `.env`	部署时决定	API Key、数据库 DSN
动态配置	`RunnableConfig`	每次请求决定	modelName、tenantId、thread_id

动态配置相关内容见：配置管理与 Configurable。

💡 练习题

重构题：你现有的代码可能都在一个 index.ts 里。尝试按照上面的目录结构，将 State、Nodes 和 Tools 拆分到不同的文件中。

点击查看答案
推荐最小拆分：state.ts（Annotation）、nodes/*.ts、tools/*.ts、graph.ts（装配与 compile）。这样可以让状态定义、节点逻辑、工具实现解耦，后续测试和替换都更容易。
设计题：如果你要支持“同一套 Graph，不同用户使用不同模型/不同温度”，你会把配置放在 .env 还是 RunnableConfig？为什么？

点击查看答案
应优先放在 RunnableConfig，因为这是“每次调用可变”的运行时参数。 .env 更适合部署级固定配置（如 API Base URL、默认模型），不适合用户级动态差异。

✅ 总结

本章要点：

结构化：nodes/, state/, tools/ 分离，有助于维护。
Entrypoint：agent.ts 只负责组装。
Config：使用 langgraph.json 声明入口。

下一步：最好的开发体验是什么样的？继续学习：LangGraph Studio。

登录以继续阅读

解锁完整文档、代码示例及更多高级功能。

立即登录

应用结构

登录以继续阅读

On this page