跳到内容

代理

名称 描述
AgentState

代理的状态。

函数

名称 描述
create_react_agent

创建一个代理图,该图循环调用工具直到满足停止条件。

AgentState

基类: TypedDict

代理的状态。

create_react_agent

create_react_agent(
    model: Union[str, LanguageModelLike],
    tools: Union[
        Sequence[Union[BaseTool, Callable, dict[str, Any]]],
        ToolNode,
    ],
    *,
    prompt: Optional[Prompt] = None,
    response_format: Optional[
        Union[
            StructuredResponseSchema,
            tuple[str, StructuredResponseSchema],
        ]
    ] = None,
    pre_model_hook: Optional[RunnableLike] = None,
    post_model_hook: Optional[RunnableLike] = None,
    state_schema: Optional[StateSchemaType] = None,
    config_schema: Optional[Type[Any]] = None,
    checkpointer: Optional[Checkpointer] = None,
    store: Optional[BaseStore] = None,
    interrupt_before: Optional[list[str]] = None,
    interrupt_after: Optional[list[str]] = None,
    debug: bool = False,
    version: Literal["v1", "v2"] = "v2",
    name: Optional[str] = None
) -> CompiledGraph

创建一个代理图,该图循环调用工具直到满足停止条件。

有关使用 create_react_agent 的更多详细信息,请访问代理文档。

参数

名称 类型 描述 默认值
模型 Union[str, LanguageModelLike]

支持工具调用的 LangChain 聊天模型。

必需
工具 Union[Sequence[Union[BaseTool, Callable, dict[str, Any]]], ToolNode]

工具列表或 ToolNode 实例。如果提供空列表,代理将由一个不带工具调用的单一 LLM 节点组成。

必需
提示 Optional[Prompt]

LLM 的可选提示。可以采用几种不同的形式

  • str:这将被转换为 SystemMessage 并添加到状态["messages"]中的消息列表的开头。
  • SystemMessage:这将被添加到状态["messages"]中的消息列表的开头。
  • Callable:此函数应接收完整的图状态,其输出随后传递给语言模型。
  • Runnable:此可运行对象应接收完整的图状态,其输出随后传递给语言模型。
响应格式 Optional[Union[StructuredResponseSchema, tuple[str, StructuredResponseSchema]]]

最终代理输出的可选模式。

如果提供,输出将格式化以匹配给定的模式,并以“structured_response”状态键返回。如果未提供,输出状态中将不存在structured_response。可以作为以下形式传递

- an OpenAI function/tool schema,
- a JSON Schema,
- a TypedDict class,
- or a Pydantic class.
- a tuple (prompt, schema), where schema is one of the above.
    The prompt will be used together with the model that is being used to generate the structured response.

重要

response_format 要求模型支持 .with_structured_output

注意

图将在代理循环结束后单独调用LLM以生成结构化响应。这并非获取结构化响应的唯一策略,更多选项请参见此指南

pre_model_hook Optional[RunnableLike]

一个可选节点,添加到agent节点(即调用LLM的节点)之前。对于管理长消息历史(例如,消息修剪、摘要等)非常有用。前置模型钩子必须是可调用对象或可运行对象,它接收当前图状态并以以下形式返回状态更新

# At least one of `messages` or `llm_input_messages` MUST be provided
{
    # If provided, will UPDATE the `messages` in the state
    "messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), ...],
    # If provided, will be used as the input to the LLM,
    # and will NOT UPDATE `messages` in the state
    "llm_input_messages": [...],
    # Any other state keys that need to be propagated
    ...
}

重要

必须提供messagesllm_input_messages中的至少一个,并将作为agent节点的输入。其余键将添加到图状态中。

警告

如果您在 pre-model hook 中返回 messages,您应该通过以下方式覆盖 messages

{
    "messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), *new_messages]
    ...
}
post_model_hook Optional[RunnableLike]

一个可选节点,添加到agent节点(即调用LLM的节点)之后。对于实现人机交互、防护栏、验证或其他后处理非常有用。后置模型钩子必须是可调用对象或可运行对象,它接收当前图状态并返回状态更新。

注意

仅适用于 version="v2"

state_schema Optional[StateSchemaType]

一个可选的状态模式,用于定义图状态。必须包含 messagesremaining_steps 键。默认使用定义这两个键的 AgentState

config_schema Optional[Type[Any]]

一个可选的配置模式。使用它通过 agent.config_specs 公开可配置参数。

检查器 Optional[Checkpointer]

一个可选的检查点保存对象。这用于持久化图的状态(例如,作为聊天记忆),用于单个线程(例如,单个对话)。

存储 Optional[BaseStore]

一个可选的存储对象。这用于在多个线程(例如,多个对话/用户)之间持久化数据。

interrupt_before Optional[list[str]]

一个可选的节点名称列表,用于在这些节点之前中断。应为以下之一:“agent”、“tools”。如果您想在执行操作之前添加用户确认或其他中断,这会很有用。

interrupt_after Optional[list[str]]

一个可选的节点名称列表,用于在这些节点之后中断。应为以下之一:“agent”、“tools”。如果您想直接返回或对输出执行额外处理,这会很有用。

调试 布尔值

指示是否启用调试模式的标志。

False
版本 Literal['v1', 'v2']

确定要创建的图的版本。可以是以下之一

  • "v1":工具节点处理单个消息。消息中的所有工具调用都在工具节点内并行执行。
  • "v2":工具节点处理工具调用。工具调用通过 Send API 分布到多个工具节点实例中。
'v2'
名称 Optional[str]

CompiledStateGraph 的可选名称。当将 ReAct 代理图作为子图节点添加到另一个图时,此名称将自动使用——这对于构建多代理系统特别有用。

返回

类型 描述
CompiledGraph

一个编译后的 LangChain 可运行对象,可用于聊天交互。

“agent”节点用消息列表(应用提示后)调用语言模型。如果结果 AIMessage 包含 tool_calls,则图将调用 “tools”。“tools”节点执行工具(每个 tool_call 对应一个工具),并将响应作为 ToolMessage 对象添加到消息列表中。然后代理节点再次调用语言模型。这个过程重复,直到响应中不再存在 tool_calls。然后代理返回完整的消息列表,作为一个包含键“messages”的字典。

    sequenceDiagram
        participant U as User
        participant A as LLM
        participant T as Tools
        U->>A: Initial input
        Note over A: Prompt + LLM
        loop while tool_calls present
            A->>T: Execute tools
            T-->>A: ToolMessage for each tool_calls
        end
        A->>U: Return final state
示例
from langgraph.prebuilt import create_react_agent

def check_weather(location: str) -> str:
    '''Return the weather forecast for the specified location.'''
    return f"It's always sunny in {location}"

graph = create_react_agent(
    "anthropic:claude-3-7-sonnet-latest",
    tools=[check_weather],
    prompt="You are a helpful assistant",
)
inputs = {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
for chunk in graph.stream(inputs, stream_mode="updates"):
    print(chunk)

ToolNode

基类: RunnableCallable

一个运行最后 AIMessage 中调用的工具的节点。

它可以在 StateGraph 中使用“messages”状态键(或通过 ToolNode 的“messages_key”传递的自定义键),也可以在 MessageGraph 中使用。如果请求了多个工具调用,它们将并行运行。输出将是一个 ToolMessages 列表,每个工具调用对应一个。

工具调用也可以直接作为 ToolCall 字典列表传递。

参数

名称 类型 描述 默认值
工具 Sequence[Union[BaseTool, Callable]]

ToolNode 可以调用的工具序列。

必需
名称 str

图中的 ToolNode 名称。默认为“tools”。

'tools'
标签 Optional[list[str]]

与节点关联的可选标签。默认为None。

handle_tool_errors Union[bool, str, Callable[..., str], tuple[type[Exception], ...]]

如何处理节点内部工具引发的工具错误。默认为True。必须是以下之一

  • True:所有错误都将被捕获,并返回带有默认错误消息 (TOOL_CALL_ERROR_TEMPLATE) 的 ToolMessage。
  • str:所有错误都将被捕获,并返回带有 'handle_tool_errors' 字符串值的 ToolMessage。
  • tuple[type[Exception], ...]: 元组中的异常将被捕获,并返回带有默认错误消息 (TOOL_CALL_ERROR_TEMPLATE) 的 ToolMessage。
  • Callable[..., str]:可调用对象签名中的异常将被捕获,并返回带有 'handle_tool_errors' 可调用对象结果字符串值的 ToolMessage。
  • False:工具引发的错误都不会被捕获
True
messages_key str

输入中包含消息列表的状态键。ToolNode 的输出也将使用相同的键。默认为“messages”。

'messages'

ToolNode 大致类似于

tools_by_name = {tool.name: tool for tool in tools}
def tool_node(state: dict):
    result = []
    for tool_call in state["messages"][-1].tool_calls:
        tool = tools_by_name[tool_call["name"]]
        observation = tool.invoke(tool_call["args"])
        result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"]))
    return {"messages": result}

工具调用也可以直接传递给 ToolNode。这在使用 Send API 时很有用,例如在条件边缘中

def example_conditional_edge(state: dict) -> List[Send]:
    tool_calls = state["messages"][-1].tool_calls
    # If tools rely on state or store variables (whose values are not generated
    # directly by a model), you can inject them into the tool calls.
    tool_calls = [
        tool_node.inject_tool_args(call, state, store)
        for call in last_message.tool_calls
    ]
    return [Send("tools", [tool_call]) for tool_call in tool_calls]
重要
  • 输入状态可以是以下之一
    • 一个包含消息列表的字典,键为 messages。
    • 消息列表。
    • 工具调用列表。
  • 如果对消息列表进行操作,最后一条消息必须是包含 tool_callsAIMessage

方法

名称 描述
inject_tool_args

将状态和存储注入工具调用。

inject_tool_args

inject_tool_args(
    tool_call: ToolCall,
    input: Union[
        list[AnyMessage], dict[str, Any], BaseModel
    ],
    store: Optional[BaseStore],
) -> ToolCall

将状态和存储注入工具调用。

带有 InjectedStateInjectedStore 类型注释的工具参数在工具模式中用于生成目的时会被忽略。此方法将它们注入工具调用中以进行工具调用。

参数

名称 类型 描述 默认值
工具调用 ToolCall

要注入状态和存储的工具调用。

必需
输入 Union[list[AnyMessage], dict[str, Any], BaseModel]

要注入的输入状态。

必需
存储 Optional[BaseStore]

要注入的存储。

必需

返回

名称 类型 描述
ToolCall ToolCall

已注入状态和存储的工具调用。

名称 描述
InjectedState

工具参数的注释,用于填充图状态。

InjectedStore

用于工具参数的注释,旨在用 LangGraph 存储填充。

函数

名称 描述
tools_condition

在 conditional_edge 中使用,如果最后一条消息是工具调用,则路由到 ToolNode。

InjectedState

基类: InjectedToolArg

工具参数的注释,用于填充图状态。

任何用 InjectedState 注释的工具参数都将对工具调用模型隐藏,这样模型就不会尝试生成该参数。如果使用 ToolNode,则会将适当的图状态字段自动注入到模型生成的工具参数中。

参数

名称 类型 描述 默认值
字段 Optional[str]

要插入的状态键。如果为 None,则预期传递整个状态。

示例
from typing import List
from typing_extensions import Annotated, TypedDict

from langchain_core.messages import BaseMessage, AIMessage
from langchain_core.tools import tool

from langgraph.prebuilt import InjectedState, ToolNode


class AgentState(TypedDict):
    messages: List[BaseMessage]
    foo: str

@tool
def state_tool(x: int, state: Annotated[dict, InjectedState]) -> str:
    '''Do something with state.'''
    if len(state["messages"]) > 2:
        return state["foo"] + str(x)
    else:
        return "not enough messages"

@tool
def foo_tool(x: int, foo: Annotated[str, InjectedState("foo")]) -> str:
    '''Do something else with state.'''
    return foo + str(x + 1)

node = ToolNode([state_tool, foo_tool])

tool_call1 = {"name": "state_tool", "args": {"x": 1}, "id": "1", "type": "tool_call"}
tool_call2 = {"name": "foo_tool", "args": {"x": 1}, "id": "2", "type": "tool_call"}
state = {
    "messages": [AIMessage("", tool_calls=[tool_call1, tool_call2])],
    "foo": "bar",
}
node.invoke(state)
[
    ToolMessage(content='not enough messages', name='state_tool', tool_call_id='1'),
    ToolMessage(content='bar2', name='foo_tool', tool_call_id='2')
]

InjectedStore

基类: InjectedToolArg

用于工具参数的注释,旨在用 LangGraph 存储填充。

任何用 InjectedStore 注释的工具参数都将对工具调用模型隐藏,这样模型就不会尝试生成该参数。如果使用 ToolNode,则会将适当的存储字段自动注入到模型生成的工具参数中。注意:如果图是用存储对象编译的,那么在使用 ToolNode 时,存储将自动传播到带有 InjectedStore 参数的工具。

警告

InjectedStore 注释要求 langchain-core >= 0.3.8

示例
from typing import Any
from typing_extensions import Annotated

from langchain_core.messages import AIMessage
from langchain_core.tools import tool

from langgraph.store.memory import InMemoryStore
from langgraph.prebuilt import InjectedStore, ToolNode

store = InMemoryStore()
store.put(("values",), "foo", {"bar": 2})

@tool
def store_tool(x: int, my_store: Annotated[Any, InjectedStore()]) -> str:
    '''Do something with store.'''
    stored_value = my_store.get(("values",), "foo").value["bar"]
    return stored_value + x

node = ToolNode([store_tool])

tool_call = {"name": "store_tool", "args": {"x": 1}, "id": "1", "type": "tool_call"}
state = {
    "messages": [AIMessage("", tool_calls=[tool_call])],
}

node.invoke(state, store=store)
{
    "messages": [
        ToolMessage(content='3', name='store_tool', tool_call_id='1'),
    ]
}

tools_condition

tools_condition(
    state: Union[
        list[AnyMessage], dict[str, Any], BaseModel
    ],
    messages_key: str = "messages",
) -> Literal["tools", "__end__"]

在 conditional_edge 中使用,如果最后一条消息是工具调用,则路由到 ToolNode。

具有工具调用。否则,路由到末尾。

参数

名称 类型 描述 默认值
状态 Union[list[AnyMessage], dict[str, Any], BaseModel]

要检查工具调用的状态。必须有消息列表 (MessageGraph) 或有“messages”键 (StateGraph)。

必需

返回

类型 描述
Literal['tools', '__end__']

要路由到的下一个节点。

示例

使用工具创建自定义的 ReAct 风格代理。

>>> from langchain_anthropic import ChatAnthropic
>>> from langchain_core.tools import tool
...
>>> from langgraph.graph import StateGraph
>>> from langgraph.prebuilt import ToolNode, tools_condition
>>> from langgraph.graph.message import add_messages
...
>>> from typing import Annotated
>>> from typing_extensions import TypedDict
...
>>> @tool
>>> def divide(a: float, b: float) -> int:
...     """Return a / b."""
...     return a / b
...
>>> llm = ChatAnthropic(model="claude-3-haiku-20240307")
>>> tools = [divide]
...
>>> class State(TypedDict):
...     messages: Annotated[list, add_messages]
>>>
>>> graph_builder = StateGraph(State)
>>> graph_builder.add_node("tools", ToolNode(tools))
>>> graph_builder.add_node("chatbot", lambda state: {"messages":llm.bind_tools(tools).invoke(state['messages'])})
>>> graph_builder.add_edge("tools", "chatbot")
>>> graph_builder.add_conditional_edges(
...     "chatbot", tools_condition
... )
>>> graph_builder.set_entry_point("chatbot")
>>> graph = graph_builder.compile()
>>> graph.invoke({"messages": {"role": "user", "content": "What's 329993 divided by 13662?"}})

ValidationNode

基类: RunnableCallable

一个验证上次 AIMessage 中所有工具请求的节点。

它可以在 StateGraph 中与“messages”键一起使用,也可以在 MessageGraph 中使用。

注意

此节点实际上不运行工具,它只验证工具调用,这对于提取和其他用例很有用,在这些用例中,您需要生成符合复杂模式的结构化输出,而不会丢失原始消息和工具 ID(用于多轮对话)。

参数

名称 类型 描述 默认值
模式 Sequence[Union[BaseTool, Type[BaseModel], Callable]]

用于验证工具调用的模式列表。它们可以是以下任何一种: - Pydantic BaseModel 类 - BaseTool 实例(将使用 args_schema) - 函数(将根据函数签名创建模式)

必需
format_error Optional[Callable[[BaseException, ToolCall, Type[BaseModel]], str]]

一个函数,它接受一个异常、一个 ToolCall 和一个模式,并返回一个格式化的错误字符串。默认情况下,它返回异常的 repr 和一条在修复验证错误后进行响应的消息。

名称 str

节点的名称。

'validation'
标签 Optional[list[str]]

要添加到节点的标签列表。

返回

类型 描述
Union[Dict[str, List[ToolMessage]], Sequence[ToolMessage]]

包含验证内容或错误消息的 ToolMessages 列表。

示例
重新提示模型以生成有效响应的示例用法
from typing import Literal, Annotated
from typing_extensions import TypedDict

from langchain_anthropic import ChatAnthropic
from pydantic import BaseModel, field_validator

from langgraph.graph import END, START, StateGraph
from langgraph.prebuilt import ValidationNode
from langgraph.graph.message import add_messages

class SelectNumber(BaseModel):
    a: int

    @field_validator("a")
    def a_must_be_meaningful(cls, v):
        if v != 37:
            raise ValueError("Only 37 is allowed")
        return v

builder = StateGraph(Annotated[list, add_messages])
llm = ChatAnthropic(model="claude-3-5-haiku-latest").bind_tools([SelectNumber])
builder.add_node("model", llm)
builder.add_node("validation", ValidationNode([SelectNumber]))
builder.add_edge(START, "model")

def should_validate(state: list) -> Literal["validation", "__end__"]:
    if state[-1].tool_calls:
        return "validation"
    return END

builder.add_conditional_edges("model", should_validate)

def should_reprompt(state: list) -> Literal["model", "__end__"]:
    for msg in state[::-1]:
        # None of the tool calls were errors
        if msg.type == "ai":
            return END
        if msg.additional_kwargs.get("is_error"):
            return "model"
    return END

builder.add_conditional_edges("validation", should_reprompt)

graph = builder.compile()
res = graph.invoke(("user", "Select a number, any number"))
# Show the retry logic
for msg in res:
    msg.pretty_print()

名称 描述
HumanInterruptConfig

定义人类中断允许哪些操作的配置。

ActionRequest

表示图执行中对人类操作的请求。

HumanInterrupt

表示由图触发的需要人工干预的中断。

HumanResponse

人类对中断提供的响应,在图执行恢复时返回。

HumanInterruptConfig

基类: TypedDict

定义人类中断允许哪些操作的配置。

这控制了当图暂停等待人类输入时可用的交互选项。

属性

名称 类型 描述
allow_ignore 布尔值

人类是否可以选择忽略/跳过当前步骤

allow_respond 布尔值

人类是否可以提供文本响应/反馈

allow_edit 布尔值

人类是否可以编辑提供的内容/状态

allow_accept 布尔值

人类是否可以接受/批准当前状态

ActionRequest

基类: TypedDict

表示图执行中对人类操作的请求。

包含操作类型和操作所需的任何相关参数。

属性

名称 类型 描述
操作 str

请求的操作类型或名称(例如,“批准 XYZ 操作”)

参数 字典

操作所需的参数键值对

HumanInterrupt

基类: TypedDict

表示由图触发的需要人工干预的中断。

当执行因人工输入而暂停时,此项会传递给 interrupt 函数。

属性

名称 类型 描述
action_request ActionRequest

向人类请求的具体行动

配置 HumanInterruptConfig

定义允许哪些操作的配置

描述 Optional[str]

对所需输入的可选详细描述

示例
# Extract a tool call from the state and create an interrupt request
request = HumanInterrupt(
    action_request=ActionRequest(
        action="run_command",  # The action being requested
        args={"command": "ls", "args": ["-l"]}  # Arguments for the action
    ),
    config=HumanInterruptConfig(
        allow_ignore=True,    # Allow skipping this step
        allow_respond=True,   # Allow text feedback
        allow_edit=False,     # Don't allow editing
        allow_accept=True     # Allow direct acceptance
    ),
    description="Please review the command before execution"
)
# Send the interrupt request and get the response
response = interrupt([request])[0]

HumanResponse

基类: TypedDict

人类对中断提供的响应,在图执行恢复时返回。

属性

名称 类型 描述
类型 Literal['accept', 'ignore', 'response', 'edit']

响应类型: - "accept":不作任何更改地批准当前状态 - "ignore":跳过/忽略当前步骤 - "response":提供文本反馈或指令 - "edit":修改当前状态/内容

参数 Literal['accept', 'ignore', 'response', 'edit']

响应负载: - None:用于忽略/接受操作 - str:用于文本响应 - ActionRequest:用于带有更新内容的编辑操作