Agent Server

LangSmith Deployment 的 Agent Server 提供了用于创建和管理基于智能体应用的 API。它基于 助手这一概念构建，助手是针对特定任务配置的智能体，并内置了持久化功能和任务队列。这个灵活的 API 支持广泛的智能体应用场景，从后台处理到实时交互。 使用 Agent Server 创建和管理：

​

应用结构

要部署 Agent Server 应用，你需要指定要部署的一个或多个图，以及相关配置设置，例如依赖项和环境变量。 阅读应用结构指南，了解如何构建 LangGraph 应用以进行部署。

​

部署的组成部分

部署 Agent Server 时，你需要部署一个或多个图、用于持久化的数据库，以及一个任务队列。

​

图

使用 Agent Server 部署图时，你部署的是 Assistant 的“蓝图”。 图通常实现一个智能体，但并非必须如此。例如，图可以实现一个只支持来回对话的简单聊天机器人，而不具备影响任何应用控制流的能力。实际上，随着应用变得越来越复杂，一个图通常会实现更复杂的流程，并可能使用协同工作的多个智能体。 图不一定要使用 LangGraph 编写。你也可以使用 LangGraph Functional API 或 deployments-wrap-sdk 包，部署使用其他框架构建的智能体，例如 Strands、Claude Agent SDK 等或 Google ADK。

​

图的加载与编译

图的编译方式和编译时机取决于你在应用结构中注册图的方式：

1. 已编译的图（推荐）：导出一个已经编译的 CompiledGraph 实例。服务器会在容器启动时加载一次，并在每次运行中复用它，因此每个请求都无需重新编译。
2. 工厂函数：导出一个智能体工厂函数，服务器每次需要图时都会调用该函数。只有在需要针对每次运行自定义图时才使用此方式，例如根据助手配置选择不同的模型或工具。请保持工厂函数轻量，因为它会在每次调用时运行。

在这两种情况下，服务器都会在运行时自动注入为该部署配置的检查点器和内存存储。不要在图代码中配置这些内容，因为服务器需要管理它们以支持其他操作。

​

持久化

Agent Server 会持久化三类数据，默认情况下都由 PostgreSQL 提供支持：

• 核心资源数据：助手、线程、运行和 Cron 作业。这些数据始终存储在 PostgreSQL 中。
• 检查点（短期记忆）：在每个步骤写入的图执行状态快照。它们可以使运行具备持久性：如果工作进程被中断，运行可以从上一个检查点恢复，而不必从头开始。持久性模式决定检查点的写入频率——async（默认）在每个步骤后写入；exit 只存储最终状态。LangSmith 默认将其存储在 PostgreSQL 中，但你可以切换到 MongoDB 或自定义实现。详细信息请参阅配置检查点后端。
• 存储（长期记忆）：跨线程持久保存的记忆，使智能体能够在不同对话之间保留信息。默认存储在 PostgreSQL 中，但可以替换为自定义实现。详细信息请参阅添加自定义存储。

​

任务队列

客户端创建运行时，API 服务器会将其加入队列，队列工作进程会获取该运行并执行。工作进程也可以接收信号来取消正在进行的运行，并发布输出事件；打开 /stream 连接后，这些事件会实时转发给客户端。 Redis 负责 API 服务器与队列工作进程之间的信号传递、取消操作和流式 pub/sub。它只存储临时数据——用户数据或运行数据不会持久保存在 Redis 中。运行数据本身始终从 PostgreSQL 中读取并写入 PostgreSQL。 有关如何设置和管理这些组件的更多信息，请参阅托管选项指南。

​

运行时架构

​

部署模式

Agent Server 支持三种运行时配置：

• 单主机：API 服务器直接管理任务队列，不使用独立的队列工作进程。这是自托管部署的默认模式，适用于开发和低流量场景。
• API 与队列分离：专用队列工作进程在独立于 API 服务器的主机上处理运行。对于自托管部署，可以在配置中设置 queue.enabled: true 来启用此模式。每个层级都可以独立扩展——API 服务器根据请求量扩展，队列工作进程根据待处理运行数量扩展。
• 分布式运行时：API 进程和队列进程同样分开运行，但不同于由单个队列进程同时处理图的编排和执行，分布式运行时使用一个进程负责编排，另一个进程负责执行。适用于具有高并发要求的大规模部署。

下面介绍的容器架构和运行生命周期适用于单主机以及 API 与队列分离这两种配置。

​

容器架构

典型部署由两类长期运行的容器组成，它们都基于同一个 Docker 镜像构建（在基础镜像上安装你的项目代码）：

• API 服务器处理客户端请求（创建运行、读取线程状态、流式传输结果），但不会自行执行智能体代码。
• 队列工作进程是执行引擎。它们监听持久化任务队列，执行你的图代码，并写入检查点。

容器是无状态但持久运行的。任何时刻都必须至少有 1 个队列工作进程监听任务队列，以确保不会有运行无人处理。容器在其生命周期内可以处理许多运行。 API 服务器和队列工作进程属于独立的容器池，可以独立扩展。

​

运行执行生命周期

调用运行时，请求会经过多个组件：

1. 客户端向 API 服务器发送请求，API 服务器会在持久化任务队列中创建一个待处理运行。
2. 队列工作进程获取该运行、为其获取租约、加载相应的图并开始执行。队列会强制确保同一时间最多只能执行给定线程的 1 个运行。
3. 图执行过程中，工作进程会将检查点写入持久化层（频率取决于持久性模式），并通过配置的 pubsub 提供商广播流式事件。
4. 如果客户端打开了 /stream 连接，API 服务器会订阅 pubsub 通道，并通过服务器发送事件将事件实时转发给客户端。
5. 执行完成后，工作进程会更新运行状态，并释放其占用的槽位，以便执行下一个运行。

每个工作进程最多可以并发执行 N_JOBS_PER_WORKER 个运行（默认值：10），因此单个工作进程容器可以并行处理许多运行。该设置限制的是并发运行数量，而不是部署可以处理的 API 请求数量。API 服务器独立处理请求并单独扩展，因此请求处理能力不会受到 N_JOBS_PER_WORKER 的限制。有关调优建议，请参阅配置 Agent Server 以实现扩展。

​

了解更多

• 应用结构指南介绍了如何构建应用以进行部署。
• API 参考提供了有关 API 端点和数据模型的详细信息。

---