Principle:Langchain ai Langgraph Graph Module Definition
| Property | Value |
|---|---|
| Concept | Defining and Registering Graph Modules for Deployment via Configuration |
| Category | Module Resolution |
| Scope | CLI Deployment Workflow |
| Related Workflow | CLI_Deployment |
Overview
Graph Module Definition in LangGraph refers to the process of specifying which graph objects are exposed by a deployed LangGraph API server. Each graph is identified by a unique name in the configuration and mapped to a Python (or JavaScript/TypeScript) import path that resolves to a compiled graph object. During the Docker build process, these import paths must be translated from host-relative file paths to container-internal paths so that the API server can locate and load each graph at runtime.
Description
Import Path Format
Graph modules are specified in the `graphs` dictionary of the configuration file using the format:
"<graph_id>": "<module_path>:<attribute_name>"
For example:
{
"graphs": {
"my_agent": "./src/agent.py:graph",
"chatbot": "my_package.chatbot:compiled_graph"
}
}
The module path can be either:
- A relative file path (starting with `./`) pointing to a Python file on the host filesystem.
- A Python dotted module path (e.g., `my_package.chatbot`) for packages installed via pip.
When a relative file path is used, the build system must determine which local dependency contains the file and translate the path to the corresponding container-internal location under `/deps/`.
Graph Value Types
Each graph entry can be:
- A string in `"path:attribute"` format (simple case).
- A dictionary with a `"path"` key containing the import string, allowing additional metadata.
The referenced attribute must be one of:
- A compiled `StateGraph` or any Pregel object.
- An `@entrypoint`-decorated function.
- An (async) context manager accepting a `RunnableConfig` and returning a Pregel object.
Local Dependency Management
When graph modules reference local files, the build system must:
- Identify which local dependency directory contains the referenced file.
- Determine whether that directory is a "real package" (has `pyproject.toml` or `setup.py`) or a "faux package" (bare directory with Python files).
- Map the host-side file path to the container-internal path where the dependency will be installed.
- Update the graph import path in the configuration to use the container path.
This mapping is managed by the `_assemble_local_deps` function (which catalogues local dependencies) and the `_update_graph_paths` function (which performs the path rewriting).
Module Resolution Rules
The path resolution follows these rules in order:
- Check if the file is inside a "real package" directory and map to `/deps/<package_name>/...`.
- Check if the file is inside a "faux package" directory and map to the corresponding `/deps/outer-<name>/...` path.
- If neither match is found, raise an error instructing the user to add the containing package to the `dependencies` list.
Usage
Registering a Graph from a Local Package
Given a project structure:
my_project/
langgraph.json
my_agent/
pyproject.toml
agent.py # contains: graph = StateGraph(...)
The configuration would be:
{
"dependencies": ["./my_agent"],
"graphs": {
"agent": "./my_agent/agent.py:graph"
}
}
During the Docker build, `./my_agent/agent.py:graph` is rewritten to `/deps/my_agent/agent.py:graph`.
Registering a Graph from a Bare Directory
For a directory without packaging metadata:
{
"dependencies": ["."],
"graphs": {
"chatbot": "./src/chatbot.py:app"
}
}
The build system generates a minimal `pyproject.toml` for the faux package and rewrites the graph path accordingly.
Theoretical Basis
Module Resolution
Module resolution is the process of translating a symbolic reference (an import path) to a concrete file location. In LangGraph's deployment pipeline, this resolution must bridge two distinct filesystem layouts: the developer's host machine and the Docker container. The configuration system acts as a binding layer, recording the developer's intent and then mechanically transforming paths during the build.
Dependency Inversion
By declaring graph modules in configuration rather than hard-coding import logic in the server, LangGraph applies a form of dependency inversion. The API server is decoupled from the specifics of where graph code lives; it simply reads the `LANGSERVE_GRAPHS` environment variable (set during the Docker build) and loads the specified modules.
Local Dependency Classification
The distinction between "real packages" and "faux packages" reflects Python's packaging ecosystem. Real packages follow standard packaging conventions and can be installed with `pip install -e .` directly. Faux packages require the build system to synthesize minimal packaging metadata so they can also be installed via pip, ensuring a uniform installation flow inside the container.