Skip to main content
功能API 允许您以最小的现有代码改动,将 LangGraph 的关键特性——持久化记忆人机交互流式传输——添加到您的应用程序中。 它旨在将这些功能集成到可能使用标准语言原语进行分支和控制流的现有代码中,例如 if 语句、for 循环和函数调用。与许多需要将代码重构为显式管道或DAG的数据编排框架不同,功能API允许您在不强制执行严格执行模型的情况下,将这些功能融入其中。 功能API使用两个关键构建块:
  • @entrypoint – 标记一个函数为工作流的起点,封装逻辑并管理执行流程,包括处理长时间运行的任务和中断。
  • @task – 表示一个离散的工作单元,例如API调用或数据处理步骤,可以在入口点异步执行。任务返回一个类似未来的对象,可以等待或同步解决。
这为构建具有状态管理和流式传输的工作流程提供了一个最小化抽象。
有关如何使用功能API的信息,请参阅使用功能API

功能API与图API

对于偏好声明式方法的用户,LangGraph的图API允许您使用图范式定义工作流程。这两个API共享相同的底层运行时,因此您可以在同一应用程序中一起使用它们。 以下是一些关键区别:
  • 控制流:功能API不需要考虑图结构。您可以使用标准的Python结构来定义工作流程。这通常会减少您需要编写的代码量。
  • 短期记忆GraphAPI需要声明一个状态,可能还需要定义reducer来管理图状态的更新。@entrypoint@tasks不需要显式状态管理,因为它们的状态仅限于函数内部,并且不会在函数之间共享。
  • 检查点:两个API都生成并使用检查点。在Graph API中,每次超级步骤之后都会生成一个新的检查点。在Functional API中,当任务执行时,它们的输出会被保存到一个与给定入口点关联的现有检查点中,而不是创建一个新的检查点。
  • 可视化:Graph API使得将工作流程可视化为图变得容易,这对于调试、理解工作流程以及与他人分享都很有用。功能API不支持可视化,因为图是在运行时动态生成的。

示例

以下我们展示了一个简单的应用,该应用可以撰写文章并中断以请求人工审核。
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.func import entrypoint, task
from langgraph.types import interrupt

@task
def write_essay(topic: str) -> str:
    """Write an essay about the given topic."""
    time.sleep(1) # A placeholder for a long-running task.
    return f"An essay about topic: {topic}"

@entrypoint(checkpointer=InMemorySaver())
def workflow(topic: str) -> dict:
    """A simple workflow that writes an essay and asks for a review."""
    essay = write_essay("cat").result()
    is_approved = interrupt({
        # Any json-serializable payload provided to interrupt as argument.
        # It will be surfaced on the client side as an Interrupt when streaming data
        # from the workflow.
        "essay": essay, # The essay we want reviewed.
        # We can add any additional information that we need.
        # For example, introduce a key called "action" with some instructions.
        "action": "Please approve/reject the essay",
    })

    return {
        "essay": essay, # The essay that was generated
        "is_approved": is_approved, # Response from HIL
    }
此工作流程将撰写一篇关于“猫”主题的论文,然后暂停以获取人类的评审。工作流程可以在提供评审之前无限期地中断。当工作流恢复时,它将从起点开始执行,但由于 writeEssay 任务的输出已经被保存,任务结果将直接从检查点加载,而不是重新计算。
import time
import uuid
from langgraph.func import entrypoint, task
from langgraph.types import interrupt
from langgraph.checkpoint.memory import InMemorySaver


@task
def write_essay(topic: str) -> str:
    """Write an essay about the given topic."""
    time.sleep(1)  # This is a placeholder for a long-running task.
    return f"An essay about topic: {topic}"

@entrypoint(checkpointer=InMemorySaver())
def workflow(topic: str) -> dict:
    """A simple workflow that writes an essay and asks for a review."""
    essay = write_essay("cat").result()
    is_approved = interrupt(
        {
            # Any json-serializable payload provided to interrupt as argument.
            # It will be surfaced on the client side as an Interrupt when streaming data
            # from the workflow.
            "essay": essay,  # The essay we want reviewed.
            # We can add any additional information that we need.
            # For example, introduce a key called "action" with some instructions.
            "action": "Please approve/reject the essay",
        }
    )
    return {
        "essay": essay,  # The essay that was generated
        "is_approved": is_approved,  # Response from HIL
    }


thread_id = str(uuid.uuid4())
config = {"configurable": {"thread_id": thread_id}}
for item in workflow.stream("cat", config):
    print(item)
# > {'write_essay': 'An essay about topic: cat'}
# > {
# >     '__interrupt__': (
# >        Interrupt(
# >            value={
# >                'essay': 'An essay about topic: cat',
# >                'action': 'Please approve/reject the essay'
# >            },
# >            id='b9b2b9d788f482663ced6dc755c9e981'
# >        ),
# >    )
# > }
一篇论文已经撰写完毕,准备进行审查。一旦审查完成,我们就可以继续工作流程:
from langgraph.types import Command

# Get review from a user (e.g., via a UI)
# In this case, we're using a bool, but this can be any json-serializable value.
human_review = True

for item in workflow.stream(Command(resume=human_review), config):
    print(item)
{'workflow': {'essay': 'An essay about topic: cat', 'is_approved': False}}
工作流程已完成,并已将审阅添加到论文中。

入口点

The @entrypoint 装饰器可用于从函数创建工作流。它封装工作流逻辑并管理执行流程,包括处理 长时间运行的任务中断

定义

一个 入口点 通过使用 @entrypoint 装饰器来定义。 该函数必须接受一个单一的位置参数,该参数作为工作流程输入。如果您需要传递多个数据项,请使用字典作为第一个参数的输入类型。 使用 entrypoint 装饰一个函数会生成一个 Pregel 实例,该实例有助于管理工作流的执行(例如,处理流式传输、恢复和检查点)。 您通常需要将 检查点器 传递给 @entrypoint 装饰器以启用持久性和使用 人机交互 等功能。
from langgraph.func import entrypoint

@entrypoint(checkpointer=checkpointer)
def my_workflow(some_input: dict) -> int:
    # some logic that may involve long-running tasks like API calls,
    # and may be interrupted for human-in-the-loop.
    ...
    return result
序列化 入口点的 输入输出 必须是可 JSON 序列化的,以支持检查点。请参阅 序列化 部分,获取更多详细信息。

可注入参数

在声明一个 entrypoint 时,您可以请求访问将在运行时自动注入的附加参数。这些参数包括:
参数描述
previous访问与给定线程关联的先前 checkpoint 的状态。参见 短期记忆
store[BaseStore][langgraph.store.base.BaseStore] 的实例。适用于 长期记忆
writer用于在处理 Async Python < 3.11 时访问 StreamWriter。有关详细信息,请参阅 使用功能 API 进行流式传输
config用于访问运行时配置。有关信息,请参阅 RunnableConfig
使用适当的名称和类型注解声明参数。
from langchain_core.runnables import RunnableConfig
from langgraph.func import entrypoint
from langgraph.store.base import BaseStore
from langgraph.store.memory import InMemoryStore

in_memory_store = InMemoryStore(...)  # An instance of InMemoryStore for long-term memory

@entrypoint(
    checkpointer=checkpointer,  # Specify the checkpointer
    store=in_memory_store  # Specify the store
)
def my_workflow(
    some_input: dict,  # The input (e.g., passed via `invoke`)
    *,
    previous: Any = None, # For short-term memory
    store: BaseStore,  # For long-term memory
    writer: StreamWriter,  # For streaming custom data
    config: RunnableConfig  # For accessing the configuration passed to the entrypoint
) -> ...:

执行

使用@entrypoint可以得到一个Pregel对象,该对象可以使用invokeainvokestreamastream方法进行执行。
config = {
    "configurable": {
        "thread_id": "some_thread_id"
    }
}
my_workflow.invoke(some_input, config)  # Wait for the result synchronously

恢复

在执行中断后恢复执行可以通过向 Command 原语传递一个 resume 值来实现。
from langgraph.types import Command

config = {
    "configurable": {
        "thread_id": "some_thread_id"
    }
}

my_workflow.invoke(Command(resume=some_resume_value), config)
错误后恢复 在错误后恢复,运行 entrypoint 并带有 None 以及相同的 线程 ID(配置)。 这假设底层错误已被解决,执行可以成功进行。

config = {
    "configurable": {
        "thread_id": "some_thread_id"
    }
}

my_workflow.invoke(None, config)

短期记忆

当使用 checkpointer 定义 entrypoint 时,它会在 检查点 中存储在相同 线程 ID 的连续调用之间的信息。 这允许使用 previous 参数访问前一次调用的状态。 默认情况下,previous 参数是前一次调用的返回值。
@entrypoint(checkpointer=checkpointer)
def my_workflow(number: int, *, previous: Any = None) -> int:
    previous = previous or 0
    return number + previous

config = {
    "configurable": {
        "thread_id": "some_thread_id"
    }
}

my_workflow.invoke(1, config)  # 1 (previous was None)
my_workflow.invoke(2, config)  # 3 (previous was 1 from the previous invocation)

entrypoint.final

entrypoint.final 是一种特殊的原始类型,可以从入口点返回,并允许将 保存在检查点中的值入口点的返回值 解耦 第一个值是入口点的返回值,第二个值是将在检查点中保存的值。类型注解为 entrypoint.final[return_type, save_type]
@entrypoint(checkpointer=checkpointer)
def my_workflow(number: int, *, previous: Any = None) -> entrypoint.final[int, int]:
    previous = previous or 0
    # This will return the previous value to the caller, saving
    # 2 * number to the checkpoint, which will be used in the next invocation
    # for the `previous` parameter.
    return entrypoint.final(value=previous, save=2 * number)

config = {
    "configurable": {
        "thread_id": "1"
    }
}

my_workflow.invoke(3, config)  # 0 (previous was None)
my_workflow.invoke(1, config)  # 6 (previous was 3 * 2 from the previous invocation)

任务

一个 任务 代表一个离散的工作单元,例如API调用或数据处理步骤。它有两个关键特征:
  • 异步执行:任务被设计为异步执行,允许多个操作同时运行而不会阻塞。
  • 检查点:任务结果被保存到检查点,使得可以从最后保存的状态恢复工作流程。(有关更多详细信息,请参阅persistence)。

定义

任务使用 @task 装饰器定义,该装饰器包装了一个常规的 Python 函数。
from langgraph.func import task

@task()
def slow_computation(input_value):
    # Simulate a long-running operation
    ...
    return result
序列化 任务的输出必须是JSON可序列化的,以支持检查点。

执行

任务 只能在 入口点、另一个 任务状态图节点 内部调用。 任务 不能 从主应用程序代码中直接调用。 当您调用一个 任务 时,它将立即返回一个未来对象。未来对象是一个用于表示稍后可用的结果的占位符。 要获取任务的结果,您可以同步等待(使用 result())或异步等待(使用 await)。
@entrypoint(checkpointer=checkpointer)
def my_workflow(some_input: int) -> int:
    future = slow_computation(some_input)
    return future.result()  # Wait for the result synchronously

何时使用任务

任务在以下场景中非常有用:
  • 检查点: 当您需要将长时间运行的操作的结果保存到检查点时,以便在恢复工作流程时无需重新计算。
  • 人工干预: 如果您正在构建需要人工干预的工作流程,您必须使用任务来封装任何随机性(例如API调用),以确保工作流程可以正确恢复。有关更多详细信息,请参阅确定性部分。
  • 并行执行: 对于I/O密集型任务,任务可以启用并行执行,允许多个操作同时运行而不会阻塞(例如,调用多个API)。
  • 可观察性: 使用任务封装操作提供了一种跟踪工作流程进度和监控单个操作执行的方式,使用LangSmith
  • 可重试工作: 当工作需要重试以处理失败或不一致性时,任务提供了一种封装和管理重试逻辑的方式。

序列化

LangGraph中的序列化有两个关键方面:
  1. entrypoint 的输入和输出必须是可 JSON 序列化的。
  2. task 的输出必须是可 JSON 序列化的。
这些要求是启用检查点和工作流程恢复所必需的。使用Python原语,如字典、列表、字符串、数字和布尔值,以确保您的输入和输出可序列化。 序列化确保工作流状态,如任务结果和中间值,可以可靠地保存和恢复。这对于实现人工干预、容错性和并行执行至关重要。 提供不可序列化的输入或输出,当工作流配置了检查点时,将导致运行时错误。

决定性

为了利用如人机交互等特性,任何随机性都应该封装在任务中。这保证了当执行被暂停(例如,因为人机交互)然后恢复时,它将遵循相同的_步骤序列_,即使任务的结果是非确定性的。 LangGraph通过在执行过程中持久化任务子图的结果来实现这种行为。一个精心设计的流程确保了恢复执行遵循相同的步骤序列,从而可以正确检索先前计算的结果,而无需重新执行它们。这对于运行时间较长的任务或具有非确定性结果的任务特别有用,因为它避免了重复之前已完成的工作,并允许从本质上相同的状态恢复。 尽管工作流程的不同运行可能产生不同的结果,但恢复特定运行时,应始终遵循记录的步骤序列。这允许LangGraph高效地查找在图被中断之前执行的任务子图结果,从而避免重新计算它们。

一致性

幂等性确保多次执行相同的操作会产生相同的结果。这有助于防止重复的API调用和冗余处理,如果由于失败而重新执行某个步骤。始终将API调用放在任务函数中进行检查点设置,并设计它们在重新执行时保持幂等性。如果任务开始但未成功完成,则可能发生重新执行。然后,如果工作流恢复,任务将再次运行。使用幂等性键或验证现有结果以避免重复。

常见陷阱

处理副作用

将副作用(例如,写入文件、发送电子邮件)封装在任务中,以确保在恢复工作流时不会多次执行。
在本例中,一个副作用(写入文件)被直接包含在工作流程中,因此当恢复工作流程时,它将被执行第二次。
@entrypoint(checkpointer=checkpointer)
def my_workflow(inputs: dict) -> int:
    # This code will be executed a second time when resuming the workflow.
    # Which is likely not what you want.
    with open("output.txt", "w") as f:  
        f.write("Side effect executed")  
    value = interrupt("question")
    return value

非确定性控制流

可能每次都会产生不同结果的操作(如获取当前时间或随机数)应封装在任务中,以确保在恢复时返回相同的结果。
  • 在任务中:获取随机数(5)→ 中断 → 恢复 →(再次返回5)→ …
  • 不在任务中:获取随机数(5)→ 中断 → 恢复 → 获取新的随机数(7)→ …
这在使用人机交互工作流程并多次调用中断时尤为重要。LangGraph为每个任务/入口点保存一个恢复值的列表。当遇到中断时,它会与相应的恢复值进行匹配。这种匹配是严格基于索引的,因此恢复值的顺序应与中断的顺序相匹配。 如果在恢复时未保持执行顺序,一个 interrupt 调用可能与错误的 resume 值匹配,从而导致结果不正确。 请阅读关于确定性的部分以获取更多详细信息。
在本例中,工作流程使用当前时间来确定要执行哪个任务。这是非确定性的,因为工作流程的结果取决于执行时的时间。
from langgraph.func import entrypoint

@entrypoint(checkpointer=checkpointer)
def my_workflow(inputs: dict) -> int:
    t0 = inputs["t0"]
    t1 = time.time()  

    delta_t = t1 - t0

    if delta_t > 1:
        result = slow_task(1).result()
        value = interrupt("question")
    else:
        result = slow_task(2).result()
        value = interrupt("question")

    return {
        "result": result,
        "value": value
    }