投入生产

本指南涵盖将深度智能体从本地原型部署到生产环境所需考虑的事项。内容将涉及内存范围界定、执行环境配置、添加防护措施以及连接前端。

概述

智能体利用来自内存和其执行环境的信息来完成任务。在生产环境中，有几个基本原语决定了信息如何被共享和访问：

线程：一次单独的对话。消息历史和临时文件默认限定在线程范围内，不会跨线程延续。
用户：与您的智能体交互的人。内存和文件可以对某个用户私有，或跨用户共享。身份验证和授权来自您的认证层。
助手：一个配置好的智能体实例。内存和文件可以绑定到某个助手，或在所有助手间共享。

本页涵盖：

LangSmith 部署：提供认证、Webhook 和定时任务的托管基础设施
生产环境考量：调用、多租户、认证、凭据、异步和持久性
内存：跨对话持久化信息
执行环境：文件存储和代码执行
防护措施：权限和数据隐私
前端：将您的 UI 连接到已部署的智能体

LangSmith 部署

将深度智能体投入生产的推荐路径是托管深度智能体，这是一个 CLI 优先的托管运行时，用于在 LangSmith 中创建、运行和操作深度智能体。托管深度智能体目前处于私密预览阶段（加入等待列表）。对于需要自定义应用代码、自定义路由、高级认证的团队，您可以直接配置 LangSmith 部署。这两种方式都会为您的智能体配置所需的基础设施：线程、运行、存储和检查点器，因此您无需自行设置这些。传统的 LangSmith 部署还开箱提供认证、Webhook、定时任务和可观测性，并可以通过 MCP 或 A2A 暴露您的智能体。

LangSmith Cloud 部署会自动将跟踪数据发送到以您的部署名称命名的项目中。打开 LangSmith 以调试运行并监控使用情况。对于混合或自托管设置，请参阅 LangSmith 跟踪。我们建议您同时设置 LangSmith 引擎，它可监控您的跟踪数据，检测问题并提出修复建议。

除非另有说明，本页的所有代码片段都使用以下的 langgraph.json 文件：

langgraph.json

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:agent"
  },
  "env": ".env"
}

langgraph.json 是配置文件，它告诉 LangGraph 平台如何构建和运行您的应用程序。它位于项目根目录，对于本地开发（使用 langgraph dev）和生产部署都是必需的。关键字段包括：

字段	描述
`dependencies`	要安装的包。`["."]` 将当前目录作为包安装（从 `requirements.txt`、`pyproject.toml` 或 `package.json` 读取）。
`graphs`	将图 ID 映射到其代码位置。每个条目是 `"<id>": "./<file>:<variable>"`，其中 `<id>` 是您通过 API 调用图时使用的名称，`<variable>` 是从 `<file>` 导出的编译后图或构造函数。
`env`	包含环境变量（API 密钥、秘密）的 `.env` 文件路径。这些变量在构建时设置，并在运行时可用。

有关完整的配置选项（自定义 Docker 步骤、存储索引、认证处理器等），请参阅应用程序结构。

生产环境考量

调用智能体

在生产环境中，每次调用都应携带两个运行级别的参数：

thread_id（通过 config={"configurable": {"thread_id": ...}} 传递）：对话的稳定标识符。检查点器使用它来持久化和恢复消息历史，因此后续轮次可以继续同一对话。生成新的 thread_id 以开始新的对话。
context：您的工具和中间件在调用时读取的每次运行数据，例如 user_id、API 密钥、功能标志或会话元数据。使用 context_schema 定义其形状，并通过 runtime.context 访问它。参见运行时上下文。

这两者相互独立，并且几乎总是一起传递：

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


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

# 开始一个对话
config = {"configurable": {"thread_id": str(uuid7())}}
agent.invoke(
    {"messages": [{"role": "user", "content": "规划一个东京三日游"}]},
    config=config,
    context=Context(user_id="user-123"),
)

# 在同一对话中继续跟进：复用相同的 thread_id
agent.invoke(
    {"messages": [{"role": "user", "content": "改成五天吧"}]},
    config=config,
    context=Context(user_id="user-123"),
)

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


agent = create_deep_agent(
    model="openai:gpt-5.5",
    context_schema=Context,
)

# 开始一个对话
config = {"configurable": {"thread_id": str(uuid7())}}
agent.invoke(
    {"messages": [{"role": "user", "content": "规划一个东京三日游"}]},
    config=config,
    context=Context(user_id="user-123"),
)

# 在同一对话中继续跟进：复用相同的 thread_id
agent.invoke(
    {"messages": [{"role": "user", "content": "改成五天吧"}]},
    config=config,
    context=Context(user_id="user-123"),
)

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    context_schema=Context,
)

# 开始一个对话
config = {"configurable": {"thread_id": str(uuid7())}}
agent.invoke(
    {"messages": [{"role": "user", "content": "规划一个东京三日游"}]},
    config=config,
    context=Context(user_id="user-123"),
)

# 在同一对话中继续跟进：复用相同的 thread_id
agent.invoke(
    {"messages": [{"role": "user", "content": "改成五天吧"}]},
    config=config,
    context=Context(user_id="user-123"),
)

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


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

# 开始一个对话
config = {"configurable": {"thread_id": str(uuid7())}}
agent.invoke(
    {"messages": [{"role": "user", "content": "规划一个东京三日游"}]},
    config=config,
    context=Context(user_id="user-123"),
)

# 在同一对话中继续跟进：复用相同的 thread_id
agent.invoke(
    {"messages": [{"role": "user", "content": "改成五天吧"}]},
    config=config,
    context=Context(user_id="user-123"),
)

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


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

# 开始一个对话
config = {"configurable": {"thread_id": str(uuid7())}}
agent.invoke(
    {"messages": [{"role": "user", "content": "规划一个东京三日游"}]},
    config=config,
    context=Context(user_id="user-123"),
)

# 在同一对话中继续跟进：复用相同的 thread_id
agent.invoke(
    {"messages": [{"role": "user", "content": "改成五天吧"}]},
    config=config,
    context=Context(user_id="user-123"),
)

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


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

# 开始一个对话
config = {"configurable": {"thread_id": str(uuid7())}}
agent.invoke(
    {"messages": [{"role": "user", "content": "规划一个东京三日游"}]},
    config=config,
    context=Context(user_id="user-123"),
)

# 在同一对话中继续跟进：复用相同的 thread_id
agent.invoke(
    {"messages": [{"role": "user", "content": "改成五天吧"}]},
    config=config,
    context=Context(user_id="user-123"),
)

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


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

# 开始一个对话
config = {"configurable": {"thread_id": str(uuid7())}}
agent.invoke(
    {"messages": [{"role": "user", "content": "规划一个东京三日游"}]},
    config=config,
    context=Context(user_id="user-123"),
)

# 在同一对话中继续跟进：复用相同的 thread_id
agent.invoke(
    {"messages": [{"role": "user", "content": "改成五天吧"}]},
    config=config,
    context=Context(user_id="user-123"),
)

使用 LangGraph SDK 部署时，SDK 会为您管理线程，并将返回的 thread_id 传递给每次运行：

from langgraph_sdk import get_client

client = get_client(url="<DEPLOYMENT_URL>", api_key="<LANGSMITH_API_KEY>")

thread = await client.threads.create()
async for chunk in client.runs.stream(
    thread["thread_id"],
    "agent",
    input={"messages": [{"role": "user", "content": "Plan a 3-day trip to Tokyo"}]},
    context={"user_id": "user-123"},
    stream_mode="updates",
):
    print(chunk.data)

thread_id 限定对话（消息历史、检查点）的范围。context 携带您的工具和中间件读取的 每次运行 数据。它们是独立的：更改一个不会影响另一个，您可以传递其中任意一个或两者都传递。

多租户

当您的智能体为多个用户提供服务时，您需要处理三个问题：验证每个用户是谁，控制他们可以访问什么，以及管理智能体用于代表他们行事的凭据。三个认证层组合：最终用户认证、智能体代理用户认证和团队 RBAC

用户身份与访问控制

LangSmith 部署支持自定义认证来建立用户身份，并支持授权处理器来控制对线程、助手和存储命名空间等资源的访问。授权处理器在认证成功后运行，可以：

使用所有权元数据标记资源（例如，owner: user_id）
返回过滤器，使用户只能看到自己的资源
拒绝未经授权的操作并返回 HTTP 403

有关分步教程，请参阅使对话私有化。有关操作演示，请观看自定义认证视频。您如何界定内存范围和执行环境决定了用户之间共享哪些数据。有关详细信息，请参阅下面的章节。

团队访问控制 (RBAC)

LangSmith 的基于角色的访问控制管理团队中谁可以部署、配置和监控智能体。这与上述的最终用户授权是分开的。

角色	访问权限
工作区管理员	完全权限，包括设置和成员管理
工作区编辑者	创建和修改资源，但不能删除运行或管理成员
工作区查看者	只读访问权限

企业版计划提供具有细粒度权限的自定义角色。有关完整的权限模型，请参阅 RBAC 参考。

最终用户凭据

当您的智能体需要代表用户调用外部 API 时（例如，读取他们的 GitHub 仓库、发送 Slack 消息、查询他们的数据仓库），您需要一种方式将用户的凭据传递给智能体，而无需硬编码。 通过代理认证进行 OAuth。 代理认证提供托管的 OAuth 2.0 流程。配置一个 OAuth 提供商，智能体就可以请求限定于每个用户的令牌。首次使用时，智能体会中断执行并显示一个 OAuth 同意 URL。用户完成认证后，智能体将使用有效的令牌恢复执行。令牌会自动存储和刷新。

from langchain_auth import Client
from langchain.tools import tool, ToolRuntime

auth_client = Client()

# 在您的智能体工具内部：
@tool
async def github_action(runtime: ToolRuntime):
    """通过 GitHub 代表用户执行操作。"""
    auth_result = await auth_client.authenticate(
        provider="github",
        scopes=["repo", "read:org"],
        user_id=runtime.server_info.user.identity,
    )
    # 使用 auth_result.token 代表用户进行 GitHub API 调用

沙箱凭据注入。 如果您的智能体在沙箱内运行需要调用外部 API 的代码，沙箱认证代理可以自动将凭据注入到出站请求中，这样沙箱代码永远不会接收到原始的 API 密钥。有关设置详情，请参阅管理密钥。 工作区密钥。 对于所有用户共享的 API 密钥（例如您组织的 LLM 提供商密钥、搜索 API 密钥），请将它们作为工作区密钥存储在 LangSmith 中。有关详细信息，请参阅管理密钥。

异步

基于 LLM 的应用程序在 I/O 方面非常密集：调用语言模型、数据库和外部服务。异步编程允许这些操作并发运行而不是阻塞，从而提高吞吐量和响应能力。

LangChain 遵循在异步方法名前加 a 的约定（例如 ainvoke、abefore_agent、astream）。同步和异步变体位于同一个类或命名空间中。

为生产环境构建时：

创建异步工具。 LangChain 在单独的线程中运行同步工具以避免阻塞，但原生异步可以完全避免线程开销。
使用异步中间件方法。 自定义中间件应实现异步钩子（例如，使用 abefore_agent 而不是 before_agent）。
对资源生命周期使用异步。 创建沙箱或连接到 MCP 服务器涉及网络调用，应该被 await。这就是为什么提供这些资源的图工厂是异步的。

持久性

深度智能体运行在 LangGraph 上，LangGraph 开箱即用地提供了持久化执行。持久化层在每个步骤检查点状态，因此因故障、超时或人在回路暂停而中断的运行可以从其最后记录的状态恢复，而无需重新处理之前的步骤。对于运行时间较长、生成许多子智能体的深度智能体来说，这意味着运行中的故障不会丢失已完成的工作。持久化执行：当工作进程在运行中崩溃时，另一个工作进程会从最新的检查点继续该运行

检查点功能还实现了：

无限期的中断。 人在回路的工作流可以暂停数分钟或数天，并精确地从离开的地方恢复。
时间旅行。 每个检查点步骤都是一个快照，您可以回退到该快照，如果出现问题，可以从更早的状态重放。
安全处理敏感操作。 对于涉及支付或其他不可逆操作的工作流，检查点提供了审计跟踪和恢复点，可以检查导致操作的确切状态。

LangSmith 部署会自动配置一个持久化的检查点器。如果您是自托管，请参阅持久化获取设置说明。

内存

没有内存，每次对话都从零开始。内存使您的智能体能够跨对话保留信息（用户偏好、学到的指令、过往经验），从而可以随时间个性化其行为。有关内存类型的概述，请参阅内存概念指南。短期内存通过检查点限定于单个线程；长期内存通过存储跨线程持久化

范围界定

内存始终在对话之间是持久的。主要问题是它如何在用户和助手边界之间界定范围。正确的范围取决于谁应该看到和修改数据：

范围	命名空间	用例	示例
用户（推荐默认）	`(user_id)`	每个用户的偏好和上下文	“我偏好简洁的回复”
助手	`(assistant_id)`	某个助手的共享指令	“帖子限制在 280 个字符以内”
全局	`(org_id)`	所有用户和助手的只读策略	“绝不透露内部定价”

共享内存（助手、用户或组织范围）是提示注入的一个途径。如果一个用户可以写入另一个用户对话读取的内存，恶意用户可能会将指令注入到该共享状态中。在适当的地方强制执行只读访问。例如，让组织范围的策略只能通过应用程序代码写入，而不能由智能体本身写入。使用权限声明性地拒绝写入共享路径，或使用后端策略钩子实现自定义验证逻辑。

配置

在深度智能体中，内存作为文件存储在虚拟文件系统中。默认情况下，文件限定于单个线程（对话）并且不会在线程间共享。否则，要跨线程共享内存，请将像 /memories/ 这样的路径路由到写入 LangGraph 存储的 StoreBackend。使用 CompositeBackend 可以为智能体同时提供线程作用域的临时空间和跨线程的长期内存。

下面显示的 rt.server_info 和 rt.execution_info 命名空间模式需要 deepagents>=0.5.0。

用户（推荐）
助手
用户
组织

按 user_id 划分命名空间。每个用户都有自己私有的内存。这是推荐的默认设置，因为大多数应用程序部署单个助手。

agent.py

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda rt: (
                    rt.server_info.assistant_id,
                    rt.server_info.user.identity,
                ),
            ),
        },
    ),
    system_prompt="""您在 /memories/ 下拥有持久化内存。
    每次对话开始时读取 /memories/instructions.txt 以获取积累的知识和偏好。
    当您学到应该保留的内容时，请更新该文件。""",
)

按 assistant_id 划分命名空间。内存在同一助手的所有用户之间共享，因此任何用户都可以读取或更新它。适用于使用给定助手的所有人都适用的共享指令或知识（例如，“始终以正式语气回复”）。

agent.py

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda rt: (
                    rt.server_info.assistant_id,
                ),
            ),
        },
    ),
)

仅按 user_id 划分命名空间。内存跟随用户跨所有助手。适用于全局用户资料（姓名、时区、通信偏好），无论用户正在与哪个助手对话都应适用。

agent.py

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda rt: (rt.server_info.user.identity,),
            ),
        },
    ),
)

按 org_id 划分命名空间。内存跨所有用户和所有助手共享。通常用于组织范围的策略（合规规则、品牌指南），这些策略对智能体来说应该是只读的。写入访问应限制为应用程序代码，以防止提示注入。

agent.py

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda rt: (rt.context.org_id,),
            ),
        },
    ),
)

您也可以使用存储 API 从应用程序代码中读取和写入存储。有关示例，请参阅高级用法。有关完整的命名空间工厂 API，请参阅命名空间工厂。有关自改进指令和知识库等内存模式，请参阅长期内存。

执行环境

在本地，智能体可以直接在磁盘上读写文件并运行 shell 命令。在生产环境中，您需要考虑隔离和持久性。正确的设置取决于您的智能体是否需要执行代码：

如果您的智能体只需要读写文件，文件系统后端就足够了。选择一个符合您持久性需求的后端：线程作用域的临时空间、跨线程存储，或两者兼有。
沙箱添加一个隔离的容器，带有用于运行 shell 命令的 execute 工具。如果您的智能体需要运行代码、安装包或进行文件 I/O 之外的任何操作，请使用沙箱。

文件系统

根据需要持久化的内容选择后端：

StateBackend（默认）：线程作用域的临时空间。文件通过检查点器在线程内的轮次之间持久化，但不在线程间共享。在每个步骤进行检查点，因此避免写入大文件。
StoreBackend：跨线程存储，在对话间保留。使用命名空间工厂进行范围界定。
CompositeBackend：混合两者。默认为线程作用域的临时空间，并为特定路径（如 /memories/）设置跨线路由。
ContextHubBackend：LangSmith Hub 仓库（owner/name 或 name）中的持久化文件。当您想要 LangSmith 原生持久化而不需配置单独的 LangGraph 存储时使用。

有关后端列表以及如何构建自定义后端的完整信息，请参阅后端。

FilesystemBackend 和 LocalShellBackend 直接访问宿主机。不要在部署的智能体中使用它们。

沙箱

如果您的智能体需要运行代码（而不仅仅是读写文件），请使用沙箱。沙箱既提供文件系统，也提供用于运行 shell 命令的 execute 工具，并且全部位于一个隔离的容器中。这种隔离也保护您的宿主机：如果智能体的代码耗尽内存或崩溃，只有沙箱会受到影响。您的服务器会继续运行。

生命周期

关键决策是沙箱的生命周期。每个对话是获得一个全新的沙箱，还是对话共享一个持久的环境？

范围	沙箱 ID 存储于	生命周期	示例用例
线程作用域	线程元数据	每次对话全新，TTL 到期后清理	数据分析机器人，每次对话从干净状态开始
助手作用域	助手配置	所有对话共享	编码助手，在对话间维护一个克隆的仓库

下面的示例使用异步图工厂，而不是静态图，因为沙箱需要 thread_id 或 assistant_id 来查找或创建正确的沙箱。图工厂不会接收完整的 Runtime（没有 server_info 或 execution_info）；相反，接收一个 RunnableConfig 并从 config["configurable"] 读取 thread_id 和 assistant_id。工厂是异步的，因为沙箱创建是一个 I/O 密集型操作，需要仅在调用时才可用的每次运行信息。

线程作用域（最常见）
助手作用域

每个对话获得自己的沙箱。图工厂从运行配置中读取 thread_id，因此每个线程会自动获得自己的隔离环境。命名沙箱查找处理跨运行的重复。当沙箱的 TTL 到期时清理。

agent.py

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langchain_core.runnables import RunnableConfig
from langsmith.sandbox import SandboxClient

client = SandboxClient()


async def agent(config: RunnableConfig):
    thread_id = config["configurable"]["thread_id"]
    sandbox_name = f"thread-{thread_id}"
    existing = [
        sb
        for sb in client.list_sandboxes()
        if getattr(sb, "name", None) == sandbox_name
    ]
    if existing:
        ls_sandbox = existing[0]
    else:
        ls_sandbox = client.create_sandbox(
            name=sandbox_name,
            idle_ttl_seconds=3600,  # TTL：闲置时清理
        )
    return create_deep_agent(
        model="google_genai:gemini-3.6-flash",
        backend=LangSmithSandbox(sandbox=ls_sandbox),
    )

所有对话共享一个沙箱。图工厂从 config["configurable"] 读取助手 ID，因此在同一助手上的每个线程都会返回到相同的环境。文件、安装的包和克隆的仓库在对话间持久化。

agent.py

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langchain_core.runnables import RunnableConfig
from langsmith.sandbox import SandboxClient

client = SandboxClient()


async def agent(config: RunnableConfig):
    assistant_id = config["configurable"]["assistant_id"]
    sandbox_name = f"assistant-{assistant_id}"
    existing = [
        sb
        for sb in client.list_sandboxes()
        if getattr(sb, "name", None) == sandbox_name
    ]
    if existing:
        ls_sandbox = existing[0]
    else:
        ls_sandbox = client.create_sandbox(name=sandbox_name)
    return create_deep_agent(
        model="google_genai:gemini-3.6-flash",
        backend=LangSmithSandbox(sandbox=ls_sandbox),
    )

助手作用域的沙箱会随时间积累文件、安装的包和其他沙箱内状态。请向您的沙箱提供商配置 TTL，使用快照定期重置，或实现清理逻辑以防止沙箱的磁盘和内存无限增长。

由于 agent 变量是一个异步函数（不是编译后的图），服务器将其视为一个图工厂，并在每次运行时调用它，注入配置。工厂按名称查找或创建沙箱，并返回一个连接到该沙箱的新智能体图。使用 langgraph deploy 部署后，使用 SDK 从您的应用程序代码中调用智能体。无论范围如何，客户端代码都是相同的。范围界定完全在上面的智能体工厂中处理，但行为有所不同：

线程作用域
助手作用域

每个线程获得自己的沙箱。同一线程内的后续消息重用同一个沙箱，但新的线程总是从全新状态开始，没有前一个对话遗留的文件或安装的包。

client.py

from langgraph_sdk import get_client

client = get_client(url="<DEPLOYMENT_URL>", api_key="<LANGSMITH_API_KEY>")

# 对话 1：安装 pandas 并分析数据
thread_1 = await client.threads.create()
async for chunk in client.runs.stream(
    thread_1["thread_id"],
    "agent",
    input={"messages": [{"role": "human", "content": "Install pandas and analyze sales_data.csv"}]},
    stream_mode="updates",
):
    print(chunk.data)

# 同一对话中的后续操作 — pandas 仍然已安装
async for chunk in client.runs.stream(
    thread_1["thread_id"],
    "agent",
    input={"messages": [{"role": "human", "content": "Now plot the results"}]},
    stream_mode="updates",
):
    print(chunk.data)

# 对话 2：全新沙箱 — pandas 未安装，没有来自对话 1 的文件
thread_2 = await client.threads.create()
async for chunk in client.runs.stream(
    thread_2["thread_id"],
    "agent",
    input={"messages": [{"role": "human", "content": "What packages are installed?"}]},
    stream_mode="updates",
):
    print(chunk.data)

所有线程共享一个沙箱。当沙箱具有重新创建成本高昂的状态时（例如克隆的仓库、安装的依赖项或构建产物），这非常有用。同一助手上的任何对话都可以从上一个对话停止的地方继续，而无需重复设置。

client.py

from langgraph_sdk import get_client

client = get_client(url="<DEPLOYMENT_URL>", api_key="<LANGSMITH_API_KEY>")

# 对话 1：克隆并设置项目
thread_1 = await client.threads.create()
async for chunk in client.runs.stream(
    thread_1["thread_id"],
    "agent",
    input={"messages": [{"role": "human", "content": "Clone https://github.com/org/repo and install dependencies"}]},
    stream_mode="updates",
):
    print(chunk.data)

# 对话 2：仓库和依赖项仍然存在
thread_2 = await client.threads.create()
async for chunk in client.runs.stream(
    thread_2["thread_id"],
    "agent",
    input={"messages": [{"role": "human", "content": "Run the test suite and fix any failures"}]},
    stream_mode="updates",
):
    print(chunk.data)

文件传输

沙箱是隔离的容器，因此您的应用程序代码无法直接访问其中的文件。使用 upload_files() 和 download_files() 在沙箱边界之间移动数据：

在智能体运行前为沙箱准备数据：上传用户文件、技能脚本、配置或持久化内存，以便智能体一开始就拥有所需的一切。
在智能体完成后检索结果：下载生成的工件（报告、图表、导出），并将更新后的内存同步回来以供未来的对话使用。

有关特定提供商的文件传输示例，请参阅使用文件。有关提供商设置、安全性和生命周期模式，请参阅完整的沙箱指南。

示例：使用自定义中间件同步技能和内存

智能体需要执行的技能脚本必须在智能体运行之前上传到沙箱中。您可能还想同步内存，以便智能体可以在容器内读取和更新它们。使用带有 before_agent 和 after_agent 钩子的自定义中间件来跨沙箱边界移动文件：

agent.py

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StoreBackend
from deepagents.backends.langsmith import LangSmithSandbox
from langchain.agents.middleware import AgentMiddleware, AgentState
from langgraph.runtime import Runtime
from langsmith.sandbox import SandboxClient


def _safe_filename(key: str) -> str:
    """拒绝包含路径遍历或通配符字符的键。"""
    name = key.split("/")[-1]
    if ".." in name or any(c in name for c in ("*", "?")):
        raise ValueError(f"无效的键: {key}")
    return name


class SandboxSyncMiddleware(AgentMiddleware):
    """在存储和沙箱之间同步技能和内存。"""

    def __init__(self, backend: CompositeBackend):
        super().__init__()
        self.backend = backend

    async def abefore_agent(self, state: AgentState, runtime: Runtime) -> None:
        """将技能脚本和内存上传到沙箱中。"""
        user_id = runtime.server_info.user.identity  
        store = runtime.store
        files = []
        for item in await store.asearch(("skills", user_id)):
            name = _safe_filename(item.key)
            files.append((f"/skills/{name}", item.value["content"].encode()))
        for item in await store.asearch(("memories", user_id)):
            name = _safe_filename(item.key)
            files.append((f"/memories/{name}", item.value["content"].encode()))
        if files:
            await self.backend.upload_files(files)

    async def aafter_agent(self, state: AgentState, runtime: Runtime) -> None:
        """将更新后的内存同步回存储。"""
        user_id = runtime.server_info.user.identity  
        store = runtime.store
        items = await store.asearch(("memories", user_id))
        results = await self.backend.download_files(
            [f"/memories/{item.key}" for item in items]
        )
        for result in results:
            if result.content is not None:
                await store.aput(
                    ("memories", user_id),
                    result.path.split("/")[-1],
                    {"content": result.content.decode()},
                )


client = SandboxClient()
ls_sandbox = client.create_sandbox()


backend = CompositeBackend(
    default=LangSmithSandbox(sandbox=ls_sandbox),
    routes={
        "/skills/": StoreBackend(
            rt,
            namespace=lambda rt: ("skills", rt.server_info.user.identity),
        ),
        "/memories/": StoreBackend(
            rt,
            namespace=lambda rt: ("memories", rt.server_info.user.identity),
        ),
    },
)

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

管理密钥

沙箱是隔离的容器，因此来自宿主机的环境变量在其中不可用。有两种方式可以向沙箱代码提供 API 密钥和其他秘密信息： 认证代理（推荐）。 沙箱认证代理拦截来自沙箱的出站请求并自动注入认证头。沙箱代码正常调用外部 API，代理根据目标主机添加正确的凭据。这意味着 API 密钥永远不会出现在沙箱代码、环境变量或日志中。沙箱认证代理将凭据注入到出站请求中，因此秘密信息永远不会进入沙箱

{
  "proxy_config": {
    "rules": [
      {
        "name": "openai-api",
        "match_hosts": ["api.openai.com"],
        "inject_headers": {
          "Authorization": "Bearer ${OPENAI_API_KEY}"
        }
      },
      {
        "name": "anthropic-api",
        "match_hosts": ["api.anthropic.com"],
        "inject_headers": {
          "x-api-key": "${ANTHROPIC_API_KEY}"
        }
      }
    ]
  }
}

${SECRET_KEY} 引用解析自存储在您 LangSmith 工作区设置中的密钥。在创建引用这些密钥的模板之前，请先在那里配置密钥。 工作区密钥。 对于不需要基于代理的注入的 API 密钥（例如，由智能体服务器本身使用，而非沙箱代码使用的密钥），请将它们作为工作区密钥存储在 LangSmith 中。这些密钥作为环境变量在运行时可用于工作区中的所有智能体。

避免通过环境变量或文件上传将秘密信息传递到沙箱中。智能体可以读取沙箱内任何可访问的文件或环境变量，包括凭据。认证代理将秘密信息完全隔离在沙箱之外。

防护措施

生产环境中的智能体是自主运行的，这意味着它们可能无限循环、达到速率限制或处理包含敏感信息的用户数据。深度智能体提供两层保护：

权限：声明式的允许/拒绝规则，控制智能体可以读取或写入哪些文件和目录。
容错性：速率限制、重试、回退和错误处理。
数据隐私：在数据到达模型或存储在日志中之前检测和处理个人身份信息 (PII) 的中间件。

权限

权限是声明式的允许/拒绝规则，控制智能体可以读取或写入哪些文件和目录。使用权限将智能体隔离到工作目录、保护敏感文件或强制执行只读内存。规则按声明顺序评估，第一个匹配的规则生效。

容错性

有关速率限制、重试、回退和错误处理，请参阅容错性。

数据隐私

如果您的智能体处理的用户输入可能包含电子邮件、信用卡号码或其他个人身份信息 (PII)，您可以在数据到达模型或存储在日志中之前检测和处理它：

from deepagents import create_deep_agent
from langchain.agents.middleware import PIIMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
    ],
)

策略包括 redact（替换为 [REDACTED_EMAIL]）、mask（部分屏蔽，如 ****-****-****-1234）、hash（确定性哈希）和 block（引发错误）。您也可以为特定领域的模式编写自定义检测器。有关完整的配置，请参阅 PIIMiddleware。有关默认的深度智能体中间件栈，请参阅自定义。有关额外的 LangChain 预构建中间件（重试、回退、PII 检测等），请参阅预构建中间件。

前端

深度智能体使用 useStream 将您的 UI 连接到智能体后端。useStream 是一个前端钩子（适用于 React、Vue、Svelte 和 Angular），可以实时从您的智能体流式传输消息、子智能体进度和自定义状态。在本地，useStream 指向 http://localhost:2024。在生产环境中，将其指向您的 LangSmith 部署并配置重连，以便用户在连接中断时不会丢失进度。

import { useStream } from "@langchain/react";

function App() {
  const stream = useStream<typeof agent>({
    apiUrl: "https://your-deployment.langsmith.dev",
    assistantId: "agent",
  });
}

对于生成许多子智能体的深度智能体工作流，在提交时设置较高的 recursionLimit 以避免截断长时间运行的执行：

stream.submit(
  { messages: [{ type: "human", content: text }] },
  {
    streamSubgraphs: true,
    config: { recursionLimit: 10000 },
  },
);

有关深度智能体特定的 UI 模式，如子智能体卡片、待办事项列表和自定义状态渲染，请参阅前端指南。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

概述

LangSmith 部署

生产环境考量

调用智能体

多租户

用户身份与访问控制

团队访问控制 (RBAC)

最终用户凭据

异步

持久性

内存

范围界定

配置

执行环境

文件系统

沙箱

生命周期

文件传输

管理密钥

防护措施

权限

容错性

数据隐私

前端

​概述

​LangSmith 部署

​生产环境考量

​调用智能体

​多租户

​用户身份与访问控制

​团队访问控制 (RBAC)

​最终用户凭据

​异步

​持久性

​内存

​范围界定

​配置

​执行环境

​文件系统

​沙箱

​生命周期

​文件传输

​管理密钥

​防护措施

​权限

​容错性

​数据隐私

​前端

概述

LangSmith 部署

生产环境考量

调用智能体

多租户

用户身份与访问控制

团队访问控制 (RBAC)

最终用户凭据

异步

持久性

内存

范围界定

配置

执行环境

文件系统

沙箱

生命周期

文件传输

管理密钥

防护措施

权限

容错性

数据隐私

前端