Deep Agents 中的上下文工程

控制你的深度智能体可以访问哪些上下文，以及如何在长时间运行的任务中管理这些上下文

上下文工程是指以正确的格式提供正确的信息和工具，使你的深度智能体能够可靠地完成任务。

深度智能体可以访问多种类型的上下文。有些来源在启动时提供给智能体；其他来源则在运行时才可用，例如用户输入。深度智能体包含内置的机制，用于在长时间运行的会话中管理上下文。

本页概述了你的深度智能体可以访问和管理的不同种类的上下文。

TIP

刚接触上下文工程？有关不同类型的上下文以及何时使用它们，请参见概念概览。

上下文的类型

上下文类型	你控制的内容	范围
输入上下文	启动时进入智能体提示词的内容（系统提示词、记忆、技能）	静态，每次运行都应用
运行时上下文	调用时传入的静态配置（用户元数据、API 密钥、连接）	每次运行，会传播到子智能体
上下文压缩	内置的卸载和摘要机制，使上下文保持在窗口限制内	自动，在接近限制时触发
上下文隔离	使用子智能体隔离繁重工作，仅向主智能体返回结果	每个子智能体，在委派时
长期记忆	使用虚拟文件系统跨线程持久化存储	跨对话持久

输入上下文

输入上下文是启动时提供给深度智能体、并成为其系统提示词一部分的信息。最终提示词由多个来源组成：

System prompt

你提供的自定义指令加上内置的智能体指导。

Memory

配置后始终加载的持久化 AGENTS.md 文件。

Skills

在相关时按需加载的能力（渐进式披露）。

Tool prompts

用于内置工具或自定义工具的使用说明。

系统提示词

你的自定义系统提示词会被前置到内置系统提示词之前，后者包含文件系统工具和子智能体的指导。使用它来定义智能体的角色、行为和知识：

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.5",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

system_prompt 参数是静态的，这意味着它不会因调用而改变。对于某些用例，你可能需要动态提示词：例如，告诉模型「你拥有管理员访问权限」还是「你拥有只读访问权限」，或从长期记忆注入诸如「用户偏好简洁的回复」这样的用户偏好。如果你的提示词依赖于上下文或 runtime.store，请使用 @dynamic_prompt 来构建上下文感知的指令。你的中间件可以读取 request.runtime.context 和 request.runtime.store。有关 Deep Agents 技术栈以及添加自定义中间件，请参见自定义。有关示例，请参见 LangChain 上下文工程指南。

当只有工具使用上下文或 runtime.store 时，你不需要中间件；工具会直接接收 ToolRuntime 对象（包括 runtime.context 和 runtime.store）。只有当工具需要与系统提示词的更新一起打包时，才添加中间件。

TIP

要为特定的服务商或模型调整组装后的系统提示词，请使用 harness 配置文件：base_system_prompt 会完全替换基础提示词，而 system_prompt_suffix 会在其后追加内容。

记忆

记忆文件（AGENTS.md）提供始终加载到系统提示词中的持久化上下文。将记忆用于每次对话都适用的项目约定、用户偏好和关键准则：

python

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

python

agent = create_deep_agent(
    model="openai:gpt-5.5",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

python

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

python

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

python

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

python

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

python

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

与技能不同，记忆始终会被注入—没有渐进式披露。请保持记忆尽可能精简，以避免上下文过载；对于详细的工作流和领域特定内容，请使用技能。有关配置细节，请参见记忆。

要生成编码智能体通过 AGENTS.md 发现的仓库 wiki，请参见 OpenWiki。

技能

技能提供按需能力。智能体在启动时读取每个 SKILL.md 的 frontmatter，然后仅在判断技能相关时才加载完整的技能内容。这减少了 token 用量，同时仍能提供专门的工作流：

python

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    skills=["/skills/"],
)

python

agent = create_deep_agent(
    model="openai:gpt-5.5",
    skills=["/skills/"],
)

python

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    skills=["/skills/"],
)

python

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    skills=["/skills/"],
)

python

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    skills=["/skills/"],
)

python

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    skills=["/skills/"],
)

python

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    skills=["/skills/"],
)

让每项技能专注于单个工作流或领域；宽泛或重叠的技能会稀释相关性，并在加载时使上下文变得臃肿。在技能内部，保持主要内容简洁，并将详细的参考资料移入技能文件中引用的单独文件。将始终相关的约定放入记忆。有关编写和配置，请参见技能。

工具提示词

工具提示词是塑造模型如何使用工具的指令。所有工具都会暴露模型在其提示词中看到的元数据—通常是一个模式和一段描述。你通过 tools 参数传入的工具会将这些工具元数据（模式和描述）呈现给模型。深度智能体的内置工具被打包在 Deep Agents 技术栈中，并且通常还会更新系统提示词，为这些工具提供更多指导。

内置工具：添加 harness 能力（文件系统、子智能体以及可选规划）的中间件会自动向系统提示词追加工具特定的指令，从而创建说明如何有效使用这些工具的工具提示词。有关完整列表，请参见自定义：

文件系统提示词：ls、read_file、write_file、edit_file、delete、glob、grep（以及使用沙箱后端时的 execute）的文档
子智能体提示词：使用 task 工具委派工作的指导
人在回路提示词：在指定工具调用处暂停的用法（当设置了 interrupt_on 时）
本地上下文提示词：当前目录和项目信息（仅 CLI）

你提供的工具：通过 tools 参数传入的工具会将其描述（来自工具模式）发送给模型。你还可以添加自定义中间件，它添加工具并追加自己的系统提示词指令。

对于你提供的工具，请确保提供清晰的名称、描述和参数描述。这些会指导模型就何时以及如何使用该工具进行推理。在描述中说明何时使用该工具，并描述每个参数的作用。

python

from langchain.tools import tool

@tool(parse_docstring=True)
def search_orders(
    user_id: str,
    status: str,
    limit: int = 10,
) -> str:
    """Search for user orders by status.

    Use this when the user asks about order history or wants to check
    order status. Always filter by the provided status.

    Args:
        user_id: Unique identifier for the user
        status: Order status: 'pending', 'shipped', or 'delivered'
        limit: Maximum number of results to return
    """
    # Implementation here
    return f"orders for {user_id} with status {status} (limit {limit})"

TIP

要为特定的服务商或模型覆盖内置工具或用户提供工具的描述，请使用 harness 配置文件的 tool_description_overrides（以工具名为键）。

未使用的内置工具仍会在每一轮发送其完整模式。使用 excluded_tools 移除智能体永远不应调用的工具（例如只读智能体上的 write_file 或 execute）。这样可以缩减整个运行的基线提示词大小。这是配置，而不是上下文压缩中的自动卸载或摘要。

参见 Harness 配置文件和不使用默认文件系统工具运行。

有关内置能力，请参见概览；有关直接传入工具，请参见自定义。

完整的系统提示词

深度智能体的系统消息—即模型在运行开始时收到的组装后的系统提示词—由以下部分组成：

自定义 system_prompt（如果提供）
基础智能体提示词
记忆提示词：AGENTS.md + 记忆使用准则（仅在提供了 memory 时）
技能提示词：技能位置 + 带 frontmatter 信息的技能列表 + 用法（仅在提供了技能时）
虚拟文件系统提示词（如适用，包含文件系统 + execute 工具文档）
子智能体提示词：Task 工具用法
用户提供的中间件提示词（如果提供了自定义中间件）
人在回路提示词（当设置了 interrupt_on 时）

运行时上下文

运行时上下文是你在调用智能体时传入的每次运行的配置。它不会自动包含在模型提示词中；只有当工具、中间件或其他逻辑读取它并将其添加到消息或系统提示词中时，模型才会看到它。将运行时上下文用于用户元数据（ID、偏好、角色）、API 密钥、数据库连接、功能标志或你的工具和 harness 所需的其他值。

使用 context_schema 定义该数据的形状：使用 dataclasses.dataclass 或 typing.TypedDict 类。通过 invoke / ainvoke 的 context 参数传入值。有关完整细节，请参见运行时和 LangGraph 运行时上下文。

在工具内部，从注入的 ToolRuntime 中读取上下文：

python

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

python

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

python

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

python

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

python

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

python

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

python

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

运行时上下文会传播到所有子智能体。当子智能体运行时，它会接收与父级相同的运行时上下文。有关每个子智能体的上下文（带命名空间的键），请参见子智能体。

自定义状态模式

NOTE

自定义状态模式需要 deepagents>=0.6.6。

当你的智能体或中间件需要跟踪必须在整个智能体生命周期中持久化、并能经受检查点的数据时，请使用自定义状态模式。自定义状态让你可以：

跟踪整个运行过程中的状态：维护在模型调用和工具调用之间得以保留的计数器、标志或累积值
在工具和中间件之间共享数据：一个工具可以将值写入状态，中间件钩子可以读取它，反之亦然
实现横切关注点：添加速率限制、用量跟踪或审计日志等功能，而无需修改核心智能体逻辑
在调用时传入初始值：在每次运行开始时为状态字段设定初始值，然后让智能体在执行过程中更新它们

当数据必须是智能体可变图状态的一部分、随线程一起做检查点，或可通过 runtime.state 访问时，请使用 state_schema。对于不可变的每次运行输入（例如用户 ID、凭证或功能标志），请优先使用运行时上下文。

自定义状态模式必须继承 DeepAgentState。这会保留 messages 上内置的 DeltaChannel 归约器，从而使检查点的增长随对话变长保持线性。

python

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]

@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    },
)

python

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]

@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    },
)

python

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]

@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    },
)

python

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]

@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    },
)

python

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]

@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    },
)

python

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]

@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    },
)

python

from deepagents import DeepAgentState, create_deep_agent
from langchain.tools import ToolRuntime, tool

class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]

@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    },
)

该模式会与中间件贡献的状态模式合并。当 Deep Agents 为 task 工具编译它们时，传递给 subagents= 的声明式 SubAgent 规格会继承父级的 state_schema。CompiledSubAgent 可运行对象和远程 AsyncSubAgent 规格不会继承它，因为它们的图已经被编译或单独托管。如果这些图需要相同的状态字段，请使用兼容的模式来编译它们。

上下文压缩

每次 create_deep_agent 调用都包含内置的上下文压缩。你无需添加中间件即可让卸载或摘要生效。

长时间运行的任务会产生大量工具输出和很长的对话历史。上下文压缩会缩减智能体工作记忆中信息的规模，同时保留与任务相关的细节。以下技术是内置机制，用于确保传递给 LLM 的上下文始终处于其上下文窗口限制之内：

Offloading

大型工具输入和结果会存储在文件系统中，并被替换为引用。

Summarization

当接近限制时，旧消息会被压缩为 LLM 生成的摘要。

为了在压缩运行之前就缩减每一轮发送的工具 schema，可通过 harness profile（excluded_tools）排除未使用的内置工具。请参阅工具提示词。

卸载

Deep Agents 使用内置文件系统工具自动卸载内容，并按需搜索和检索这些已卸载的内容。当工具调用输入或结果超过 token 阈值（默认 20,000）时，就会发生内容卸载：

工具调用输入超过 20,000 token：文件写入和编辑操作会在智能体的对话历史中留下包含完整文件内容的工具调用。由于这些内容已经持久化到文件系统，它们往往是冗余的。当会话上下文超过模型可用窗口的 85% 时，deep agents 会截断较早的工具调用，将其替换为指向磁盘上文件的指针，从而减小活动上下文的大小。
工具调用结果超过 20,000 token：发生这种情况时，deep agent 会将响应卸载到已配置的后端，并用文件路径引用和前 10 行的预览来替代它。此后智能体可以按需重新读取或搜索这些内容。

NOTE

内置上下文压缩不会调整图像尺寸、降低图像分辨率或生成视觉嵌入。有关多模态输入、工具输出，以及压缩如何与媒体交互，请参阅多模态。

摘要

每次 create_deep_agent 调用都会在裸栈中包含 SummarizationMiddleware。当上下文大小越过模型的上下文窗口限制（例如 max_input_tokens 的 85%），并且没有更多可供卸载的上下文时，deep agent 会自动对消息历史进行摘要。

该过程包含两个组成部分：

上下文内摘要：LLM 生成对话的结构化摘要，包含会话意图、创建的产物以及后续步骤——它会取代智能体工作记忆中的完整对话历史。
文件系统保留：原始对话消息的文本呈现会被写入文件系统，作为权威记录。

这种双重方式确保智能体始终了解其目标和进展（通过摘要），同时保留在需要时恢复文本细节的能力（通过文件系统搜索）。

配置：

在模型的 model profile 达到 max_input_tokens 的 85% 时触发
保留 10% 的 token 作为近期上下文
如果 model profile 不可用，则回退到 170,000 token 触发 / 保留 6 条消息
如果任何模型调用引发标准的 ContextOverflowError，deep agent 会立即回退到摘要，并使用摘要 + 最近保留的消息重试
较早的消息由模型进行摘要

TIP

来自智能体的流式传输 token通常包含摘要步骤生成的 token。你可以使用这些 token 关联的元数据将其过滤掉：

python

for token, metadata in agent.stream(
    {"messages": [...]},
    stream_mode="messages",
):
    if metadata.get("lc_source") == "summarization":  
        continue
    else:
        ...

按需压缩工具

默认情况下，当达到上下文阈值时，会自动运行摘要。另外，你可以给智能体提供一个 compact_conversation 工具，使其能够按需触发压缩，例如在任务之间，而不必等待达到 85% 的阈值。

通过在 create_deep_agent 上使用 middleware 参数传入 create_summarization_tool_middleware 来启用该工具。自定义 middleware 会被插入到 Deep Agents 栈中 PatchToolCallsMiddleware 之后：

python

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend  # if using default backend

model = "google_genai:gemini-3.6-flash"
agent = create_deep_agent(
    model=model,
    middleware=[  
        create_summarization_tool_middleware(model, backend),  
    ],  
)

python

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend  # if using default backend

model = "openai:gpt-5.5"
agent = create_deep_agent(
    model=model,
    middleware=[  
        create_summarization_tool_middleware(model, backend),  
    ],  
)

python

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend  # if using default backend

model = "anthropic:claude-sonnet-5"
agent = create_deep_agent(
    model=model,
    middleware=[  
        create_summarization_tool_middleware(model, backend),  
    ],  
)

python

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend  # if using default backend

model = "openrouter:z-ai/glm-5.2"
agent = create_deep_agent(
    model=model,
    middleware=[  
        create_summarization_tool_middleware(model, backend),  
    ],  
)

python

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend  # if using default backend

model = "fireworks:accounts/fireworks/models/glm-5p2"
agent = create_deep_agent(
    model=model,
    middleware=[  
        create_summarization_tool_middleware(model, backend),  
    ],  
)

python

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend  # if using default backend

model = "baseten:zai-org/GLM-5.2"
agent = create_deep_agent(
    model=model,
    middleware=[  
        create_summarization_tool_middleware(model, backend),  
    ],  
)

python

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend  # if using default backend

model = "ollama:north-mini-code-1.0"
agent = create_deep_agent(
    model=model,
    middleware=[  
        create_summarization_tool_middleware(model, backend),  
    ],  
)

添加压缩工具并不会禁用模型上下文限制达到 85% 时的自动摘要。二者共享同一个摘要引擎和状态。

有关详细信息，请参阅 API 参考中的 SummarizationToolMiddleware 和 create_summarization_tool_middleware。

使用子智能体实现上下文隔离

子智能体解决了上下文膨胀问题。当主智能体使用会产生大量输出的工具（网页搜索、文件读取、数据库查询）时，上下文窗口会很快被填满。子智能体将这项工作隔离起来——主智能体只接收最终结果，而不是产生该结果的数十次工具调用。你还可以将每个子智能体与主智能体分开配置（例如模型、工具、系统提示词和技能）。

工作原理：

主智能体拥有一个 task 工具来委派工作
子智能体在其自身全新的上下文中运行
子智能体自主执行直至完成
子智能体向主智能体返回单份最终报告
主智能体的上下文保持干净

最佳实践：

委派复杂任务：对会让主智能体上下文变得杂乱的多步骤工作使用子智能体。

保持子智能体响应简洁：指示子智能体返回摘要，而不是原始数据：

python

research_subagent = {
    "name": "researcher",
    "description": "Conducts research on a topic",
    "system_prompt": """You are a research assistant.
    IMPORTANT: Return only the essential summary (under 500 words).
    Do NOT include raw search results or detailed tool outputs.""",
    "tools": [web_search],
}

对大型数据使用文件系统：子智能体可以将结果写入文件；主智能体读取其所需的部分。

有关配置，请参阅子智能体；有关运行时上下文传播和按子智能体划分命名空间，请参阅上下文管理。

长期记忆

使用默认文件系统时，你的 deep agent 会将其工作记忆文件存储在智能体状态中，而这些文件仅在单个线程内持久保留。长期记忆使你的 deep agent 能够跨不同线程和对话持久化信息。 deep agents 可以使用长期记忆来存储用户偏好、积累的知识、研究进展，或任何应当超出单次会话而持久保留的信息。

要使用长期记忆，你必须使用一个 CompositeBackend，它会将特定路径（通常是 /memories/）路由到 LangGraph Store，后者提供跨线程的持久化。 CompositeBackend 是一种混合存储系统，其中一些文件会无限期持久保留，而另一些则限定在单个线程范围内。

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    store=store,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model="openai:gpt-5.5",
    store=store,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    store=store,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    store=store,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    store=store,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    store=store,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    store=store,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

你无需用文件预填充 /memories/。你提供后端配置、store 以及系统提示词指令，告诉智能体保存什么以及保存到哪里。例如，你可以提示智能体将偏好存储到 /memories/preferences.txt。该路径初始为空，当用户分享值得记住的信息时，智能体会使用其文件系统工具（write_file、edit_file）按需创建文件。

要在 LangSmith 上部署时预先填充记忆，请使用 Store API。有关设置和用例，请参阅长期记忆。

最佳实践

从正确的输入上下文入手：对始终相关的约定保持记忆最小化；对特定任务能力使用聚焦的技能。
利用子智能体处理繁重工作：委派多步骤、输出繁重的任务，以保持主智能体的上下文干净。
在配置中调整子智能体输出：如果你在调试时注意到子智能体生成了冗长输出，可以向子智能体的 system_prompt 添加指引，要求其创建摘要和综合后的发现。
使用文件系统：将大型输出持久化到文件（例如子智能体写入或自动卸载），从而让活动上下文保持较小；当模型需要细节时，它可以使用 read_file 和 grep 拉取片段。
记录长期记忆结构：告诉智能体 /memories/ 中有什么以及如何使用它。
为工具传递运行时上下文：使用 context 传递用户元数据、API 密钥以及工具所需的其他静态配置。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织