主题
Agent Server
LangSmith Deployment 的 Agent Server 提供了一个用于创建和管理基于智能体的应用的 API。它构建在 assistants 这一概念之上——即为特定任务配置的智能体——并内置了持久化和任务队列。这个多用途 API 支持广泛的智能体应用场景，从后台处理到实时交互。
使用 Agent Server 来创建和管理：
TIP
API 参考
有关 API 端点和数据模型的详细信息，请参阅 Agent Server API 参考。
应用结构
要部署 Agent Server 应用，你需要指定想要部署的图，以及任何相关的配置设置，例如依赖项和环境变量。
阅读应用结构指南，了解如何为部署组织你的 LangGraph 应用结构。
NOTE
LangSmith cloud 会为你管理数据库。如果你在自己的基础设施上部署，则需要自行设置。
部署的组成部分
当你部署 Agent Server 时，你部署的是一个或多个图、一个用于持久化的数据库，以及一个任务队列。
图
当你使用 Agent Server 部署图时，你部署的是 Assistant 的“蓝图”。
图最常见的用途是实现一个智能体，但并非必须如此。例如，图可以实现一个仅支持来回对话的简单聊天机器人，而无法影响任何应用的控制流。实际上，随着应用变得越来越复杂，图往往会实现更复杂的流程，可能会使用多个智能体协同工作。
图不必使用 LangGraph 编写。你也可以使用 LangGraph Functional API 或 deployments-wrap-sdk 包，部署用其他框架构建的智能体——例如 Strands、Claude Agent SDK 等或 Google ADK。
图的加载与编译
你的图如何以及何时被编译，取决于你在应用结构中如何注册它：
- 已编译的图（推荐）：导出一个已编译的
CompiledGraph实例。服务器在容器启动时加载它一次，并在每次运行时复用——没有针对每个请求的编译开销。 - 工厂函数：导出一个智能体工厂函数，服务器每次需要图时都会调用它。仅当你需要针对每次运行定制图时（例如，根据 assistant 配置选择不同的模型或工具）才使用它。请保持工厂函数轻量，因为它们会在每次调用时运行。
TIP
除非你特别需要针对每次运行的定制，否则请使用已编译的图。工厂函数会在每次调用时增加开销；已编译的图则不会。
在这两种情况下，服务器都会在运行时自动注入为该部署配置的检查点器和记忆存储。不要在你的图代码中配置它们，因为服务器需要为其他操作管理它们。
持久化
Agent Server 会持久化三种类型的数据，默认全部由 PostgreSQL 提供支持：
- 核心资源数据：assistants、threads、runs 和 cron jobs。始终存储在 PostgreSQL 中。
- 检查点（短期记忆）：在每一步写入的图执行状态快照。它们使运行具备持久性：如果某个 worker 被中断，运行可以从最后一个检查点恢复，而不是从头开始。持久化模式控制检查点的频率——
async（默认）在每一步之后写入；exit只存储最终状态。LangSmith 默认将其存储在 PostgreSQL 中；但你可以切换到 MongoDB 或自定义实现。有关详情，请参阅配置检查点器后端。 - 存储（长期记忆）：跨线程持久存在的记忆，使智能体能够在不同的对话之间保留信息。默认存储在 PostgreSQL 中，但可以替换为自定义实现。有关详情，请参阅添加自定义存储。
任务队列
当客户端创建一个运行时，API 服务器会将其加入队列，并由一个队列 worker 取出来执行。Worker 还可以收到信号以取消正在进行的运行，并发布输出事件，让打开的 /stream 连接将这些事件实时转发给客户端。
Redis 负责 API 服务器与队列 worker 之间的信令、取消和流式传输 pub/sub。它只存储临时数据——Redis 中不会持久保存任何用户或运行数据。运行数据本身始终从 PostgreSQL 读取并写入 PostgreSQL。
有关如何设置和管理这些组件的更多信息，请查阅托管选项指南。
运行时架构
部署模式
Agent Server 支持三种运行时配置：
- 单主机：API 服务器直接管理任务队列，没有独立的队列 worker。这是自托管部署的默认方式，适用于开发和低流量场景。
- 拆分 API 与队列：专用的队列 worker 在与 API 服务器不同的主机上处理运行执行。对于自托管部署，可通过在配置中设置
queue.enabled: true来启用。各层独立伸缩——API 服务器根据请求量伸缩，队列 worker 根据待处理运行的数量伸缩。 - 分布式运行时：API 进程和队列进程同样分开运行，但与由单个队列进程同时处理图的编排和执行不同，分布式运行时使用一个进程进行编排、一个进程进行执行。适用于高并发需求的大规模部署。
下文描述的容器架构和运行生命周期适用于单主机以及拆分 API 与队列的配置。
容器架构
一个典型的部署由两种长期运行的容器组成，二者都基于同一个 Docker 镜像构建（一个基础镜像，其上安装了你的项目代码）：
- API 服务器处理客户端请求（创建运行、读取线程状态、流式输出结果），但它们自身并不执行智能体代码。
- 队列 worker是执行引擎。它们监听持久化任务队列，执行你的图代码并写入检查点。
容器是无状态的，但具有持久性。任何时候都必须至少有 1 个队列 worker 监听任务队列，以确保不会有运行被孤立。这些容器在其生命周期内可以服务许多运行。
API 服务器和队列 worker 是独立的容器池，并且独立伸缩。
flowchart TB
User["User"]
API["API Servers"]
subgraph WorkerContainer["Worker Containers"]
QueueLoop["Queue Loop"]
W1["Worker"]
W2["Worker"]
Wn["..."]
QueueLoop -->|dispatch| W1
QueueLoop -->|dispatch| W2
end
DB[(Postgres)]
Redis[(Redis)]
User -->|request| API
API -->|create run| DB
API -->|notify| Redis
Redis -->|wake| QueueLoop
QueueLoop -->|claim next run| DB
WorkerContainer -->|save checkpoints / update status| DB
WorkerContainer -->|publish events| Redis
Redis -->|stream events| API
API -->|SSE response| User
style User fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
style API fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
style DB fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
style Redis fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643
style WorkerContainer fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
style QueueLoop fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
style W1 fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
style W2 fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
style Wn fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
运行执行生命周期
当你调用一次运行时，请求会流经若干组件：
- 客户端向 API 服务器发送请求，API 服务器在持久化任务队列中创建一个待处理的运行。
- 一个队列 worker 取出该运行，获取它的租约，加载相应的图并开始执行。队列强制规定，对于给定的线程，同一时间最多只能执行 1 个运行。
- 随着图的执行，worker 将检查点写入持久化层（频率取决于持久化模式），并通过配置的 pubsub 服务商广播流式传输事件。
- 如果客户端打开了
/stream连接，API 服务器会订阅 pubsub 通道，并通过服务器发送事件实时将事件转发给客户端。 - 当执行完成时，worker 更新运行状态并释放其槽位以供下一个运行使用。
每个 worker 最多可并发执行 N_JOBS_PER_WORKER 个运行（默认：10），因此单个 worker 容器可以并行服务许多运行。这限制的是并发运行执行的数量，而不是部署可服务的 API 请求数量。API 服务器独立处理请求并单独伸缩，因此请求服务能力不受 N_JOBS_PER_WORKER 的限制。有关调优指导，请参阅为规模配置 Agent Server。