LangGraph Project Setup

Initialize and configure LangGraph projects for local development and deployment.

Quick Start

Python Project

# Initialize new project
uv run scripts/init_langgraph_project.py my-agent

# Fallback if uv not available
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
python3 scripts/init_langgraph_project.py my-agent \
  --pattern multiagent \
  --python-version 3.12

JavaScript Project

# Initialize new project
node scripts/init_langgraph_project.js my-agent

# TypeScript project
node scripts/init_langgraph_project.js my-agent --typescript

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

Setup Workflow

Step 1: Choose Project Pattern

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

Step 2: Initialize Project

Run the init script with your chosen pattern:

# Python - simple
uv run scripts/init_langgraph_project.py my-agent

# Fallback if uv not available
python3 scripts/init_langgraph_project.py my-agent

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

# Fallback if uv not available
python3 scripts/init_langgraph_project.py my-agent --pattern multiagent

# JavaScript/TypeScript - simple
node scripts/init_langgraph_project.js my-agent --typescript

# JavaScript/TypeScript - multi-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

Step 3: Install Dependencies

Python:

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

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

JavaScript:

cd my-agent
npm install  # or: yarn install / pnpm install

Step 4: Configure Environment Variables

Option A: Interactive Setup (Recommended)

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:

# Required: Choose at least one LLM provider
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.

Step 5: Implement Agent Logic

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

Step 6: Configure langgraph.json

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

{
  "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.

Step 7: Start Development Server

Option A: langgraph dev (Recommended for development)

langgraph dev

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

Option B: langgraph up (Production-like testing)

langgraph up

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

Step 8: Connect to LangGraph Studio

Access Studio in your browser:

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

Safari users: Use --tunnel flag:

langgraph dev --tunnel

Validation

Validate Configuration

uv run scripts/validate_langgraph_config.py

Checks:

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

Test Agent Locally

# Start server
langgraph dev

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

Common Configurations

Python with OpenAI

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

# agent.py
from langchain_openai import ChatOpenAI

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

Python with Anthropic

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

# agent.py
from langchain_anthropic import ChatAnthropic

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

JavaScript with OpenAI

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

// 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

Troubleshooting

"Module not found" errors

Ensure dependencies are installed:

# Python
uv pip install -e '.[dev]'

# Fallback if uv not available
pip install -e '.[dev]'

# JavaScript
npm install

"Graph not found" in langgraph.json

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)

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

Studio connection issues

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

Hot reload not working

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

Next Steps

After setup:

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

Scripts Reference

init_langgraph_project.py

Initialize Python project:

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

# Fallback if uv not available
python3 scripts/init_langgraph_project.py <name> [--pattern simple|multiagent] [--python-version 3.11|3.12|3.13]

init_langgraph_project.js

Initialize JavaScript project:

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

validate_langgraph_config.py

Validate langgraph.json:

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

# Fallback if uv not available
python3 scripts/validate_langgraph_config.py [path/to/langgraph.json]

setup_providers.py

Interactive provider setup:

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

# Fallback if uv not available
python3 scripts/setup_providers.py [--output .env]

Additional Resources

• •LangGraph Documentation
• •LangSmith Documentation
• •LangGraph CLI Reference
• •Application Structure Guide