主题
自托管 Agent Server 环境变量
部署在自托管基础设施上时，LangSmith Agent Server 支持的环境变量。
Agent Server 在部署到自托管基础设施上时支持以下环境变量。有关云部署专属的变量，见Cloud Agent Server 环境变量。
BG_JOB_ISOLATED_LOOPS
把 BG_JOB_ISOLATED_LOOPS 设为 True，在一个与提供服务的 API 事件循环分离的隔离事件循环中执行后台运行。
WARNING
启用这个标志并不会消除根本问题。它只是把同步阻塞工作移出提供服务的 API 事件循环，使健康检查不再失败，但阻塞代码会继续在后台循环上运行，并将继续在生产中造成问题，如吞吐下降、尾延迟飙升、worker 挨饿，或连接池耗尽（见下面的 pool-size 警示），以及在负载下糟糕的扩展性。
要妥善解决这些问题，请在你的整个 agent 中使用原生异步驱动和异步代码。这意味着像 httpx 或 aiohttp 这样的异步 HTTP 客户端（虽然我们建议缓存这些客户端以避免加载 SSL 上下文的 CPU 开销）、像 asyncpg 或 psycopg[async] 这样的异步数据库驱动，以及异步模型 SDK。对于无法避免的同步库，把那个特定的调用包裹进 asyncio.to_thread(...) 或 loop.run_in_executor(...)，而不是为整个部署启用这个标志。
如果一个图/节点的实现含同步代码，这个环境变量就应设为 True。在这种情况下，同步代码会阻塞提供服务的 API 事件循环，可能导致 API 不可用。API 不可用的一个症状是因健康检查失败而不断重启应用。
WARNING
当 BG_JOB_ISOLATED_LOOPS 启用时，每个后台 worker 在它自己的线程中运行，带一个独立的 Postgres 连接池。每 worker 的池大小是 LANGGRAPH_POSTGRES_POOL_MAX_SIZE // N_JOBS_PER_WORKER。例如，LANGGRAPH_POSTGRES_POOL_MAX_SIZE=20 且 N_JOBS_PER_WORKER=15 时，每个 worker 只得到一个 1 个连接的池。小的每-worker 池更容易受连接失败影响，因为单个陈旧连接占据池的很大比例。如果你启用隔离循环，确保 LANGGRAPH_POSTGRES_POOL_MAX_SIZE 足够大，为每个 worker 至少提供几个连接。
默认为 False。
BG_JOB_MAX_RETRIES
一次后台运行在可重试失败（例如暂态数据库错误、服务器关闭取消）之后被重试的最大次数。当一次运行以可重试错误失败时，它被放回队列并从最后打检查点的步骤恢复。如果运行超过最大重试次数，它被标记为失败。
默认为 3。
BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS
以秒指定队列收到关闭信号后，服务器等待后台作业完成多久。这段期限过后，服务器会强制终止。默认为 180 秒。最大值为 3600 秒。设置它以确保作业在关闭期间有足够时间干净地完成。在 langgraph-api==0.2.16 中加入。
BG_JOB_TIMEOUT_SECS
后台运行的超时可以增加。不过，云部署的基础设施对 API 请求强制执行 1 小时的超时上限。这意味着客户端与服务器之间的连接会在 1 小时后超时。这不可配置。
一次后台运行可以执行超过 1 小时，但如果某次运行耗时超过 1 小时，客户端必须重新连接到服务器（例如通过 POST /threads/{thread_id}/runs/{run_id}/stream 加入流）以取回该运行的输出。
默认为 86400。
CORS_ALLOW_ORIGINS
设置 CORS_ALLOW_ORIGINS 以指定允许的源。
- 允许单个源的例子：
CORS_ALLOW_ORIGINS=https://example.com - 允许多个源的例子：
CORS_ALLOW_ORIGINS=https://example.com,https://app.example.com
有关高级 CORS 配置，见如何添加自定义 CORS 配置。
默认为 *（所有源）。
支持的 Datadog 环境变量
在部署上设置这些环境变量或机密，以把 Agent Server 的追踪和日志发送到 Datadog。每个变量只有在 DD_API_KEY 被设置时才生效，它会用 Datadog 的 ddtrace-run 追踪器和日志收集代理包裹应用进程。
DD_API_KEY：你的 Datadog API 密钥。必需。发送任何追踪或日志到 Datadog 都需要它。DD_LOGS_ENABLED：设为true以把 Agent Server 日志转发到 Datadog。省略它或设为false以禁用日志转发。DD_LOGS_INJECTION：设为true以给日志添加追踪和 span 标识符，使日志与追踪关联。DD_TRACE_ENABLED：控制 Datadog 追踪收集。设为true收集追踪，或false禁用它。DD_SITE：发送数据到的 Datadog 站点，例如datadoghq.com或datadoghq.eu。默认为datadoghq.com。DD_ENV：应用于追踪和日志的环境名，例如production。DD_SERVICE：应用于追踪和日志的服务名。DD_TRACE_DEBUG：排障时设为true以在ddtrace追踪器中启用调试日志。DD_LOG_LEVEL：Datadog Agent 日志级别，例如排障时的debug。
完整的追踪选项集，见 DD_* 环境变量参考。
NOTE
启用 DD_API_KEY（因而 ddtrace-run）可能覆盖或干扰你可能已插桩进应用代码的其他自动插桩方案（例如 OpenTelemetry）。
LANGGRAPH_POSTGRES_POOL_MAX_SIZE
从 langgraph-api 版本 0.2.12 起，Postgres 连接池的最大大小（每副本）可以用 LANGGRAPH_POSTGRES_POOL_MAX_SIZE 环境变量控制。通过设置这个变量，你能确定服务器与 Postgres 数据库建立的并发连接数的上限。
例如，如果一个部署扩到 10 个副本且 LANGGRAPH_POSTGRES_POOL_MAX_SIZE 配为 150，那么最多可建立 1500 个到 Postgres 的连接。这对数据库资源受限（或更充裕）、或你出于性能或扩展原因需要调优连接行为的部署尤为有用。
当 BG_JOB_ISOLATED_LOOPS 启用时，池不被共享。取而代之，每个后台 worker 线程创建一个它自己的池，最大大小为 LANGGRAPH_POSTGRES_POOL_MAX_SIZE / N_JOBS_PER_WORKER。在调低池大小时记住这一点。对一个共享池合适的值，在隔离循环下可能导致非常小的每-worker 池。
默认为 150 个连接。
LS_CHECKPOINT_DELETE
延迟检查点删除的 JSON 值配置。启用时，线程删除和清理操作会把检查点排入后台删除队列，而非同步删除，从而把 I/O 移出请求热路径。在 langgraph-api>=0.8.1 中可用。
NOTE
仅与默认的 PostgreSQL 检查点器后端一起受支持。延迟删除将在未来的版本中成为默认。
接受的字段：
enabled（布尔，默认false）：当为true时，线程删除和清理操作把检查点排入checkpoint_delete_queue并立即返回，后台 worker 排空该队列。enabledWorkerOnly（布尔，默认false）：只运行后台排空 worker 而不排入新条目。用它把enabled回滚为false后完成排空队列。pollIntervalMs（整数，默认5000）：worker 轮询队列的频率（毫秒）。batchSize（整数，默认25）：worker 每个事务从队列取出的检查点条目数。较小的值以更长排空延迟为代价，把 I/O 分摊到更多时间。batchSleepMs（整数，默认500）：队列非空时 worker 在批次之间休眠多久（毫秒）。
示例：LS_CHECKPOINT_DELETE='{"enabled":true,"batchSize":10,"pollIntervalMs":1000}'。
默认为禁用（同步检查点删除）。
LS_DEFAULT_CHECKPOINTER_BACKEND
为那些在 langgraph.json 中未指定检查点器的 agent 服务器设置默认检查点器后端。接受的值："default"（PostgreSQL）、"mongo"、"custom"。
如果应用的 langgraph.json 含一个 checkpointer.backend 值，它优先于这个变量。
当设为 "mongo" 时，你还必须通过 LS_MONGODB_URI 提供 MongoDB 连接 URI。
LANGSMITH_TRACING
把 LANGSMITH_TRACING 设为 false 以禁用向 LangSmith 的追踪。
NOTE
要基于运行时条件（例如按客户要求或数据敏感度）做选择性追踪控制，见条件追踪。
默认为 true。
LOG_COLOR
这主要与通过 langgraph dev 命令使用 dev 服务器的场景相关。把 LOG_COLOR 设为 true，在使用默认控制台渲染器时启用 ANSI 彩色控制台输出。通过把这个变量设为 false 禁用颜色输出会产生单色日志。默认为 true。
LOG_LEVEL
配置日志级别。默认为 INFO。
LOG_JSON
把 LOG_JSON 设为 true，用已配置的 JSONRenderer 把所有日志消息渲染为 JSON 对象。这会产出能被日志管理系统轻松解析或摄取的 structured 日志。默认为 false。
N_JOBS_PER_WORKER
单个队列 worker 从 Agent Server 任务队列并发执行的最大运行数。默认为 10。
这限制并发运行执行，而非你的部署能服务的 API 请求数。服务请求的容量由 API 服务器处理，并独立于这个值扩展。有关调优指导，见为规模配置 Agent Server。
LS_APM_OTEL_ENABLED
要为你的部署配置 OpenTelemetry APM 追踪，把 LS_APM_OTEL_ENABLED 设为 true，并把 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 或 OTEL_EXPORTER_OTLP_ENDPOINT 设为目标追踪摄取端点。注意 LS_APM_OTEL_ENABLED 和另外两个导出端点之一都是必需的，才能在 0.7.17 之后的服务器版本中激活 OpenTelemetry APM 追踪。
指定其他 OTEL_* 环境变量来配置追踪、日志和其他插桩。
shell
# If you set LS_APM_OTEL_ENABLED AND (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT),
# the server starts with OpenTelemetry instrumentation enabled.
LS_APM_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<target trace ingestion endpoint>
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net
OTEL_SERVICE_NAME=MY_LANGSMITH_DEPLOYMENT
OTEL_EXPORTER_OTLP_HEADERS=api-key=<YOUR_INGEST_LICENSE_KEY>
LANGSMITH_OTEL_ENABLED=true
# Common OTEL settings
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=4095
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
OTEL_PYTHON_EXCLUDED_URLS=/metrics,/ok,/info
# Optional: OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true例如，要把 OpenTelemetry 追踪提交到 New Relic 的美国区域，设置以下内容：
shell
LS_APM_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.nr-data.net/v1/traces
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net
OTEL_EXPORTER_OTLP_HEADERS=api-key=<YOUR_INGEST_LICENSE_KEY>NOTE
OTel APM 追踪在 Agent Server 版本 0.5.32 中加入，目前处于 Alpha。
LS_MONGODB_URI
MongoDB 检查点器后端的 MongoDB 连接 URI。
该 URI 必须指向一个副本集成员或 mongos 路由器，且必须在路径中包含数据库名。
详情见配置检查点器后端。
REDIS_KEY_PREFIX
INFO
在 API Server 版本 0.1.9+ 中可用 这个环境变量在 API Server 版本 0.1.9 及以上受支持。
指定一个 Redis 键的前缀。这让多个 Agent Server 实例能通过使用不同的键前缀共享同一个 Redis 实例。
默认为 ''。
REDIS_URI_CUSTOM
INFO
仅用于 Hybrid 和 Self-Hosted 自定义 Redis 实例仅对 Hybrid 和 Self-Hosted 部署可用。
指定 REDIS_URI_CUSTOM 以使用一个自定义 Redis 实例。REDIS_URI_CUSTOM 的值必须是一个有效的 Redis 连接 URI。
REDIS_MAX_CONNECTIONS
Redis 连接池的最大大小（每副本）可以用 REDIS_MAX_CONNECTIONS 环境变量控制。通过设置这个变量，你能确定服务器与 Redis 实例建立的并发连接数的上限。
例如，如果一个部署扩到 10 个副本且 REDIS_MAX_CONNECTIONS 配为 150，那么最多可建立 1500 个到 Redis 的连接。
默认为 2000。
RESUMABLE_STREAM_TTL_SECONDS
Redis 中可恢复流数据的存活时间（秒）。
当创建一次运行并流式输出时，该流可被配置为可恢复（例如 stream_resumable=True）。如果某个流可恢复，该流的输出会临时存储在 Redis 中。这部分数据的 TTL 可以通过设置 RESUMABLE_STREAM_TTL_SECONDS 来配置。
有关如何实现可恢复流的更多详情，见 Python 和 JS/TS SDK。
默认为 120 秒。
NOTE
为 RESUMABLE_STREAM_TTL_SECONDS 设一个很高的值，会在有大量带大或频繁流式输出的并发运行时，导致大量 Redis 内存占用。把这个值设为能在网络中断期间实现恢复的最小值，并优先用检查点做长期持久化和执行快照。
AGENT_POSTGRES_IAM_AUTH_PROVIDER
把 AGENT_POSTGRES_IAM_AUTH_PROVIDER 设为 aws、azure 或 gcp，用一个短生命周期的云身份令牌替换 PostgreSQL 连接 URI 中的密码。需要 langgraph-api>=0.12.0。
提供商前置条件和连接 URI 要求，见为数据存储配置 IAM 身份验证。
AGENT_REDIS_IAM_AUTH_PROVIDER
把 AGENT_REDIS_IAM_AUTH_PROVIDER 设为 aws、azure 或 gcp，用一个短生命周期的云身份令牌对 Redis 连接进行身份验证。需要 langgraph-api>=0.12.0。
提供商前置条件和连接 URI 要求，见为数据存储配置 IAM 身份验证。
LANGGRAPH_SERVER_HOST
设置 LANGGRAPH_SERVER_HOST 以控制 Agent Server 监听哪些地址族：
- 空字符串：同时监听 IPv4 和 IPv6。从
langgraph-api>=0.14.0起这是默认。 0.0.0.0：仅监听 IPv4。::：仅监听 IPv6。
langgraph-api 0.14.0 之前的版本默认为 0.0.0.0，即仅监听 IPv4。
LANGSMITH_API_KEY
要把追踪发送到自托管 LangSmith 实例，把 LANGSMITH_API_KEY 设为一个从该自托管实例创建的 API 密钥。
LANGSMITH_ENDPOINT
要把追踪发送到自托管 LangSmith 实例，把 LANGSMITH_ENDPOINT 设为该自托管实例的主机名。
MOUNT_PREFIX
设置 MOUNT_PREFIX 以在一个特定的路径前缀下提供服务 Agent Server。这对服务器位于需要一个特定路径前缀的反向代理或负载均衡器之后的部署很有用。
例如，如果服务器要在 https://example.com/langgraph 下提供服务，把 MOUNT_PREFIX 设为 /langgraph。
POSTGRES_URI_CUSTOM
指定 POSTGRES_URI_CUSTOM 以使用一个自定义 Postgres 实例。POSTGRES_URI_CUSTOM 的值必须是一个有效的 Postgres 连接 URI。
Postgres：
- 版本 15.8 或更高。
- 必须存在一个初始数据库，且连接 URI 必须引用该数据库。
控制平面功能：
- 如果指定了
POSTGRES_URI_CUSTOM，控制平面不会为服务器预配一个数据库。 - 如果移除了
POSTGRES_URI_CUSTOM，控制平面不会为服务器预配数据库，也不会删除外部管理的 Postgres 实例。 - 如果移除了
POSTGRES_URI_CUSTOM，该修订版的部署将不会成功。一旦指定了POSTGRES_URI_CUSTOM，在部署的整个生命周期内它必须始终被设置。 - 如果部署被删除，控制平面不会删除外部管理的 Postgres 实例。
POSTGRES_URI_CUSTOM的值可以更新。例如，可以更新 URI 中的密码。
数据库连接：
- 自定义 Postgres 实例必须能被 Agent Server 访问。用户负责确保连通性。
REDIS_CLUSTER
WARNING
此功能处于 Alpha。
把 REDIS_CLUSTER 设为 True 以启用 Redis Cluster 模式。启用时，系统会用集群模式连接 Redis。这对连接一个 Redis Cluster 部署很有用。
默认为 False。
REDIS_URI_CUSTOM
指定 REDIS_URI_CUSTOM 以使用一个自定义 Redis 实例。REDIS_URI_CUSTOM 的值必须是一个有效的 Redis 连接 URI。