Python

基本配置

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "chat.graph:graph"
      }
    }
    

使用 Wolfi 基础镜像

您可以使用 image_distro 字段指定基础镜像的 Linux 发行版。有效选项为 debian, wolfi, bookworm, or bullseye。Wolfi 是推荐选项，因为它提供更小、更安全的镜像。这在 langgraph-cli>=0.2.11.

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "chat.graph:graph"
      },
      "image_distro": "wolfi"
    }
    

向存储添加语义搜索

所有部署都附带一个基于数据库的 BaseStore。在您的 langgraph.json 中添加"索引"配置将启用 语义搜索 在部署的 BaseStore 中。

该 index.fields 配置决定了要嵌入文档的哪些部分：

• * 如果省略或设置为 ["$"]，则整个文档将被嵌入
• * 要嵌入特定字段，请使用 JSON 路径表示法： ["metadata.title", "content.text"]
• * 缺少指定字段的文档仍会被存储，但这些字段不会有嵌入向量
• * 您仍然可以在特定项目上覆盖要嵌入的字段 put 时间使用 index 参数

    {
      "dependencies": ["."],
      "graphs": {
        "memory_agent": "./agent/graph.py:graph"
      },
      "store": {
        "index": {
          "embed": "openai:text-embedding-3-small",
          "dims": 1536,
          "fields": ["$"]
        }
      }
    }
    

使用自定义嵌入函数进行语义搜索

如果您想使用自定义嵌入函数进行语义搜索，可以传递一个自定义嵌入函数的路径：

    {
      "dependencies": ["."],
      "graphs": {
        "memory_agent": "./agent/graph.py:graph"
      },
      "store": {
        "index": {
          "embed": "./embeddings.py:embed_texts",
          "dims": 768,
          "fields": ["text", "summary"]
        }
      }
    }
    

存储配置中的 embed 字段可以引用一个自定义函数，该函数接受字符串列表并返回嵌入向量列表。示例实现：

    # embeddings.py
    def embed_texts(texts: list[str]) -> list[list[float]]:
        """Custom embedding function for semantic search."""
        # Implementation using your preferred embedding model
        return [[0.1, 0.2, ...] for _ in texts]  # dims-dimensional vectors
    

添加自定义身份验证

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "chat.graph:graph"
      },
      "auth": {
        "path": "./auth.py:auth",
        "openapi": {
          "securitySchemes": {
            "apiKeyAuth": {
              "type": "apiKey",
              "in": "header",
              "name": "X-API-Key"
            }
          },
          "security": [{ "apiKeyAuth": [] }]
        },
        "disable_studio_auth": false
      }
    }
    

请参阅 身份验证概念指南 了解更多详情，以及 设置自定义身份验证 指南，了解整个过程的实际操作步骤。

<a id="ttl"></a> #### 配置存储项目生存时间

You can configure default data expiration for items/memories in the BaseStore using the store.ttl 键。这决定了项目在最后一次访问后的保留时间（读取操作可能会根据 refresh_on_read重置计时器）。请注意，这些默认值可以通过修改 get, search等中的相应参数来按调用覆盖。

ttl 配置是一个包含可选字段的对象：

• * refresh_on_read: If true （默认），通过访问项目会 get or search 重置其过期计时器。设置为 false 以仅在写入时刷新 TTL（put).
• * default_ttl：项目的默认生存时间（以 **分钟为单位**）。仅适用于新创建的项目；现有项目不会被修改。如果未设置，项目默认不会过期。
• * sweep_interval_minutes：系统应运行后台进程删除过期项目的频率（以分钟为单位）。如果未设置，清扫不会自动进行。

以下是一个启用 7 天 TTL（10080 分钟）、读取时刷新、每小时清扫的示例：

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "memory_agent": "./agent/graph.py:graph"
      },
      "store": {
        "ttl": {
          "refresh_on_read": true,
          "sweep_interval_minutes": 60,
          "default_ttl": 10080
        }
      }
    }
    

<a id="ttl"></a> #### 配置检查点生存时间

您可以使用 checkpointer 键配置检查点的生存时间（TTL）。这决定了检查点数据在被自动处理前的保留时间。系统支持两个可选的子对象配置：

• * ttl：包括 strategy, sweep_interval_minutes, default_ttl和 sweep_limit （Agent 服务器 v0.8+），它们共同设置检查点的过期方式。
• * serde _（Agent 服务器 v0.5+）_ ：让您控制检查点负载的反序列化行为。

以下是一个设置默认 TTL 为 30 天（43200 分钟）的示例：

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "chat.graph:graph"
      },
      "checkpointer": {
        "ttl": {
          "strategy": "delete",
          "sweep_interval_minutes": 10,
          "default_ttl": 43200
        }
      }
    }
    

在此示例中，超过 30 天的检查点将被删除，并且每 10 分钟执行一次检查。

配置检查点序列化

checkpointer.serde 对象形状反序列化：

• * allowed_json_modules 定义了你希望服务器能够从保存在"json"模式的载荷中反序列化的自定义Python对象的允许列表。这是一个 [path, to, module, file, symbol] 序列。如果省略，则只允许LangChain安全默认值。你可以不安全地设置为 true 来允许任何模块被反序列化。
• * pickle_fallback：是否在JSON解码失败时回退到pickle反序列化。

    {
      "checkpointer": {
        "serde": {
          "allowed_json_modules": [
            ["my_agent", "auth", "SessionState"]
          ]
        }
      }
    }
    

自定义HTTP中间件和请求头

http 块允许你微调请求处理：

• * middleware_order：选择 "auth_first" 在中间件之前运行认证，或 "middleware_first" （默认）来反转该顺序。
• * enable_custom_route_auth：将对认证的扩展应用到你通过 http.app.
• * configurable_headers / logging_headers挂载的路由：每个都接受一个带有可选的 includes 和 excludes 数组的对象；支持通配符，排除规则优先于包含规则。
• * cors：自定义服务器的CORS（跨域资源共享）配置。示例 langgraph.json 配置文件用于配置CORS：

        {
          ...
          "http": {
            "cors": {
              "allow_origins": ["https://example.com", "https://app.example.com"],
              "allow_methods": ["GET", "POST"],
              "allow_headers": ["Authorization", "Content-Type"],
              "allow_credentials": true,
              "allow_origin_regex": "^https://.*\\.example\\.com$",
              "expose_headers": ["x-pagination-total", "x-pagination-next", "x-request-id"],
              "max_age": 600
            }
          },
          ...
        }
        

配置Webhook

可以为出站webhook请求配置自定义请求头和URL限制：

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "chat.graph:graph"
      },
      "webhooks": {
        "headers": {
          "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}"
        },
        "url": {
          "allowed_domains": ["*.mycompany.com"],
          "require_https": true
        }
      }
    }
    

参见 使用Webhook 了解请求头配置、环境变量模板和URL限制的详细信息。

<a id="api-version"></a> #### 固定API版本

_（在v0.3.7中添加）_

可以通过使用 api_version 键来固定Agent Server的API版本。如果你想确保服务器使用特定版本的API，这很有用。 默认情况下，云部署中的构建使用服务器的最新稳定版本。可以通过将 api_version 键设置为特定版本来固定。

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "chat.graph:graph"
      },
      "api_version": "0.2"
    }
    

禁用内置路由

可以使用 http 配置块中的布尔标志来选择性地禁用内置HTTP路由组。这对于你想要最小化服务器暴露面的生产部署很有用。

例如，要禁用系统信息和文档路由：

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "chat.graph:graph"
      },
      "http": {
        "disable_meta": true
      }
    }
    

设置 disable_meta to true 会禁用以下路由：

• - / — 根健康检查
• - /info — 服务器版本和配置信息
• - /metrics — Prometheus和JSON指标
• - /docs — API文档UI
• - /openapi.json — OpenAPI规范

/ok 健康检查端点即使在 disable_meta 被设置时仍然可用，这样Kubernetes等编排工具仍然可以执行存活探针和就绪探针。

其他路由禁用标志包括 disable_assistants, disable_runs, disable_threads, disable_store、和 disable_ui。对于MCP、A2A和webhook，请参阅各自的指南： 禁用 MCP, 禁用 A2A, 禁用 Webhook.

JS

基本配置

    {
      "$schema": "https://langgra.ph/schema.json",
      "graphs": {
        "chat": "./src/graph.ts:graph"
      }
    }
    

<a id="api-version"></a> #### 固定 API 版本

_（于 v0.3.7 添加）_

您可以通过使用 api_version 密钥来固定 Agent Server 的 API 版本。如果您想确保服务器使用特定版本的 API，这会很有用。 默认情况下，Cloud 部署中的构建使用服务器的最新版稳定版本。可以通过将 api_version 密钥设置为特定版本来固定版本。

    {
      "$schema": "https://langgra.ph/schema.json",
      "dependencies": ["."],
      "graphs": {
        "chat": "./src/chat/graph.ts:graph"
      },
      "api_version": "0.2"
    }
    

禁用内置路由

您可以使用 http 配置块中的布尔标志来选择性地禁用内置 HTTP 路由组。这对于生产部署很有用，因为您希望最小化服务器的暴露面。

例如，要禁用系统信息和文档路由：

    {
      "$schema": "https://langgra.ph/schema.json",
      "graphs": {
        "chat": "./src/chat/graph.ts:graph"
      },
      "http": {
        "disable_meta": true
      }
    }
    

设置 disable_meta to true 将禁用以下路由：

• - / — 根健康检查
• - /info — 服务器版本和配置信息
• - /metrics — Prometheus 和 JSON 指标
• - /docs — API 文档 UI
• - /openapi.json — OpenAPI 规范

当 /ok 设置为 true 时，健康检查端点仍然可用 disable_meta ，以便 Kubernetes 等编排工具可以继续执行存活和就绪探针。

其他路由禁用标志包括 disable_assistants, disable_runs, disable_threads, disable_store、 disable_ui。有关 MCP、A2A 和 Webhook 的更多信息，请参阅各自的指南： 禁用 MCP, 禁用 A2A, 禁用 Webhook.

Python

LangGraph CLI 的基础命令是 langgraph.

    langgraph [OPTIONS] COMMAND [ARGS]
    

JS

LangGraph.js CLI 的基础命令是 langgraphjs.

    npx @langchain/langgraph-cli [OPTIONS] COMMAND [ARGS]
    

我们建议使用 npx 以始终使用最新版本的 CLI。

Python

在开发模式下运行 LangGraph API 服务器，支持热重载和调试功能。这个轻量级服务器无需安装 Docker，适用于开发和测试。状态会持久化到本地目录。

安装

此命令需要安装 "inmem" 附加组件：

    pip install -U "langgraph-cli[inmem]"
    

用法

    langgraph dev [OPTIONS]
    

选项

    npx @langchain/langgraph-cli dev [OPTIONS]
    

    langgraph build [OPTIONS]
    

    npx @langchain/langgraph-cli build [OPTIONS]
    

    langgraph deploy [OPTIONS] [DOCKER_BUILD_ARGS]
    

    # Deploy with API key from .env file
    langgraph deploy

    # Deploy with inline API key
    LANGSMITH_API_KEY=lsv2_... langgraph deploy

    # Update an existing deployment
    langgraph deploy --deployment-id abc123

    # Deploy with inline deployment name
    LANGSMITH_DEPLOYMENT_NAME=my-agent langgraph deploy

    # Deploy to EU region
    LANGGRAPH_HOST_URL=https://eu.api.host.langchain.com langgraph deploy
    

    langgraph deploy list [OPTIONS]
    

    langgraph deploy revisions [OPTIONS] COMMAND [ARGS]...
    

    langgraph deploy revisions list [OPTIONS] DEPLOYMENT_ID
    

    langgraph deploy delete [OPTIONS] DEPLOYMENT_ID
    

    langgraph deploy logs [OPTIONS]
    

    langgraph up [OPTIONS]
    

    npx @langchain/langgraph-cli up [OPTIONS]
    

    langgraph dockerfile [OPTIONS] SAVE_PATH
    

    langgraph dockerfile -c langgraph.json Dockerfile
    

    FROM langchain/langgraph-api:3.11

    ADD ./pipconf.txt /pipconfig.txt

    RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_anthropic langchain_openai wikipedia scikit-learn

    ADD ./graphs /deps/__outer_graphs/src
    RUN set -ex && \
        for line in '[project]' \
                    'name = "graphs"' \
                    'version = "0.1"' \
                    '[tool.setuptools.package-data]' \
                    '"*" = ["**/*"]'; do \
            echo "$line" >> /deps/__outer_graphs/pyproject.toml; \
        done

    RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*

    ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph", "storm": "/deps/__outer_graphs/src/storm.py:graph"}'
    

    npx @langchain/langgraph-cli dockerfile [OPTIONS] SAVE_PATH
    

    npx @langchain/langgraph-cli dockerfile -c langgraph.json Dockerfile
    

    FROM langchain/langgraphjs-api:20

    ADD . /deps/agent

    RUN cd /deps/agent && yarn install

    ENV LANGSERVE_GRAPHS='{"agent":"./src/react_agent/graph.ts:graph"}'

    WORKDIR /deps/agent

    RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts