langgraph-project-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangGraph Project Setup

LangGraph项目搭建

Initialize and configure LangGraph projects for local development and deployment.

为本地开发和部署初始化并配置LangGraph项目。

Quick Start

快速开始

Python Project

Python项目

bash

undefined

bash

undefined

Initialize new project

初始化新项目

uv run scripts/init_langgraph_project.py my-agent

Fallback if uv not available

若uv不可用的备用方案

python3 scripts/init_langgraph_project.py my-agent

Or with options

带参数的初始化

uv run scripts/init_langgraph_project.py my-agent
--pattern multiagent
--python-version 3.12

Fallback if uv not available

若uv不可用的备用方案

python3 scripts/init_langgraph_project.py my-agent
--pattern multiagent
--python-version 3.12

undefined

python3 scripts/init_langgraph_project.py my-agent
--pattern multiagent
--python-version 3.12

undefined

JavaScript Project

JavaScript项目

bash

undefined

bash

undefined

Initialize new project

初始化新项目

node scripts/init_langgraph_project.js my-agent

TypeScript project

TypeScript项目

node scripts/init_langgraph_project.js my-agent --typescript

Multi-agent pattern

多Agent模式

node scripts/init_langgraph_project.js my-agent
--pattern multiagent
--typescript

undefined

node scripts/init_langgraph_project.js my-agent
--pattern multiagent
--typescript

undefined

Setup Workflow

搭建流程

Step 1: Choose Project Pattern

步骤1：选择项目模式

Simple Pattern: Single agent with straightforward workflow

Best for: Getting started, prototypes, single-purpose agents
Structure: Minimal files, agent.py/agent.ts at package root

Multi-Agent Pattern: Modular architecture with separated concerns

Best for: Complex workflows, multiple agents, production applications
Structure: utils/ directory with state.py, nodes.py, tools.py

简单模式： 单一Agent搭配简洁工作流

适用场景：入门学习、原型开发、单一功能Agent
结构：极简文件，agent.py/agent.ts位于包根目录

多Agent模式： 模块化架构，职责分离

适用场景：复杂工作流、多Agent协作、生产级应用
结构：utils/目录包含state.py、nodes.py、tools.py

Step 2: Initialize Project

步骤2：初始化项目

Run the init script with your chosen pattern:

bash

undefined

运行初始化脚本并选择对应模式：

bash

undefined

Python - simple

Python - 简单模式

uv run scripts/init_langgraph_project.py my-agent

Fallback if uv not available

若uv不可用的备用方案

python3 scripts/init_langgraph_project.py my-agent

Python - multi-agent

Python - 多Agent模式

uv run scripts/init_langgraph_project.py my-agent --pattern multiagent

Fallback if uv not available

若uv不可用的备用方案

python3 scripts/init_langgraph_project.py my-agent --pattern multiagent

JavaScript/TypeScript - simple

JavaScript/TypeScript - 简单模式

node scripts/init_langgraph_project.js my-agent --typescript

JavaScript/TypeScript - multi-agent

JavaScript/TypeScript - 多Agent模式

node scripts/init_langgraph_project.js my-agent --pattern multiagent --typescript


The script creates:
- Project directory structure
- `langgraph.json` configuration
- `.env` template
- Dependency files (pyproject.toml or package.json)
- `.gitignore`
- Boilerplate code with TODO comments

node scripts/init_langgraph_project.js my-agent --pattern multiagent --typescript


脚本会创建以下内容：
- 项目目录结构
- `langgraph.json`配置文件
- `.env`模板文件
- 依赖管理文件（pyproject.toml或package.json）
- `.gitignore`文件
- 包含TODO注释的样板代码

Step 3: Install Dependencies

步骤3：安装依赖

Python:

bash

cd my-agent
uv venv --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e '.[dev]'

Python：

bash

cd my-agent
uv venv --python 3.12
source .venv/bin/activate  # Windows系统：.venv\Scripts\activate
uv pip install -e '.[dev]'

Fallback if uv not available

若uv不可用的备用方案

python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e '.[dev]'


**JavaScript:**
```bash
cd my-agent
npm install  # or: yarn install / pnpm install

python3 -m venv venv source venv/bin/activate # Windows系统：venv\Scripts\activate pip install -e '.[dev]'


**JavaScript：**
```bash
cd my-agent
npm install  # 或：yarn install / pnpm install

Step 4: Configure Environment Variables

步骤4：配置环境变量

Option A: Interactive Setup (Recommended)

bash

uv run scripts/setup_providers.py

Follow the prompts to configure:

OpenAI
Anthropic (Claude)
Google (Gemini)
AWS Bedrock
LangSmith (tracing)
Tavily (search)

Option B: Manual Configuration

Edit

.env

file directly:

bash

undefined

选项A：交互式配置（推荐）

bash

uv run scripts/setup_providers.py

按照提示配置以下服务：

OpenAI
Anthropic（Claude）
Google（Gemini）
AWS Bedrock
LangSmith（追踪）
Tavily（搜索）

选项B：手动配置

直接编辑

.env

文件：

bash

undefined

Required: Choose at least one LLM provider

必填：至少选择一个LLM提供商

OPENAI_API_KEY=sk-...

or

或

ANTHROPIC_API_KEY=sk-ant-...

Optional: Enable tracing

可选：启用追踪

LANGSMITH_API_KEY=lsv2_... LANGSMITH_TRACING=true LANGSMITH_PROJECT=my-project


See `references/provider-configuration.md` for provider-specific setup.

LANGSMITH_API_KEY=lsv2_... LANGSMITH_TRACING=true LANGSMITH_PROJECT=my-project


查看`references/provider-configuration.md`获取提供商专属配置指南。

Step 5: Implement Agent Logic

步骤5：实现Agent逻辑

Replace TODO comments in generated files:

Python Simple:

Edit
```
my_agent/agent.py
```
Configure LLM in
```
call_model
```
function

Python Multi-Agent:

Define state schema in
```
my_agent/utils/state.py
```
Implement node logic in
```
my_agent/utils/nodes.py
```
Add tools in
```
my_agent/utils/tools.py
```
Build graph in
```
my_agent/agent.py
```

JavaScript/TypeScript:

Similar structure in
```
src/
```
directory
Import appropriate LangChain packages

替换生成文件中的TODO注释：

Python简单模式：

编辑
```
my_agent/agent.py
```
在
```
call_model
```
函数中配置LLM

Python多Agent模式：

在
```
my_agent/utils/state.py
```
中定义状态 schema
在
```
my_agent/utils/nodes.py
```
中实现节点逻辑
在
```
my_agent/utils/tools.py
```
中添加工具
在
```
my_agent/agent.py
```
中构建图

JavaScript/TypeScript：

结构与Python类似，位于
```
src/
```
目录
导入对应的LangChain包

Step 6: Configure langgraph.json

步骤6：配置langgraph.json

The init script creates a basic configuration. Customize as needed:

json

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./my_agent/agent.py:graph"
  },
  "env": ".env",
  "python_version": "3.11"
}

Key configuration options:

```
dependencies
```
: Package dependencies location
```
graphs
```
: Mapping of graph IDs to code paths
```
env
```
: Path to environment file
```
python_version
```
or
```
node_version
```
: Runtime version

For complete schema reference, see

references/langgraph-json-schema.md

初始化脚本会创建基础配置，可按需自定义：

json

{
  "dependencies": ["..."],
  "graphs": {
    "agent": "./my_agent/agent.py:graph"
  },
  "env": ".env",
  "python_version": "3.11"
}

核心配置选项：

```
dependencies
```
：包依赖的位置
```
graphs
```
：图ID到代码路径的映射
```
env
```
：环境文件路径
```
python_version
```
或
```
node_version
```
：运行时版本

完整schema参考请查看

references/langgraph-json-schema.md

。

Step 7: Start Development Server

步骤7：启动开发服务器

Option A: langgraph dev (Recommended for development)

bash

langgraph dev

No Docker required
In-memory state persistence
Hot reloading enabled
Default port: 2024

Option B: langgraph up (Production-like testing)

bash

langgraph up

Docker required
PostgreSQL state persistence
Production environment simulation
Default port: 8123

选项A：langgraph dev（开发推荐）

bash

langgraph dev

无需Docker
内存状态持久化
支持热重载
默认端口：2024

选项B：langgraph up（类生产环境测试）

bash

langgraph up

需要Docker
PostgreSQL状态持久化
模拟生产环境
默认端口：8123

Step 8: Connect to LangGraph Studio

步骤8：连接LangGraph Studio

Access Studio in your browser:

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

Safari users: Use

--tunnel

flag:

bash

langgraph dev --tunnel

在浏览器中访问Studio：

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

Safari用户： 使用

--tunnel

参数：

bash

langgraph dev --tunnel

Validation

验证

Validate Configuration

验证配置

bash

uv run scripts/validate_langgraph_config.py

Checks:

Required fields (dependencies, graphs)
File paths and references
Optional field formats
Common configuration errors

bash

uv run scripts/validate_langgraph_config.py

检查内容：

必填字段（dependencies、graphs）
文件路径与引用
可选字段格式
常见配置错误

Test Agent Locally

本地测试Agent

bash

undefined

bash

undefined

Start server

启动服务器

langgraph dev

In another terminal, test with curl

在另一个终端中用curl测试

curl -X POST http://localhost:2024/invoke
-H "Content-Type: application/json"
-d '{"input": {"messages": [{"role": "user", "content": "Hello"}]}}'

undefined

curl -X POST http://localhost:2024/invoke
-H "Content-Type: application/json"
-d '{"input": {"messages": [{"role": "user", "content": "Hello"}]}}'

undefined

Common Configurations

常见配置示例

Python with OpenAI

搭配OpenAI的Python项目

toml

undefined

toml

undefined

pyproject.toml

[project.optional-dependencies] openai = ["langchain-openai>=1.1.0"]


```python

[project.optional-dependencies] openai = ["langchain-openai>=1.1.0"]


```python

agent.py

from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-4o-mini")

undefined

from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-4o-mini")

undefined

Python with Anthropic

搭配Anthropic的Python项目

toml

undefined

toml

undefined

pyproject.toml

[project.optional-dependencies] anthropic = ["langchain-anthropic>=1.1.0"]


```python

[project.optional-dependencies] anthropic = ["langchain-anthropic>=1.1.0"]


```python

agent.py

from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-haiku-4-5-20251001")

undefined

from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-haiku-4-5-20251001")

undefined

JavaScript with OpenAI

搭配OpenAI的JavaScript项目

json

// package.json
{
  "dependencies": {
    "@langchain/openai": "^1.1.0"
  }
}

typescript

// agent.ts
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({ model: "gpt-4o-mini" });

json

// package.json
{
  "dependencies": {
    "@langchain/openai": "^1.1.0"
  }
}

typescript

// agent.ts
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({ model: "gpt-4o-mini" });

Project Structure Reference

项目结构参考

Python structures:
```
references/python-project-structure.md
```

JavaScript structures:

references/javascript-project-structure.md

langgraph.json schema:
```
references/langgraph-json-schema.md
```
Provider setup:
```
references/provider-configuration.md
```
Deployment options:
```
references/deployment-targets.md
```

Python项目结构：
```
references/python-project-structure.md
```

JavaScript项目结构：

references/javascript-project-structure.md

langgraph.json schema：
```
references/langgraph-json-schema.md
```
提供商配置：
```
references/provider-configuration.md
```
部署选项：
```
references/deployment-targets.md
```

Troubleshooting

故障排除

"Module not found" errors

"Module not found"错误

Ensure dependencies are installed:

bash

undefined

确保依赖已安装：

bash

undefined

Python

uv pip install -e '.[dev]'

Fallback if uv not available

若uv不可用的备用方案

pip install -e '.[dev]'

JavaScript

npm install

undefined

npm install

undefined

"Graph not found" in langgraph.json

langgraph.json中"Graph not found"错误

Check graph path format:

Python:
```
./package_name/agent.py:graph
```
JavaScript:
```
./src/agent.ts:graph
```

Validate:

uv run scripts/validate_langgraph_config.py

(fallback:

python3 scripts/validate_langgraph_config.py

)

检查图路径格式：

Python：
```
./package_name/agent.py:graph
```
JavaScript：
```
./src/agent.ts:graph
```

运行验证脚本：

uv run scripts/validate_langgraph_config.py

（备用：

python3 scripts/validate_langgraph_config.py

）

Environment variables not loading

环境变量未加载

Check
```
.env
```
file exists in project root
Verify
```
"env": ".env"
```
in langgraph.json
Ensure no quotes around values in .env
Restart development server after changes

检查项目根目录是否存在
```
.env
```
文件
确认langgraph.json中配置了
```
"env": ".env"
```
确保.env文件中的值没有加引号
修改后重启开发服务器

Studio connection issues

Studio连接问题

Verify server is running:
```
langgraph dev
```
Check correct port (default: 2024)
Safari users: use
```
--tunnel
```
flag
Check firewall/security software

确认服务器已启动：
```
langgraph dev
```
检查端口是否正确（默认：2024）
Safari用户：使用
```
--tunnel
```
参数
检查防火墙/安全软件设置

Hot reload not working

热重载不生效

Ensure using
```
langgraph dev
```
(not
```
langgraph up
```
)
Check file is in correct directory
Try manual restart if needed

确保使用的是
```
langgraph dev
```
（而非
```
langgraph up
```
）
检查文件是否在正确的目录中
必要时手动重启服务器

Next Steps

后续步骤

After setup:

Implement agent logic (replace TODOs)
Add tools and nodes as needed
Test with Studio
Write tests (see langgraph-testing-evaluation skill)
Deploy to LangSmith (see langsmith-deployment skill)

搭建完成后：

实现Agent逻辑（替换TODO注释）
按需添加工具和节点
使用Studio进行测试
编写测试用例（参考langgraph-testing-evaluation技能）
部署到LangSmith（参考langsmith-deployment技能）

Scripts Reference

脚本参考

init_langgraph_project.py

Initialize Python project:

bash

uv run scripts/init_langgraph_project.py <name> [--pattern simple|multiagent] [--python-version 3.11|3.12|3.13]

初始化Python项目：

bash

uv run scripts/init_langgraph_project.py <name> [--pattern simple|multiagent] [--python-version 3.11|3.12|3.13]

Fallback if uv not available

若uv不可用的备用方案

python3 scripts/init_langgraph_project.py <name> [--pattern simple|multiagent] [--python-version 3.11|3.12|3.13]

undefined

python3 scripts/init_langgraph_project.py <name> [--pattern simple|multiagent] [--python-version 3.11|3.12|3.13]

undefined

init_langgraph_project.js

Initialize JavaScript project:

bash

node scripts/init_langgraph_project.js <name> [--pattern simple|multiagent] [--typescript]

初始化JavaScript项目：

bash

node scripts/init_langgraph_project.js <name> [--pattern simple|multiagent] [--typescript]

validate_langgraph_config.py

Validate langgraph.json:

bash

uv run scripts/validate_langgraph_config.py [path/to/langgraph.json]

验证langgraph.json：

bash

uv run scripts/validate_langgraph_config.py [path/to/langgraph.json]

Fallback if uv not available

若uv不可用的备用方案

python3 scripts/validate_langgraph_config.py [path/to/langgraph.json]

undefined

python3 scripts/validate_langgraph_config.py [path/to/langgraph.json]

undefined

setup_providers.py

Interactive provider setup:

bash

uv run scripts/setup_providers.py [--output .env]

交互式提供商配置：

bash

uv run scripts/setup_providers.py [--output .env]

Fallback if uv not available

若uv不可用的备用方案

python3 scripts/setup_providers.py [--output .env]

undefined

python3 scripts/setup_providers.py [--output .env]

undefined