LangGraph application composition
A LangGraph application consists of one or more graphs, a configuration file (langgraph.json), a file that specifies dependencies, and an optional .env file that specifies environment variables.
LangChain · LangGraph · all subjects
deployment
158 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
langgraph.json Python example with custom local package
Python langgraph.json example: { "dependencies": ["langchain_openai", "./your_package"], "graphs": { "my_agent": "./your_package/your_file.py:agent" }, "env": "./.env" }. This loads dependencies including a custom local package, loads a single graph from specified file with the agent variable, and loads environment variables from .env file.
Python project structure with pyproject.toml
A Python LangGraph project can use pyproject.toml instead of requirements.txt. Structure includes: my_agent directory containing utils subdirectory (with __init__.py, tools.py, nodes.py, state.py), __init__.py, and agent.py; plus .env file in root, pyproject.toml file, and langgraph.json file.
LangSmith Deployment platform
LangSmith Deployment is a managed hosting platform for deploying and scaling LangGraph agents. It handles infrastructure, scaling, and operational concerns, allowing deployment of stateful, long-running agents directly from a repository.
graphs key in configuration
The graphs key in the LangGraph configuration file specifies which graphs will be available in the deployed application. Each graph is identified by a unique name and a path for either the compiled graph or a function that creates a graph.
dependencies specification in LangGraph
Dependencies are specified in two ways: (1) a dependency file in the directory (requirements.txt, pyproject.toml for Python or package.json for JavaScript), and (2) a dependencies key in the langgraph.json configuration file. Additional binaries or system libraries can be specified using the dockerfile_lines key in langgraph.json.
langgraph.json required configuration
The langgraph.json file specifies the dependencies, graphs, environment variables, and other settings required to deploy a LangGraph application. It must include: dependencies (list of packages/paths), graphs (mapping of graph names to their file paths and functions), and env (path to .env file or inline environment variables).
langgraph.json JavaScript example with inline environment
JavaScript langgraph.json example: { "dependencies": ["."], "graphs": { "my_agent": "./your_package/your_file.js:agent" }, "env": { "OPENAI_API_KEY": "secret-key" } }. This loads dependencies from package.json, loads a single graph from the specified file with the agent function, and sets environment variables inline.
Python project structure with requirements.txt
A typical Python LangGraph project structure includes: my_agent directory containing utils subdirectory (with __init__.py, tools.py, nodes.py, state.py), __init__.py, and agent.py; plus .env file in root, requirements.txt file, and langgraph.json file.
JavaScript project structure
A typical JavaScript/TypeScript LangGraph project structure includes: src directory containing optional utils subdirectory (with tools.ts, nodes.ts, state.ts) and agent.ts file; plus package.json file, .env file in root, and langgraph.json file.
environment variables configuration
Environment variables can be configured in the env key of langgraph.json, either as a path to a .env file or as inline key-value pairs. For local development, use the env key; for production deployment, configure environment variables in the deployment environment.
REST API endpoint for streaming deployed agents
Deployed LangGraph agents can be accessed via REST API using a POST request to <DEPLOYMENT_URL>/runs/stream with Content-Type application/json header, X-Api-Key header with the LangSmith API key, and a JSON body containing: assistant_id (agent name from langgraph.json), input object with messages array, and stream_mode parameter.
Python SDK for accessing deployed LangGraph agents
To test a deployed LangGraph agent using Python: (1) Install the langgraph-sdk package with 'pip install langgraph-sdk', (2) Use get_sync_client() or get_client() to create a client with the deployment URL and API key, (3) Call client.runs.stream() with the agent name from langgraph.json, input messages, and stream_mode parameter.
LangSmith deployment options beyond Cloud
LangSmith offers multiple deployment options including hybrid deployment, standalone servers, and self-hosted deployment with control plane, in addition to LangSmith Cloud.
Agent Streaming Protocol for LangGraph deployment
LangGraph uses the Agent Streaming Protocol for deployment across various platforms. This protocol is documented at https://github.com/langchain-ai/agent-protocol/tree/main/streaming and enables consistent streaming behavior across JavaScript frameworks and other deployment targets.
Testing deployed LangGraph agent in Studio
Once your agent is deployed to LangSmith Cloud, you can select the deployment in the Deployment details view and click the Studio button in the top right corner to view your graph and test the agent.
LangSmith Cloud deployment for stateful agents
LangSmith Cloud provides fully managed infrastructure for stateful, long-running agents with persistent state and background execution. It handles infrastructure, scaling, and operational concerns.
LangSmith Cloud repository requirements
Your application code must reside in a GitHub repository to be deployed on LangSmith Cloud. Both public and private repositories are supported.
LangSmith Cloud deployment process overview
To deploy to LangSmith Cloud: (1) Create a repository on GitHub and push your LangGraph-compatible code to it, (2) Navigate to Deployments in LangSmith and click +New Deployment, (3) Connect your GitHub account if needed, (4) Select your repository and click Submit. Deployment typically takes about 15 minutes.
JavaScript deployment frameworks supported by LangGraph
LangGraph agents can be deployed on JavaScript frameworks and platforms including Next.js, SvelteKit, Nuxt, Cloudflare Workers, and Deno Deploy using the Agent Streaming Protocol.
Prerequisites for deploying to LangSmith Cloud
To deploy to LangSmith Cloud, you need a GitHub account and a LangSmith account (free to sign up).
Getting API URL from LangGraph deployment
In the Deployment details view in LangGraph, you can click the API URL to copy it to your clipboard for testing and accessing your deployed agent.
TypeScript SDK for accessing deployed LangGraph agents
To test a deployed LangGraph agent using TypeScript: (1) Install the SDK with 'npm install @langchain/langgraph-sdk', (2) Create a Client with apiUrl and apiKey, (3) Call client.runs.stream() with null for threadless run, agent name from langgraph.json, input with messages, and streamMode parameter.
Graph-native runtime concepts for frontend
Frontend SDK exposes runtime concepts directly to the UI: Named nodes map to one card, timeline step, or status badge per graph node. State keys provide dedicated UI regions for typed outputs. Streaming metadata routes partial messages to the node that produced them. Checkpoints allow inspection or resumption from prior graph states for debugging and auditability. Interrupts pause a node for human input, approval, or correction, then continue. Subgraphs reveal nested execution only when needed for detail.
Frontend SDK v1 migration guides
The current frontend patterns use the v1 frontend SDK packages. Earlier versions require migration guides for React, Vue, Svelte, and Angular frameworks.
LangGraph frontend architecture overview
LangGraph graphs are composed of named nodes connected by edges. Each node executes a step and writes output to a specific state key. On the frontend, the SDK stream handler provides reactive access to node outputs, streaming tokens, and discovered subgraphs, allowing each node to be mapped to a UI card.
Custom graphs power product workflows
Custom graphs using StateGraph often power product workflows including research pipelines, approval flows, data pipelines, data enrichment, code review, planning, and multi-step analysis.
useStream hook exposes graph structure
The useStream hook from @langchain/react exposes stream.subgraphs for graph-node discovery and selector helpers such as useMessages(stream, node) for node-scoped streaming content. stream.values holds the full graph state when you need access to fields like the final synthesis output.
Scale from chat panel to workflow debugger without backend changes
Because the frontend SDK exposes graph concepts directly (nodes, state, checkpoints, interrupts, subgraphs), you can scale from a simple chat panel to a full workflow debugger without changing the backend protocol.
Frontend advantage of LangGraph UI alignment with graph structure
LangGraph's frontend advantage is that the UI can follow the same structure as the graph. Nodes, state keys, checkpoints, interrupts, subgraphs, and streamed messages are all visible runtime concepts, allowing interfaces to explain what the system is doing instead of hiding execution behind a single assistant message.
Frontend SDK works across LangChain agent types
The frontend stream API provides the same core data model whether using createAgent, createDeepAgent, or a custom StateGraph. This means frontend patterns like markdown messages, tool calling, human-in-the-loop, resumable streams, and time travel work with any LangGraph graph.
useStream API shape with TypeScript support
The useStream hook accepts configuration with apiUrl and assistantId parameters. It returns a typed stream object where stream.values contains the full graph state (including fields like classification, research, analysis, synthesis) and stream.subgraphs provides access to nested graph definitions.
Install LangChain JavaScript package with yarn
To install LangChain JavaScript package using yarn, run: yarn add langchain
Install LangChain JavaScript package with bun
To install LangChain JavaScript package using bun, run: bun add langchain
Install LangChain JavaScript package with pnpm
To install LangChain JavaScript package using pnpm, run: pnpm add langchain
Install LangGraph base package with uv
To install the base LangGraph package using uv, run: uv add langgraph
Install LangGraph JavaScript package with bun
To install the LangGraph JavaScript package using bun, run: bun add @langchain/langgraph @langchain/core
Install LangGraph JavaScript package with yarn
To install the LangGraph JavaScript package using yarn, run: yarn add @langchain/langgraph @langchain/core
Install LangGraph JavaScript package with pnpm
To install the LangGraph JavaScript package using pnpm, run: pnpm add @langchain/langgraph @langchain/core
Install LangGraph base package with pip
To install the base LangGraph package using pip, run: pip install -U langgraph
Install LangChain with uv
To install LangChain with uv, run: uv add langchain. This requires Python 3.10 or later.
Install LangChain with pip
To install LangChain with pip, run: pip install -U langchain. This requires Python 3.10 or later.
LLM provider packages must be installed separately
To work with specific LLM provider packages, you must install them separately. Refer to the integrations page for provider-specific installation instructions.
Launch LangGraph local development server
Start the LangGraph API server locally using `langgraph dev` (Python) or `npx @langchain/langgraph-cli dev` (JavaScript). The server starts in in-memory mode, suitable for development and testing, at default URL http://127.0.0.1:2024.
Prerequisites for running LangGraph local server
Before beginning, ensure you have an API key for LangSmith (free to sign up at https://smith.langchain.com/settings).
Test LangGraph local server with REST API
Send a POST request to http://localhost:2024/runs/stream with Content-Type: application/json. The request body must include "assistant_id" (e.g., "agent"), "input" with the message data, and "stream_mode" (e.g., "messages-tuple").
Install LangGraph app dependencies
After creating a new LangGraph app, install dependencies in edit mode. For pip: `cd path/to/your/app` then `pip install -e .`. For uv: `cd path/to/your/app` then `uv sync`. For JavaScript: `cd path/to/your/app` then `npm install`. Edit mode ensures local changes are used by the server.
Test LangGraph local server with Python SDK sync
Install LangGraph Python SDK with `pip install langgraph-sdk`. Then use the sync client to test: import `get_sync_client` from `langgraph_sdk`, create client with `get_sync_client(url="http://localhost:2024")`, and stream runs using `client.runs.stream(None, "agent", input={...}, stream_mode="messages-tuple")` with None for threadless run.
Safari compatibility with local LangGraph server
Safari has limitations when connecting to localhost servers. Use the `--tunnel` flag with `langgraph dev --tunnel` to create a secure tunnel for Safari compatibility.
Connect to LangGraph Studio for local testing
Test your LangGraph application using Studio, a specialized UI that visualizes, interacts with, and debugs your application locally. Access Studio by visiting the URL provided in the output of the `langgraph dev` command, such as https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024. For custom host/port, update the baseUrl query parameter.
In-memory server use case and production deployment
The `langgraph dev` command starts Agent Server in in-memory mode, which is suitable only for development and testing purposes. For production use, deploy Agent Server with access to a persistent storage backend through LangSmith Deployment.
LangGraph local server default endpoints
The local LangGraph server provides: API at http://127.0.0.1:2024, Studio UI at https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024, and API Docs at http://127.0.0.1:2024/docs.
Configure LangSmith API key in .env file
Create a `.env` file in the root of your LangGraph app. Copy the contents from the `.env.example` file and fill in necessary API keys. At minimum, include `LANGSMITH_API_KEY=lsv2...`
Test LangGraph local server with JavaScript SDK
Install LangGraph JS SDK with `npm install @langchain/langgraph-sdk`. Create a client with `new Client({ apiUrl: "http://localhost:2024" })` and stream using `client.runs.stream(null, "agent", { input: {...}, streamMode: "messages-tuple" })` where null indicates a threadless run.
Generate langgraph.json configuration for existing projects
For existing JavaScript projects with LangGraph agents, use `npm create langgraph config` to automatically scan for LangGraph agents (such as `createAgent()`, `StateGraph.compile()`, or `workflow.compile()` patterns) and generate a `langgraph.json` configuration file with all exported agents. Only exported agents are included; non-exported agents will trigger a warning.
Create new LangGraph project from template
Create a new LangGraph application using the command `langgraph new path/to/your/app --template new-langgraph-project-python` (Python) or `npm create langgraph` (JavaScript). Running `langgraph new` without a template flag presents an interactive menu to choose from available templates.
LangGraph CLI installation commands
To install the LangGraph CLI, use one of these commands depending on your package manager. For pip: `pip install -U "langgraph-cli[inmem]"` (Python >= 3.11 required). For uv: `uv add "langgraph-cli[inmem]"` (Python >= 3.11 required). For JavaScript/npm: `npm install --save-dev @langchain/langgraph-cli`.
Agent Server handles persistence automatically
When using the Agent Server, you do not need to implement or configure checkpointers or stores manually. The server handles persistence infrastructure behind the scenes.
LangSmith base store available by default locally
When using LangSmith locally (e.g., in Studio) or hosted, the base store is available by default and does not need to be specified during graph compilation. To enable semantic search, configure indexing settings in langgraph.json file.
Agent Server handles stores automatically
When using Agent Server, stores are handled automatically and do not need to be implemented or configured manually. The API handles all storage infrastructure behind the scenes.