Agent Server 在自托管基础设施上部署时支持以下环境变量。有关 Cloud 部署特有的变量，请参阅 Cloud Agent Server 环境变量。

​
BG_JOB_ISOLATED_LOOPS

Set BG_JOB_ISOLATED_LOOPS to True to execute background runs in an isolated event loop separate from the serving API event loop.
Enabling this flag does not remove the underlying problem. It moves synchronous blocking work off the serving API’s event loop so health checks stop failing, but the blocking code continues to run on the background loop and will continue to cause issues in production, like degraded throughput, tail-latency spikes, starved workers, or connection pool exhaustion (see the pool-size caveat below), and poor scaling under load.To properly resolve those issues, use native async drivers and async code throughout your agent. That means async HTTP clients like httpx or aiohttp (though we recommend caching the clients to avoid CPU overhead loading the SSL context), async database drivers like asyncpg or psycopg[async], and async model SDK’s. For unavoidable synchronous libraries, wrap the specific call in asyncio.to_thread(...) or loop.run_in_executor(...) instead of enabling this flag for the whole deployment.
This environment variable should be set to True if the implementation of a graph/node contains synchronous code. In this situation, the synchronous code will block the serving API event loop, which may cause the API to be unavailable. A symptom of an unavailable API is continuous application restarts due to failing health checks.
When BG_JOB_ISOLATED_LOOPS is enabled, each background worker runs in its own thread with a separate Postgres connection pool. The per-worker pool size is LANGGRAPH_POSTGRES_POOL_MAX_SIZE // N_JOBS_PER_WORKER. For example, with LANGGRAPH_POSTGRES_POOL_MAX_SIZE=20 and N_JOBS_PER_WORKER=15, each worker gets a pool of only 1 connection. Small per-worker pools are more susceptible to connection failures because a single stale connection represents a large fraction of the pool. If you enable isolated loops, ensure LANGGRAPH_POSTGRES_POOL_MAX_SIZE is large enough to provide at least a few connections per worker.
Defaults to False.

​
BG_JOB_MAX_RETRIES

Maximum number of times a background run will be retried after a retriable failure (e.g. transient database errors, server shutdown cancellations). When a run fails with a retriable error, it is placed back in the queue and resumed from the last checkpointed step. If the run exceeds the maximum number of retries, it is marked as failed. Defaults to 3.

​
BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS

Specifies, in seconds, how long the server will wait for background jobs to finish after the queue receives a shutdown signal. After this period, the server will force termination. Defaults to 180 seconds. The maximum value is 3600 seconds. Set this to ensure jobs have enough time to complete cleanly during shutdown. Added in langgraph-api==0.2.16.

​
BG_JOB_TIMEOUT_SECS

The timeout of a background run can be increased. However, the infrastructure for a Cloud deployment enforces a 1 hour timeout limit for API requests. This means the connection between client and server will timeout after 1 hour. This is not configurable. A background run can execute for longer than 1 hour, but a client must reconnect to the server (e.g. join stream via POST /threads/{thread_id}/runs/{run_id}/stream) to retrieve output from the run if the run is taking longer than 1 hour. Defaults to 86400.

​
CORS_ALLOW_ORIGINS

Set CORS_ALLOW_ORIGINS to specify allowed origins.
  • Example for allowing a single origin: CORS_ALLOW_ORIGINS=https://example.com
  • Example for allowing multiple origins: CORS_ALLOW_ORIGINS=https://example.com,https://app.example.com
For advanced CORS configuration, see how to add custom CORS configuration. Defaults to * (all origins).

​
Supported Datadog environment variables

Set these environment variables or secrets on the deployment to send Agent Server traces and logs to Datadog. Every variable takes effect only when DD_API_KEY is set, which wraps the application process in Datadog’s ddtrace-run tracer and log-collection agent.
  • DD_API_KEY: Your Datadog API key. Required. Sending any traces or logs to Datadog requires it.
  • DD_LOGS_ENABLED: Set to true to forward Agent Server logs to Datadog. Omit it or set it to false to disable log forwarding.
  • DD_LOGS_INJECTION: Set to true to add trace and span identifiers to logs so that logs correlate with traces.
  • DD_TRACE_ENABLED: Controls Datadog trace collection. Set to true to collect traces or false to disable it.
  • DD_SITE: The Datadog site to send data to, such as datadoghq.com or datadoghq.eu. Defaults to datadoghq.com.
  • DD_ENV: The environment name applied to traces and logs, such as production.
  • DD_SERVICE: The service name applied to traces and logs.
  • DD_TRACE_DEBUG: Set to true to enable debug logging in the ddtrace tracer when troubleshooting.
  • DD_LOG_LEVEL: The Datadog Agent log level, such as debug, when troubleshooting.
For the full set of tracing options, see the DD_* environment variables reference.
Enabling DD_API_KEY (and thus ddtrace-run) can override or interfere with other auto-instrumentation solutions (such as OpenTelemetry) that you may have instrumented into your application code.

​
LANGGRAPH_POSTGRES_POOL_MAX_SIZE

Beginning with langgraph-api version 0.2.12, the maximum size of the Postgres connection pool (per replica) can be controlled using the LANGGRAPH_POSTGRES_POOL_MAX_SIZE environment variable. By setting this variable, you can determine the upper bound on the number of simultaneous connections the server will establish with the Postgres database. For example, if a deployment is scaled up to 10 replicas and LANGGRAPH_POSTGRES_POOL_MAX_SIZE is configured to 150, then up to 1500 connections to Postgres can be established. This is particularly useful for deployments where database resources are limited (or more available) or where you need to tune connection behavior for performance or scaling reasons. When BG_JOB_ISOLATED_LOOPS is enabled, the pool is not shared. Instead, each background worker thread creates its own pool with a maximum size of LANGGRAPH_POSTGRES_POOL_MAX_SIZE / N_JOBS_PER_WORKER. Keep this in mind when lowering the pool size. A value that works well for a shared pool may result in very small per-worker pools under isolated loops. Defaults to 150 connections.

​
LS_CHECKPOINT_DELETE

JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. Available in langgraph-api>=0.8.1.
Only supported with the default PostgreSQL checkpointer backend. Deferred deletes will become the default in a future release.
Accepted fields:
  • enabled (boolean, default false): When true, thread delete and prune operations enqueue checkpoints into checkpoint_delete_queue and return immediately, and the background worker drains the queue.
  • enabledWorkerOnly (boolean, default false): Runs only the background drain worker without enqueuing new entries. Use this to finish draining the queue after rolling enabled back to false.
  • pollIntervalMs (integer, default 5000): How often the worker polls the queue, in milliseconds.
  • batchSize (integer, default 25): Number of checkpoint entries the worker dequeues per transaction. Smaller values spread I/O over more time at the cost of longer drain latency.
  • batchSleepMs (integer, default 500): How long the worker sleeps between batches when the queue is non-empty, in milliseconds.
Example: LS_CHECKPOINT_DELETE='{"enabled":true,"batchSize":10,"pollIntervalMs":1000}'. Defaults to disabled (synchronous checkpoint deletion).

​
LS_DEFAULT_CHECKPOINTER_BACKEND

Sets the default checkpointer backend for agent servers that don’t specify one in langgraph.json. Accepted values: "default" (PostgreSQL), "mongo", "custom". If the application’s langgraph.json includes a checkpointer.backend value, it takes precedence over this variable. When set to "mongo", you must also provide the MongoDB connection URI via LS_MONGODB_URI.

​
LANGSMITH_TRACING

Set LANGSMITH_TRACING to false to disable tracing to LangSmith.
For selective tracing control based on runtime conditions (such as per-client requirements or data sensitivity), see Conditional tracing.
Defaults to true.

​
LOG_COLOR

This is mainly relevant in the context of using the dev server via the langgraph dev command. Set LOG_COLOR to true to enable ANSI-colored console output when using the default console renderer. Disabling color output by setting this variable to false produces monochrome logs. Defaults to true.

​
LOG_LEVEL

Configure log level. Defaults to INFO.

​
LOG_JSON

Set LOG_JSON to true to render all log messages as JSON objects using the configured JSONRenderer. This produces structured logs that can be easily parsed or ingested by log management systems. Defaults to false.

​
N_JOBS_PER_WORKER

Maximum number of runs a single queue worker executes concurrently from the Agent Server task queue. Defaults to 10. This limits concurrent run execution, not the number of API requests your deployment can serve. Request-serving capacity is handled by API servers and scales independently of this value. For tuning guidance, see Configure Agent Server for scale.

​
LS_APM_OTEL_ENABLED

To configure OpenTelemetry APM tracing for your deployment, set LS_APM_OTEL_ENABLED to true and OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT to the target trace ingestion endpoint. Note that both LS_APM_OTEL_ENABLED and one of the other two export endpoints are required to activate OpenTelemetry APM tracing in server versions later than 0.7.17. Specify other OTEL_* environment variables to configure tracing, logging, and other instrumentation.
For example, to submit OpenTelemetry traces to New Relic’s US region, set the following:
OTel APM tracing was added in Agent Server version 0.5.32 and is currently in Alpha.

​
LS_MONGODB_URI

MongoDB connection URI for the MongoDB checkpointer backend. The URI must point to a replica set member or mongos router and must include the database name in the path. See Configure checkpointer backend for details.

​
REDIS_KEY_PREFIX

Available in API Server version 0.1.9+ This environment variable is supported in API Server version 0.1.9 and above.
Specify a prefix for Redis keys. This allows multiple Agent Server instances to share the same Redis instance by using different key prefixes. Defaults to ''.

​
REDIS_MAX_CONNECTIONS

The maximum size of the Redis connection pool (per replica) can be controlled using the REDIS_MAX_CONNECTIONS environment variable. By setting this variable, you can determine the upper bound on the number of simultaneous connections the server will establish with the Redis instance. For example, if a deployment is scaled up to 10 replicas and REDIS_MAX_CONNECTIONS is configured to 150, then up to 1500 connections to Redis can be established. Defaults to 2000.

​
RESUMABLE_STREAM_TTL_SECONDS

Time-to-live in seconds for resumable stream data in Redis. When a run is created and the output is streamed, the stream can be configured to be resumable (e.g. stream_resumable=True). If a stream is resumable, output from the stream is temporarily stored in Redis. The TTL for this data can be configured by setting RESUMABLE_STREAM_TTL_SECONDS. See the Python and JS/TS SDKs for more details on how to implement resumable streams. Defaults to 120 seconds.
Setting a very high value for RESUMABLE_STREAM_TTL_SECONDS can result in substantial Redis memory usage when there are many concurrent runs with large or frequent streaming output. Set this value to the minimum value to enable recovery during network interruptions and prefer checkpointing for long term durability and execution snapshotting.

​
LANGSMITH_API_KEY

要将追踪数据发送至自托管的 LangSmith 实例，请将 LANGSMITH_API_KEY 设置为从该自托管实例创建的 API 密钥。

​
LANGSMITH_ENDPOINT

要将追踪数据发送至自托管的 LangSmith 实例，请将 LANGSMITH_ENDPOINT 设置为该自托管实例的主机名。

​
MOUNT_PREFIX

将 MOUNT_PREFIX 设置为在特定路径前缀下提供 Agent 服务。这在需要将服务器部署在要求特定路径前缀的反向代理或负载均衡器之后时非常有用。 例如，若要在 https://example.com/langgraph 路径下提供服务，请将 MOUNT_PREFIX 设置为 /langgraph。

​
POSTGRES_URI_CUSTOM

指定 POSTGRES_URI_CUSTOM 以使用自定义 Postgres 实例。其值必须是一个有效的 Postgres 连接 URI。 Postgres:
  • 版本 15.8 或更高。
  • 必须存在初始数据库，且连接 URI 必须指向该数据库。
控制平面功能:
  • 如果指定了 POSTGRES_URI_CUSTOM，控制平面将不会为服务器配置数据库。
  • 如果移除了 POSTGRES_URI_CUSTOM，控制平面将不会为服务器配置数据库，也不会删除外部管理的 Postgres 实例。
  • 如果移除了 POSTGRES_URI_CUSTOM，修订版的部署将不会成功。一旦指定了 POSTGRES_URI_CUSTOM，则在其部署的整个生命周期内都必须设置该值。
  • 如果部署被删除，控制平面将不会删除外部管理的 Postgres 实例。
  • 可以更新 POSTGRES_URI_CUSTOM 的值。例如，可以更新 URI 中的密码。
数据库连接性:
  • Agent 服务器必须能够访问自定义的 Postgres 实例。用户有责任确保连接畅通。

​
REDIS_CLUSTER

此功能处于 Alpha 状态。
将 REDIS_CLUSTER 设置为 True 以启用 Redis 集群模式。启用后，系统将使用集群模式连接 Redis。这在连接 Redis 集群部署时很有用。 默认值为 False。

​
REDIS_URI_CUSTOM

指定 REDIS_URI_CUSTOM 以使用自定义 Redis 实例。其值必须是一个有效的 Redis 连接 URI。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.