API 概念¶

此页面介绍了 LangGraph 云 API 的高级概念。LangGraph（Python 库）的概念指南在此。

数据模型¶

LangGraph 云 API 由一些核心数据模型组成：助手、线程、运行和计划任务。

助手¶

在构建代理时，通常会进行快速更改，这些更改不会改变图逻辑。例如，仅仅更改提示或 LLM 选择，就可能对代理的行为产生重大影响。助手提供了一种简单的方法来进行此类更改并保存这些更改，以方便代理配置。这至少有两个用例

助手为开发人员提供了一种快速简便的方法来修改和版本化图版本，以便进行实验。
助手可以通过 LangGraph Studio 进行修改，提供了一种无代码方式来配置代理（例如，针对业务用户）。

配置助手¶

在实践中，助手只是一个具有特定配置的图的实例。因此，多个助手可以引用同一个图，但可以包含不同的配置，例如提示、模型和其他图配置选项。LangGraph 云 API 提供了几个端点来创建和管理助手。有关如何创建助手的更多详细信息，请参阅API 参考和此操作指南。

助手版本控制¶

assistant versions

创建助手后，可以保存并对其进行版本控制，以便跟踪配置随时间的变化。可以从三个级别来考虑这一点

1) 图概述了通用代理应用程序逻辑 2) 代理配置选项代表可以更改的参数 3) 助手版本保存并跟踪代理配置选项的特定设置

例如，如果你有一个帮助计划旅行的代理，可以为每个用户创建一个新的助手，并将特定的用户偏好（例如，期望的航空公司和汽车服务）传递给该助手。当每个用户与其自己的助手交互时，可以保存助手版本，以跟踪用户的特定愿望。阅读此操作指南，了解如何通过Studio 和 SDK 使用助手版本控制。

线程¶

线程包含一组运行的累积状态。如果在线程上执行运行，则助手的底层图的状态将持久保存到线程。可以检索线程的当前和历史状态。要持久保存状态，必须在执行运行之前创建线程。

线程在特定时间点的状态称为检查点。

有关线程和检查点的更多信息，请参阅LangGraph 概念指南的此部分。

LangGraph 云 API 提供了几个端点来创建和管理线程以及线程状态。有关更多详细信息，请参阅API 参考。

运行¶

运行是助手的一次调用。每次运行可能具有自己的输入、配置和元数据，这些可能会影响底层图的执行和输出。可以选择在线程上执行运行。

LangGraph 云 API 提供了几个端点来创建和管理运行。有关更多详细信息，请参阅API 参考。

计划任务¶

按某个时间表运行图通常很有用。LangGraph Cloud 支持计划任务，这些任务会按照用户定义的时间表运行。用户指定时间表、助手和一些输入。之后，LangGraph 云将在指定的时间表上

使用指定的助手创建一个新线程
将指定的输入发送到该线程

请注意，这会将相同的输入发送到线程，每次都如此。有关创建计划任务的更多信息，请参阅操作指南。

LangGraph 云 API 提供了几个端点来创建和管理计划任务。有关更多详细信息，请参阅API 参考。

功能¶

LangGraph 云 API 提供了几个功能来支持复杂的代理架构。

流式处理¶

流式处理对于使 LLM 应用程序对最终用户具有响应性至关重要。在创建流式运行时，流式模式将决定哪些数据将流回 API 客户端。LangGraph 云 API 支持五种流式模式。

values：在执行每个超级步骤之后，流式处理图的完整状态。有关流式处理值的更多信息，请参阅操作指南。
messages：流式处理完整的消息（在节点执行结束时），以及在节点内部生成的任何消息的令牌。此模式主要用于支持聊天应用程序。只有当你的图包含 messages 键时，此模式才可用。有关流式处理消息的更多信息，请参阅操作指南。
updates：在执行每个节点之后，流式处理图状态的更新。有关流式处理更新的更多信息，请参阅操作指南。
events：流式处理在图执行期间发生的全部事件（包括图的状态）。有关流式处理事件的更多信息，请参阅操作指南。这可以用于对 LLM 进行逐令牌的流式处理。
debug：流式处理整个图执行过程中的调试事件。有关流式处理调试事件的更多信息，请参阅操作指南。

你也可以同时指定多种流式模式。有关同时配置多种流式模式的更多信息，请参阅操作指南。

有关如何创建流式运行，请参阅API 参考。

流式模式 values、updates 和 debug 与 LangGraph 库中可用的模式非常相似，有关这些模式的更深入的概念解释，可以参阅 LangGraph 库文档在此。

流式模式 events 与在 LangGraph 库中使用 .astream_events 相同，有关此模式的更深入的概念解释，可以参阅 LangGraph 库文档在此。

`mode="messages"`¶

流式模式 messages 是一种新的流式模式，目前仅在 API 中可用。此模式能够实现什么功能？

此模式专注于流式处理返回的消息。它目前假定你的图中有一个 messages 键，该键是一个消息列表。假设我们有一个简单的 React 代理已部署，此流看起来像什么？

所有发出的事件都有两个属性

event：这是事件的名称
data：这是与事件关联的数据

让我们在一个应该触发工具调用的问题上运行它

thread = await client.threads.create()
input = {"messages": [{"role": "user", "content": "what's the weather in sf?"}]}

events = []
async for event in client.runs.stream(
    thread["thread_id"],
    assistant_id="agent",  # This may need to change depending on the graph you deployed
    input=input,
    stream_mode="messages",
):
    print(event.event)

metadata
messages/complete
messages/metadata
messages/partial
...
messages/partial
messages/complete
messages/complete
messages/metadata
messages/partial
...
messages/partial
messages/complete
end

我们首先获得一些 metadata，这是有关运行的元数据。

StreamPart(event='metadata', data={'run_id': '1ef657cf-ae55-6f65-97d4-f4ed1dbdabc6'})

然后我们获得一个 messages/complete 事件，这是一个已完全形成的消息，正在发出。在本例中，这仅仅是我们发送的输入消息。

StreamPart(event='messages/complete', data=[{'content': 'hi!', 'additional_kwargs': {}, 'response_metadata': {}, 'type': 'human', 'name': None, 'id': '833c09a3-bb19-46c9-81d9-1e5954ec5f92', 'example': False}])

然后我们获得一个 messages/metadata 事件，它只是在通知我们正在开始一条新消息。

StreamPart(event='messages/metadata', data={'run-985c0f14-9f43-40d4-a505-4637fc58e333': {'metadata': {'created_by': 'system', 'run_id': '1ef657de-7594-66df-8eb2-31518e4a1ee2', 'graph_id': 'agent', 'thread_id': 'c178eab5-e293-423c-8e7d-1d113ffe7cd9', 'model_name': 'openai', 'assistant_id': 'fe096781-5601-53d2-b2f6-0d3403f7e9ca', 'langgraph_step': 1, 'langgraph_node': 'agent', 'langgraph_triggers': ['start:agent'], 'langgraph_task_idx': 0, 'ls_provider': 'openai', 'ls_model_name': 'gpt-4o', 'ls_model_type': 'chat', 'ls_temperature': 0.0}}})

然后我们获得大量 messages/partial 事件，这些事件是来自 LLM 的单个令牌！在下面的例子中，我们可以看到工具调用的开头。

StreamPart(event='messages/partial', data=[{'content': '', 'additional_kwargs': {'tool_calls': [{'index': 0, 'id': 'call_w8Hr8dHGuZCPgRfd5FqRBArs', 'function': {'arguments': '', 'name': 'tavily_search_results_json'}, 'type': 'function'}]}, 'response_metadata': {}, 'type': 'ai', 'name': None, 'id': 'run-985c0f14-9f43-40d4-a505-4637fc58e333', 'example': False, 'tool_calls': [], 'invalid_tool_calls': [{'name': 'tavily_search_results_json', 'args': '', 'id': 'call_w8Hr8dHGuZCPgRfd5FqRBArs', 'error': None}], 'usage_metadata': None}])

之后，我们获得一个 messages/complete 事件，这是一个 AIMessage 正在完成。它现在是一个完整的工具调用

StreamPart(event='messages/complete', data=[{'content': '', 'additional_kwargs': {'tool_calls': [{'index': 0, 'id': 'call_w8Hr8dHGuZCPgRfd5FqRBArs', 'function': {'arguments': '{"query":"current weather in San Francisco"}', 'name': 'tavily_search_results_json'}, 'type': 'function'}]}, 'response_metadata': {'finish_reason': 'tool_calls', 'model_name': 'gpt-4o-2024-05-13', 'system_fingerprint': 'fp_157b3831f5'}, 'type': 'ai', 'name': None, 'id': 'run-985c0f14-9f43-40d4-a505-4637fc58e333', 'example': False, 'tool_calls': [{'name': 'tavily_search_results_json', 'args': {'query': 'current weather in San Francisco'}, 'id': 'call_w8Hr8dHGuZCPgRfd5FqRBArs'}], 'invalid_tool_calls': [], 'usage_metadata': None}])

之后，我们获得另一个 messages/complete 事件。这是一个工具消息，我们的代理已调用了一个工具，获得了响应，现在将其以工具消息的形式插入状态。

StreamPart(event='messages/complete', data=[{'content': '[{"url": "https://www.weatherapi.com/", "content": "{\'location\': {\'name\': \'San Francisco\', \'region\': \'California\', \'country\': \'United States of America\', \'lat\': 37.78, \'lon\': -122.42, \'tz_id\': \'America/Los_Angeles\', \'localtime_epoch\': 1724877689, \'localtime\': \'2024-08-28 13:41\'}, \'current\': {\'last_updated_epoch\': 1724877000, \'last_updated\': \'2024-08-28 13:30\', \'temp_c\': 23.3, \'temp_f\': 73.9, \'is_day\': 1, \'condition\': {\'text\': \'Partly cloudy\', \'icon\': \'//cdn.weatherapi.com/weather/64x64/day/116.png\', \'code\': 1003}, \'wind_mph\': 15.0, \'wind_kph\': 24.1, \'wind_degree\': 310, \'wind_dir\': \'NW\', \'pressure_mb\': 1014.0, \'pressure_in\': 29.93, \'precip_mm\': 0.0, \'precip_in\': 0.0, \'humidity\': 57, \'cloud\': 25, \'feelslike_c\': 25.0, \'feelslike_f\': 77.1, \'windchill_c\': 20.9, \'windchill_f\': 69.6, \'heatindex_c\': 23.3, \'heatindex_f\': 74.0, \'dewpoint_c\': 12.9, \'dewpoint_f\': 55.2, \'vis_km\': 16.0, \'vis_miles\': 9.0, \'uv\': 6.0, \'gust_mph\': 19.5, \'gust_kph\': 31.3}}"}]', 'additional_kwargs': {}, 'response_metadata': {}, 'type': 'tool', 'name': 'tavily_search_results_json', 'id': '0112eba5-7660-4375-9f24-c7a1d6777b97', 'tool_call_id': 'call_w8Hr8dHGuZCPgRfd5FqRBArs'}])

之后，我们看到代理正在执行另一个 LLM 调用，并流式处理返回响应。然后我们获得一个 end 事件

StreamPart(event='end', data=None)

就是这样！这是一个更专注的流式模式，专门专注于流式处理返回消息。有关更多信息，请参阅此操作指南。

人工介入¶

在很多情况下，图无法完全自主地运行。例如，用户可能需要输入一些函数调用所需的额外参数，或者选择图继续执行的下一条边。在这些情况下，我们需要插入一些人工介入交互，你可以在人工介入操作指南中了解更多相关信息。

双重文本¶

用户经常会以意想不到的方式与你的图交互。例如，用户可能发送一条消息，然后在图完成运行之前发送第二条消息。为了解决“双重文本”（即在第一次运行完成之前第二次提示图）的问题，LangGraph 提供了四种不同的解决方案，所有这些解决方案都在双重文本操作指南中介绍。这些选项是

reject：这是最简单的选项，它只是拒绝任何后续运行，不允许双重文本。有关配置拒绝双重文本选项的更多信息，请参阅操作指南。
enqueue：这是一个比较简单的选项，它会继续执行第一次运行，直到它完成整个运行，然后将新的输入作为单独的运行发送。有关配置排队双重文本选项的更多信息，请参阅操作指南。
interrupt：此选项会中断当前执行，但会保存到目前为止完成的所有工作。然后插入用户输入并继续执行。如果启用此选项，你的图应该能够处理可能出现的奇怪的边缘情况。有关配置中断双重文本选项的更多信息，请参阅操作指南。
rollback: 此选项会回滚到该点之前完成的所有工作。然后它会发送用户输入，基本上就像它只是遵循原始运行输入一样。请参阅操作指南以了解如何配置回滚双文本选项。

无状态运行¶

所有运行都使用内置的检查点器来存储运行的检查点。但是，通常有用的是只需启动运行，而无需担心显式创建线程，也不希望保留这些检查点。无状态运行允许您通过公开一个端点来做到这一点

接收用户输入
在后台创建线程
运行代理，但跳过所有检查点步骤
之后清理线程

无状态运行仍然像常规重试一样被重试，因为每个节点都是按节点进行的，而所有内容都仍在内存中，因此不使用检查点。

唯一的区别在于无状态的后台运行，如果任务工作程序中途死亡（不是因为运行本身失败，而是由于某种外部原因），那么整个运行将像任何后台运行一样被重试，但是

有状态的后台运行会从上次成功的检查点重试
无状态的后台运行会从头开始重试

请参阅操作指南以了解如何创建无状态运行。

Webhook¶

对于所有类型的运行，Langgraph cloud 都支持完成 webhook。创建运行时，您可以传递一个 webhook URL，该 URL 会在运行完成（成功或失败）时被调用。这对于后台运行和 cron 作业尤其有用，因为 webhook 可以为您提供运行已完成的指示，并且您可以为您的应用程序执行进一步的操作。

请参阅此操作指南以了解如何在 LangGraph Cloud 中使用 webhook。

部署¶

LangGraph Cloud 提供了多个功能来支持安全和强大的部署。

身份验证¶

部署到 LangGraph Cloud 的 LangGraph 应用程序会自动配置 LangSmith 身份验证。为了调用 API，需要一个有效的 LangSmith API 密钥。

本地测试¶

在将您的应用程序部署到 LangGraph Cloud 的生产环境之前，您可能希望在本地测试您的图，以确保一切按预期运行。幸运的是，LangGraph 通过使用 LangGraph CLI 使这变得容易。请参阅此操作指南中了解更多信息，或查看 CLI 参考以了解更多信息。