Cloud Agent Server 环境变量

部署在云上时，LangSmith Agent Server 支持的环境变量。

Agent Server 在部署到云上时支持以下环境变量。有关自托管部署专属的变量，见自托管 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_* 环境变量来配置追踪、日志和其他插桩。

# 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 的美国区域，设置以下内容：

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 内存占用。把这个值设为能在网络中断期间实现恢复的最小值，并优先用检查点做长期持久化和执行快照。

---