以编程方式使用文档

LangSmith 部署的 **代理服务器** 提供了用于创建和管理基于代理的应用程序的 API。它建立在 助手的概念之上，助手是为特定任务配置的代理，并包含内置的 持久化 和 **任务队列**。这个多功能的 API 支持广泛的代理应用程序用例，从后台处理到实时交互。

使用代理服务器创建和管理：

Assistants

Threads

Runs

Cron jobs

应用程序结构

要部署代理服务器应用程序，您需要指定要部署的图，以及任何相关的配置设置，例如依赖项和环境变量。

阅读 应用程序结构 指南，了解如何为部署构建 LangGraph 应用程序。

部署的组成部分

部署 Agent Server 时，您正在部署一个或多个 图、一个用于 持久化的数据库，以及一个 任务队列.

图

使用 Agent Server 部署图时，您实际上是在部署一个"蓝图"，用于创建 助手.

图最常用于实现一个 代理，但并非必须如此。例如，一个图可以实现一个简单的聊天机器人，只支持来回对话，而不影响任何应用程序控制流。实际上，随着应用程序变得越来越复杂，一个图通常会实现更复杂的流程，可能会使用 多个代理 协同工作。

图不一定非要使用 LangGraph 编写。您还可以使用 LangGraph 函数式 API 部署使用其他框架构建的代理（如 Strands 或 Google ADK）。有关详细信息，请参阅 部署其他框架.

图的加载和编译

图的编译方式和时机取决于您如何在应用程序中注册它 应用结构:

  1. **已编译的图** （推荐）：导出一个已编译的 CompiledGraph 实例。服务器在容器启动时加载一次，并在每次运行时重复使用它——每个请求都没有编译开销。
  2. **工厂函数**导出一个代理工厂函数，服务器每次需要图时会调用该函数。仅在需要每次运行图定制时使用（例如，根据助手配置选择不同的模型或工具）。保持工厂函数轻量，因为它们每次调用都会运行。

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

持久化

Agent Server 持久化三种类型的数据，全部由 PostgreSQL 默认支持：

  • 核心资源数据：助手、线程、运行和定时任务。始终存储在 PostgreSQL 中。
  • 检查点（短期记忆）：在每个步骤写入的图执行状态快照。它们使运行具有持久性：如果工作线程中断，运行可以从最后一个检查点恢复，而不是从头开始。持久性模式控制检查点频率——async （默认）在每个步骤后写入； exit 仅存储最终状态。LangSmith 默认将其存储在 PostgreSQL 中；但您可以切换到 MongoDB 或自定义实现。详情请参阅 配置检查点后端.
  • 存储（长期记忆）：跨线程持久化的内存，使代理能够在独立对话之间保留信息。默认存储在 PostgreSQL 中，但可以用自定义实现替换。详情请参阅 添加自定义存储.

任务队列

当客户端创建运行时，API 服务器将其加入队列，队列工作线程拾取它执行。工作线程也可以收到信号取消正在进行的运行，并发布打开 /stream 到客户端的实时连接。

Redis handles the signaling, cancellation, and streaming pub/sub between API servers and queue workers. It stores only ephemeral data—no user or run data persists in Redis. Run data itself is always read from and written to PostgreSQL.

有关如何设置和管理这些组件的更多信息，请查看 托管选项 guide.

运行时架构

部署模式

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

  • 单主机：API 服务器直接管理任务队列，没有独立的工作线程。对于自托管部署这是默认配置，适合开发和低流量场景。
  • 分离 API 和队列：专用队列工作线程在独立于 API 服务器的主机上处理运行执行。对于自托管部署，通过设置 queue.enabled: true 在配置中启用。每个层级独立扩展——API 服务器按请求量扩展，队列工作线程按待处理运行数扩展。
  • 分布式运行时：API 和队列进程再次分开运行，但分布式运行时不是使用单个队列进程处理图的编排和执行，而是使用一个进程进行编排，一个进程进行执行。适用于高并发要求的大规模部署。

下面描述的容器架构和运行生命周期适用于单主机以及分离式 API 和队列配置。

容器架构

典型的部署包含两种长时间运行的容器，两者都基于相同的 Docker 镜像构建（在包含项目代码的基础镜像之上）：

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

容器是 **无状态的** 但却是持久化的。必须始终至少有 1 个队列工作器监听任务队列，以确保没有运行被遗弃。容器可以在其整个生命周期内服务多次运行。

API 服务器和队列工作器是独立的容器池，并且 可独立扩展.

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

运行执行生命周期

当您调用运行时，请求会流经多个组件：

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

每个工作器最多处理 N_JOBS_PER_WORKER 个并发运行（默认值为 10），因此单个工作器容器可以并行处理多个运行。请参阅 配置代理服务器以实现扩展 以获取调优指导。

了解更多

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