你可能需要为新的运行使用不同的配置来重建图。例如,你可能希望根据用户的凭证加载不同的工具。本指南将介绍如何使用 ServerRuntime 实现这一点。
在大多数情况下,最好在各个节点中根据配置进行条件判断,而不是动态更改整个图的结构。这样更易于测试和管理。

前置条件

  • 请先查看这份操作指南,了解如何设置应用以进行部署。
  • ServerRuntime 要求 langgraph-api >= 0.7.31 和 langgraph-sdk >= 0.3.5。在此之前,图工厂只能接受一个 config: RunnableConfig 参数。

定义图

假设你有一个包含简单图的应用,该图调用 LLM 并将响应返回给用户。应用文件目录如下所示:
其中,图定义在 agents.py 中。

不重建

部署 Agent Server 最常见的方式,是引用在文件顶层定义的已编译图实例。示例如下:
要让服务器识别你的图,需要在 LangGraph API 配置(langgraph.json)中指定包含 CompiledStateGraph 实例的变量路径,例如:

重建

要在每次新运行时重建图,请提供一个返回(或生成)图的工厂函数。该工厂可以选择接受 ServerRuntime 参数或 RunnableConfig 参数。服务器会检查函数的类型注解,以确定要注入哪些参数,因此请确保包含正确的类型提示。服务器的队列工作进程会在需要处理运行时调用工厂函数。对于某些其他端点,例如更新状态、读取状态或获取助手架构,也会调用该函数。ServerRuntime 会告诉你触发调用的上下文。
ServerRuntime 目前处于测试阶段,未来版本中可能会发生变化。

简单工厂

最简单的形式是一个返回已编译图的普通 async def 函数:

上下文管理器工厂

如果你需要设置和释放资源(数据库连接、加载 MCP 工具等),请使用异步上下文管理器。使用 runtime.execution_runtime 检查当前调用图是为了实际执行,还是仅用于自省(架构、可视化):
最后,在 langgraph.json 中指定工厂的路径:

ServerRuntime 参考

你的工厂函数会接收一个 ServerRuntime 实例,该实例包含以下属性: 方法:

访问上下文

除了执行运行之外,服务器还会在多个上下文中调用你的工厂。在所有上下文中,返回的图都应具有相同的拓扑结构(节点、边和状态架构)。在写入上下文(threads.create_run、threads.update)中,拓扑结构不匹配可能导致状态更新错误。在读取上下文(threads.read、assistants.read)中,不匹配会影响待处理任务、架构和可视化结果,但不会破坏数据。使用 execution_runtime 可以在不改变图结构的情况下,有条件地设置开销较大的资源。

按图自定义追踪

你可以使用工厂函数,为特定图自定义或禁用追踪。有关示例,请参阅条件追踪:自定义已部署 Agent 中的追踪。 请参阅LangGraph API 配置文件以了解更多信息。