跳转到内容

Deep Agents 参考

PyPI - Version PyPI - License PyPI - Downloads

欢迎来到 Deep Agents 参考文档！

正在施工中

此页面仍在建设中，感谢您的耐心等待，我们将继续扩充和改进内容。

deepagents

DeepAgents 包。

函数 描述
create_deep_agent

创建一个 deep agent。

FilesystemMiddleware

基类：AgentMiddleware

为 agent 提供文件系统工具的中间件。

此中间件向 agent 添加了六个文件系统工具：ls、read_file、write_file、edit_file、glob 和 grep。文件可以使用任何实现了 BackendProtocol 的后端进行存储。

参数 描述
backend

用于文件存储的后端。如果未提供，则默认为 StateBackend（在 agent 状态中的临时存储）。对于持久化存储或混合设置，请使用带有自定义路由的 CompositeBackend。

类型： BACKEND_TYPES | None 默认值： None

system_prompt

可选的自定义系统提示覆盖。

类型: str | None 默认值: None

custom_tool_descriptions

可选的自定义工具描述覆盖。

类型： dict[str, str] | None 默认值： None

tool_token_limit_before_evict

可选的 token 限制，在将工具结果移出到文件系统之前触发。

类型： int | None 默认值： 20000

示例 
from deepagents.middleware.filesystem import FilesystemMiddleware
from deepagents.memory.backends import StateBackend, StoreBackend, CompositeBackend
from langchain.agents import create_agent

# Ephemeral storage only (default)
agent = create_agent(middleware=[FilesystemMiddleware()])

# With hybrid storage (ephemeral + persistent /memories/)
backend = CompositeBackend(default=StateBackend(), routes={"/memories/": StoreBackend()})
agent = create_agent(middleware=[FilesystemMiddleware(memory_backend=backend)])
方法 描述
before_agent

在 agent 执行开始前运行的逻辑。
abefore_agent

在 agent 执行开始前运行的异步逻辑。
before_model

在调用模型前运行的逻辑。
abefore_model

在调用模型前运行的异步逻辑。
after_model

在调用模型后运行的逻辑。
aafter_model

在调用模型后运行的异步逻辑。
after_agent

在 agent 执行完成后运行的逻辑。
aafter_agent

在 agent 执行完成后运行的异步逻辑。
__init__

初始化文件系统中间件。
wrap_model_call

更新系统提示，以包含有关使用文件系统的说明。
awrap_model_call

（异步）更新系统提示，以包含有关使用文件系统的说明。
wrap_tool_call

检查工具调用结果的大小，如果太大则移出到文件系统。
awrap_tool_call

（异步）检查工具调用结果的大小，如果太大则移出到文件系统。

name 属性 

name: str

中间件实例的名称。

默认为类名，但可以为自定义命名进行重写。

state_schema 类属性 实例属性 

state_schema = FilesystemState

传递给中间件节点的状态的模式。

tools 实例属性 

tools = _get_filesystem_tools(backend, custom_tool_descriptions)

由中间件注册的附加工具。

before_agent 

before_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行开始前运行的逻辑。

abefore_agent 异步 

abefore_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行开始前运行的异步逻辑。

before_model 

before_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型前运行的逻辑。

abefore_model 异步 

abefore_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型前运行的异步逻辑。

after_model 

after_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型后运行的逻辑。

aafter_model 异步 

aafter_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型后运行的异步逻辑。

after_agent 

after_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行完成后运行的逻辑。

aafter_agent 异步 

aafter_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行完成后运行的异步逻辑。

__init__ 

__init__(
    *,
    backend: BACKEND_TYPES | None = None,
    system_prompt: str | None = None,
    custom_tool_descriptions: dict[str, str] | None = None,
    tool_token_limit_before_evict: int | None = 20000,
) -> None

初始化文件系统中间件。

参数 描述
backend

用于文件存储的后端，或一个工厂可调用对象。如果未提供，则默认为 StateBackend。

类型： BACKEND_TYPES | None 默认值： None

system_prompt

可选的自定义系统提示覆盖。

类型: str | None 默认值: None

custom_tool_descriptions

可选的自定义工具描述覆盖。

类型： dict[str, str] | None 默认值： None

tool_token_limit_before_evict

可选的 token 限制，在将工具结果移出到文件系统之前触发。

类型： int | None 默认值： 20000

wrap_model_call 

wrap_model_call(
    request: ModelRequest, handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse

更新系统提示，以包含有关使用文件系统的说明。

参数 描述
request

正在处理的模型请求。

类型： ModelRequest

handler

要使用修改后的请求调用的处理函数。

类型： Callable[[ModelRequest], ModelResponse]

返回 描述
ModelResponse

来自处理程序的模型响应。

awrap_model_call 异步 

awrap_model_call(
    request: ModelRequest, handler: Callable[[ModelRequest], Awaitable[ModelResponse]]
) -> ModelResponse

（异步）更新系统提示，以包含有关使用文件系统的说明。

参数 描述
request

正在处理的模型请求。

类型： ModelRequest

handler

要使用修改后的请求调用的处理函数。

类型： Callable[[ModelRequest], Awaitable[ModelResponse]]

返回 描述
ModelResponse

来自处理程序的模型响应。

wrap_tool_call 

wrap_tool_call(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command

检查工具调用结果的大小，如果太大则移出到文件系统。

参数 描述
request

正在处理的工具调用请求。

类型： ToolCallRequest

handler

要使用修改后的请求调用的处理函数。

类型： Callable[[ToolCallRequest], ToolMessage | Command]

返回 描述
ToolMessage | Command

原始的 ToolMessage，或一个伪工具消息，其中 ToolResult 在状态中。

awrap_tool_call 异步 

awrap_tool_call(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command

（异步）检查工具调用结果的大小，如果太大则移出到文件系统。

参数 描述
request

正在处理的工具调用请求。

类型： ToolCallRequest

handler

要使用修改后的请求调用的处理函数。

类型： Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]]

返回 描述
ToolMessage | Command

原始的 ToolMessage，或一个伪工具消息，其中 ToolResult 在状态中。

CompiledSubAgent

基类：TypedDict

一个预编译的 agent 规范。

name 实例属性 

name: str

agent 的名称。

description 实例属性 

description: str

agent 的描述。

runnable 实例属性 

runnable: Runnable

用于 agent 的 Runnable。

SubAgent

基类：TypedDict

agent 的规范。

在指定自定义 agent 时，将首先应用来自 `SubAgentMiddleware` 的 `default_middleware`，然后是此规范中指定的任何 `middleware`。要仅使用自定义中间件而不使用默认中间件，请将 `default_middleware=[]` 传递给 `SubAgentMiddleware`。

name 实例属性 

name: str

agent 的名称。

description 实例属性 

description: str

agent 的描述。

system_prompt 实例属性 

system_prompt: str

用于 agent 的系统提示。

tools 实例属性 

tools: Sequence[BaseTool | Callable | dict[str, Any]]

用于 agent 的工具。

model 实例属性 

model: NotRequired[str | BaseChatModel]

agent 的模型。默认为 `default_model`。

middleware 实例属性 

middleware: NotRequired[list[AgentMiddleware]]

在 `default_middleware` 之后附加的额外中间件。

interrupt_on 实例属性 

interrupt_on: NotRequired[dict[str, bool | InterruptOnConfig]]

用于 agent 的工具配置。

SubAgentMiddleware

基类：AgentMiddleware

通过一个 `task` 工具为 agent 提供子 agent 的中间件。

此中间件向 agent 添加一个 `task` 工具，可用于调用子 agent。子 agent 对于处理需要多个步骤的复杂任务，或需要大量上下文来解决的任务非常有用。

子 agent 的一个主要好处是它们可以处理多步任务，然后向主 agent 返回一个清晰、简洁的响应。

子 agent 对于需要更窄范围工具和焦点的不同专业领域也很有用。

此中间件带有一个默认的通用子 agent，可用于处理与主 agent 相同的任务，但具有隔离的上下文。

参数 描述
default_model

用于子 agent 的模型。可以是 LanguageModelLike 或用于 init_chat_model 的字典。

类型： str | BaseChatModel

default_tools

用于默认通用子 agent 的工具。

类型： Sequence[BaseTool | Callable | dict[str, Any]] | None 默认值： None

default_middleware

应用于所有子 agent 的默认中间件。如果为 `None`（默认值），则不应用任何默认中间件。传递一个列表以指定自定义中间件。

类型： list[AgentMiddleware] | None 默认值： None

default_interrupt_on

用于默认通用子 agent 的工具配置。这些配置也是任何未指定其自己的工具配置的子 agent 的备用配置。

类型： dict[str, bool | InterruptOnConfig] | None 默认值： None

subagents

提供给 agent 的附加子 agent 列表。

类型： list[SubAgent | CompiledSubAgent] | None 默认值： None

system_prompt

完整的系统提示覆盖。当提供时，完全替换 agent 的系统提示。

类型： str | None 默认值： TASK_SYSTEM_PROMPT

general_purpose_agent

是否包含通用 agent。默认为 `True`。

类型: bool 默认值: True

task_description

task 工具的自定义描述。如果为 `None`，则使用默认的描述模板。

类型: str | None 默认值: None

示例 
from langchain.agents.middleware.subagents import SubAgentMiddleware
from langchain.agents import create_agent

# Basic usage with defaults (no default middleware)
agent = create_agent(
    "openai:gpt-4o",
    middleware=[
        SubAgentMiddleware(
            default_model="openai:gpt-4o",
            subagents=[],
        )
    ],
)

# Add custom middleware to subagents
agent = create_agent(
    "openai:gpt-4o",
    middleware=[
        SubAgentMiddleware(
            default_model="openai:gpt-4o",
            default_middleware=[TodoListMiddleware()],
            subagents=[],
        )
    ],
)
方法 描述
before_agent

在 agent 执行开始前运行的逻辑。
abefore_agent

在 agent 执行开始前运行的异步逻辑。
before_model

在调用模型前运行的逻辑。
abefore_model

在调用模型前运行的异步逻辑。
after_model

在调用模型后运行的逻辑。
aafter_model

在调用模型后运行的异步逻辑。
after_agent

在 agent 执行完成后运行的逻辑。
aafter_agent

在 agent 执行完成后运行的异步逻辑。
wrap_tool_call

拦截工具执行以进行重试、监视或修改。
awrap_tool_call

通过处理程序回调拦截和控制异步工具执行。
__init__

初始化 SubAgentMiddleware。
wrap_model_call

更新系统提示以包含有关使用子 agent 的说明。
awrap_model_call

（异步）更新系统提示以包含有关使用子 agent 的说明。

state_schema 类属性 实例属性 

state_schema: type[StateT] = cast('type[StateT]', AgentState)

传递给中间件节点的状态的模式。

name 属性 

name: str

中间件实例的名称。

默认为类名，但可以为自定义命名进行重写。

tools 实例属性 

tools = [task_tool]

由中间件注册的附加工具。

before_agent 

before_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行开始前运行的逻辑。

abefore_agent 异步 

abefore_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行开始前运行的异步逻辑。

before_model 

before_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型前运行的逻辑。

abefore_model 异步 

abefore_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型前运行的异步逻辑。

after_model 

after_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型后运行的逻辑。

aafter_model 异步 

aafter_model(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在调用模型后运行的异步逻辑。

after_agent 

after_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行完成后运行的逻辑。

aafter_agent 异步 

aafter_agent(state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None

在 agent 执行完成后运行的异步逻辑。

wrap_tool_call 

wrap_tool_call(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command

拦截工具执行以进行重试、监视或修改。

多个中间件会自动组合（先定义的 = 最外层）。除非在 `ToolNode` 上配置了 `handle_tool_errors`，否则异常会传播。

参数 描述
request

带有调用 `dict`、`BaseTool`、状态和运行时的工具调用请求。通过 `request.state` 访问状态，通过 `request.runtime` 访问运行时。

类型： ToolCallRequest

handler

用于执行工具的可调用对象（可以多次调用）。

类型： Callable[[ToolCallRequest], ToolMessage | Command]

返回 描述
ToolMessage | Command

`ToolMessage` 或 `Command`（最终结果）。

处理程序可调用对象可以为重试逻辑多次调用。对处理程序的每次调用都是独立且无状态的。

示例

执行前修改请求

def wrap_tool_call(self, request, handler):
    request.tool_call["args"]["value"] *= 2
    return handler(request)

错误时重试（多次调用处理程序）

def wrap_tool_call(self, request, handler):
    for attempt in range(3):
        try:
            result = handler(request)
            if is_valid(result):
                return result
        except Exception:
            if attempt == 2:
                raise
    return result

根据响应条件性重试

def wrap_tool_call(self, request, handler):
    for attempt in range(3):
        result = handler(request)
        if isinstance(result, ToolMessage) and result.status != "error":
            return result
        if attempt < 2:
            continue
        return result

awrap_tool_call 异步 

awrap_tool_call(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command

通过处理程序回调拦截和控制异步工具执行。

处理程序回调执行工具调用并返回一个 `ToolMessage` 或 `Command`。中间件可以为重试逻辑多次调用处理程序，跳过调用它以进行短路，或修改请求/响应。多个中间件组合，列表中的第一个作为最外层。

参数 描述
request

带有调用 `dict`、`BaseTool`、状态和运行时的工具调用请求。通过 `request.state` 访问状态，通过 `request.runtime` 访问运行时。

类型： ToolCallRequest

handler

用于执行工具并返回 `ToolMessage` 或 `Command` 的异步可调用对象。调用它以执行工具。可以为重试逻辑多次调用。可以跳过调用它以进行短路。

类型： Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]]

返回 描述
ToolMessage | Command

`ToolMessage` 或 `Command`（最终结果）。

处理程序可调用对象可以为重试逻辑多次调用。对处理程序的每次调用都是独立且无状态的。

示例

错误时异步重试

async def awrap_tool_call(self, request, handler):
    for attempt in range(3):
        try:
            result = await handler(request)
            if is_valid(result):
                return result
        except Exception:
            if attempt == 2:
                raise
    return result


async def awrap_tool_call(self, request, handler):
    if cached := await get_cache_async(request):
        return ToolMessage(content=cached, tool_call_id=request.tool_call["id"])
    result = await handler(request)
    await save_cache_async(request, result)
    return result

__init__ 

__init__(
    *,
    default_model: str | BaseChatModel,
    default_tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
    default_middleware: list[AgentMiddleware] | None = None,
    default_interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
    subagents: list[SubAgent | CompiledSubAgent] | None = None,
    system_prompt: str | None = TASK_SYSTEM_PROMPT,
    general_purpose_agent: bool = True,
    task_description: str | None = None,
) -> None

初始化 SubAgentMiddleware。

wrap_model_call 

wrap_model_call(
    request: ModelRequest, handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse

更新系统提示以包含有关使用子 agent 的说明。

awrap_model_call 异步 

awrap_model_call(
    request: ModelRequest, handler: Callable[[ModelRequest], Awaitable[ModelResponse]]
) -> ModelResponse

（异步）更新系统提示以包含有关使用子 agent 的说明。

create_deep_agent 

create_deep_agent(
    model: str | BaseChatModel | None = None,
    tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
    *,
    system_prompt: str | None = None,
    middleware: Sequence[AgentMiddleware] = (),
    subagents: list[SubAgent | CompiledSubAgent] | None = None,
    response_format: ResponseFormat | None = None,
    context_schema: type[Any] | None = None,
    checkpointer: Checkpointer | None = None,
    store: BaseStore | None = None,
    backend: BackendProtocol | BackendFactory | None = None,
    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
    debug: bool = False,
    name: str | None = None,
    cache: BaseCache | None = None,
) -> CompiledStateGraph

创建一个 deep agent。

默认情况下，此 agent 将有权访问一个写入待办事项的工具 (write_todos)，六个文件编辑工具：write_file、ls、read_file、edit_file、glob_search、grep_search，以及一个调用子 agent 的工具。

参数 描述
model

要使用的模型。默认为 Claude Sonnet 4。

类型： str | BaseChatModel | None 默认值： None

工具

agent 应有权访问的工具。

类型： Sequence[BaseTool | Callable | dict[str, Any]] | None 默认值： None

system_prompt

agent 应有的附加说明。将包含在系统提示中。

类型: str | None 默认值: None

middleware

在标准中间件之后应用的附加中间件。

类型： Sequence[AgentMiddleware] 默认值： ()

subagents

要使用的子 agent。每个子 agent 应为一个字典，包含以下键： - `name` - `description`（由主 agent 用于决定是否调用子 agent） - `prompt`（在子 agent 中用作系统提示） - （可选）`tools` - （可选）`model`（LanguageModelLike 实例或 dict 设置） - （可选）`middleware`（AgentMiddleware 列表）

类型： list[SubAgent | CompiledSubAgent] | None 默认值： None

response_format

用于 agent 的结构化输出响应格式。

类型： ResponseFormat | None 默认值： None

context_schema

deep agent 的模式。

类型： type[Any] | None 默认值： None

checkpointer

可选的检查点，用于在运行之间持久化 agent 状态。

类型： Checkpointer | None 默认值： None

store

可选的持久化存储库（如果后端使用 StoreBackend，则为必需）。

类型： BaseStore | None 默认值： None

backend

可选的文件存储后端。传递一个 Backend 实例或一个可调用的工厂，如 `lambda rt: StateBackend(rt)`。

类型： BackendProtocol | BackendFactory | None 默认值： None

interrupt_on

可选的 Dict[str, bool | InterruptOnConfig]，将工具名称映射到中断配置。

类型： dict[str, bool | InterruptOnConfig] | None 默认值： None

debug

是否启用调试模式。传递给 create_agent。

类型： bool 默认值： False

name

agent 的名称。传递给 create_agent。

类型: str | None 默认值: None

cache

用于 agent 的缓存。传递给 create_agent。

类型： BaseCache | None 默认值： None

返回 描述
CompiledStateGraph

一个配置好的 deep agent。
© . This site is unofficial and not affiliated with LangChain, Inc.