Principle:Langchain ai Langgraph Project Configuration

Property	Value
Concept	Project Configuration for LangGraph Application Deployment
Category	Configuration Management
Scope	CLI Deployment Workflow
Related Workflow	CLI_Deployment

Overview

Project Configuration in LangGraph defines a structured, declarative approach for specifying every aspect of a LangGraph application deployment. Rather than relying on imperative scripts or ad-hoc setup procedures, LangGraph uses a single JSON configuration file (typically `langgraph.json`) that captures the application's dependency graph, registered graph modules, environment variables, Python/Node.js runtime versions, Docker image settings, authentication, store configuration, and more. This configuration-as-code approach ensures that deployments are reproducible, portable, and auditable.

Description

A LangGraph project configuration file is a JSON document conforming to the `Config` TypedDict schema. It serves as the central manifest for the deployment tooling, consumed by the CLI commands (`langgraph build`, `langgraph up`, `langgraph dev`) to generate Dockerfiles, Docker Compose stacks, and local development servers.

The configuration encompasses the following principal areas:

Dependency Declaration

The `dependencies` field lists all Python packages required by the application. Dependencies can be:

PyPI packages specified by name (e.g., `"langchain_openai"`)
Local packages specified by relative path (e.g., `"."` or `"./my_package"`)
Git-hosted packages via pip-compatible URLs

Local dependencies are further classified into "real packages" (containing a `pyproject.toml` or `setup.py`) and "faux packages" (plain directories with Python files) during the Docker build process.

Graph Registration

The `graphs` dictionary maps graph identifiers to import paths in the format `"path/to/file.py:object_name"`. Each registered graph must be a compiled `StateGraph`, an `@entrypoint`, or any Pregel object, or an (async) context manager returning one. This registry determines which graphs the deployed API server exposes.

Runtime Configuration

`python_version`: Minimum `3.11`, in `major.minor` format.
`node_version`: Major version only (e.g., `"20"`), required for JavaScript/TypeScript graphs.
`image_distro`: The base Linux distribution (`"debian"`, `"wolfi"`, or `"bookworm"`).
`base_image`: Override the default Docker base image.
`pip_installer`: Choose between `"auto"`, `"pip"`, or `"uv"`.

Environment and Security

`env`: A dictionary of environment variables or a path to a `.env` file.
`auth`: Authentication configuration with a path to an `Auth()` class.
`encryption`: At-rest encryption configuration.
`http`: HTTP server settings including CORS, route disabling, and custom middleware.

Optional Advanced Settings

`store`: Long-term memory store with optional semantic search indexing.
`checkpointer`: Checkpointing configuration with optional TTL.
`webhooks`: Outbound event delivery configuration.
`dockerfile_lines`: Additional Docker instructions injected into the generated Dockerfile.

Usage

The typical workflow for project configuration involves:

Create a `langgraph.json` file in the project root.
Declare dependencies, graph modules, and environment variables.
Run `langgraph build`, `langgraph up`, or `langgraph dev` to deploy.

The CLI tooling loads this file, validates it against the `Config` schema, and uses the validated configuration to drive all downstream operations (Dockerfile generation, Docker Compose orchestration, or local server startup).

Example Configuration

{
    "python_version": "3.11",
    "dependencies": [
        "langchain_openai",
        "."
    ],
    "graphs": {
        "my_agent": "./my_package/agent.py:graph"
    },
    "env": ".env",
    "store": {
        "index": {
            "dims": 1536,
            "embed": "openai:text-embedding-3-small"
        }
    }
}

Theoretical Basis

Configuration-as-Code

The configuration-as-code paradigm treats application configuration as a first-class artifact under version control, enabling:

Reproducibility: The same configuration produces identical deployments.
Auditability: Changes to configuration are tracked in source control.
Automation: CI/CD pipelines consume the configuration directly.

Schema Validation

The `Config` TypedDict defines a strict schema that is validated at CLI invocation time. This early validation catches misconfigurations (unsupported Python versions, missing dependencies, invalid graph paths) before any Docker build or server startup occurs, following the "fail fast" principle.

Separation of Concerns

By centralizing deployment metadata in a configuration file, LangGraph cleanly separates the application logic (graph definitions, tools, prompts) from the deployment infrastructure (Docker image settings, runtime versions, environment variables). This separation enables the same graph code to be deployed across different environments (local development, staging, production) with only configuration changes.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment