部署一个托管深度代理

部署一个托管深度代理会将以代码优先的项目编译成一个托管的 LangGraph 应用，将部署拥有的上下文同步到上下文中心，上传编译后的源代码，并触发一个 LangSmith 托管的部署构建。

托管深度代理目前处于私有测试阶段，仅在LangSmith Cloud的美国区域提供。加入等待列表以申请访问权限。

本页涵盖密钥路由、本地开发行为、沙箱配置和部署提示。关于命令标志、部署步骤列表和故障排除，请参阅 CLI 参考。

关于编译的概念性讲解、部署生命周期图、上下文中心、线程和沙箱，请参阅托管深度代理如何工作。

前提条件

在部署之前，请确保您已具备：

一个拥有托管深度代理私有测试版访问权限的工作区。
该工作区的 LangSmith API 密钥，可存放在 .env 文件或您的 shell 环境变量中。
已从 managed-deepagents 安装 mda CLI。
已通过 npm install（对于 TypeScript 项目）或 uv sync（对于生成的 Python 项目）安装项目依赖。
模型提供者凭据，例如 OPENAI_API_KEY，存放在 .env 文件、shell 环境变量或 LangSmith 工作区密钥中。

CLI 默认面向美国 LangSmith Cloud。

项目文件

一个托管深度代理项目从一个代理入口文件和可选的项目文件夹开始。使用 mda init 创建一个项目，或者通过在项目根目录添加 agent.ts、agent.tsx 或 agent.py 来适配现有的 TypeScript 或 Python 项目。完整的文件布局和打包规则，请参阅 CLI 项目文件参考。要定义代理入口、工具、中间件和中断，请参阅快速入门。托管运行时负责管理 backend、store、checkpointer、memory、skills 以及系统提示词。请勿在代理定义中设置这些字段。

配置项	负责方	配置位置
`name`	由你设置	代理定义中必填；用作助手 ID 和默认部署名称。
`backend`、`store`、`checkpointer`	托管运行时	不可配置。
`memory`	托管运行时（由 Context Hub 提供支持）	`disableMemory` / `disable_memory` 用于关闭代理作用域的内存功能。
`skills`	托管运行时（由 Context Hub 提供支持）	项目中的 `skills/**` 目录。
系统提示词	托管运行时（由 Context Hub 提供支持）	项目中的 `instructions.md` 文件。
模型、工具、中间件、子代理、中断处理	由你设置	通过代理定义和导入的模块配置。

有关完整字段列表，请参阅代理定义参考。

配置指令、技能和记忆

将系统提示词放在 instructions.md 文件中，并将其与项目根目录的代理入口文件放在一起：

instructions.md

# 助手

你是一个细心的助手。需要时使用可用工具并引用来源。

将部署拥有的技能放在 skills/ 目录下，该目录与项目根目录的代理入口文件放在一起。部署会将 instructions.md 和 skills/** 同步到与部署关联的上下文中心仓库。托管记忆存储在同一个上下文中心仓库的 memories/** 路径下，并为代理重新挂载为 /memories/user/（热路径 /memories/user/AGENTS.md）。部署会同步 instructions.md 和 skills/**，但会保留记忆，不会覆盖 memories/**。要禁用托管记忆，请在代理定义中设置 disableMemory: true 或 disable_memory=True。

添加工具、连接器和中间件

直接在代理源文件中添加编写的工具和中间件。托管深度代理会将您的项目文件复制到编译后的构建中，因此从 tools/、middleware/ 或其他本地模块导入的用法与在普通 Python 或 TypeScript 项目中相同。

使用自定义工具处理业务逻辑、私有 API、数据库访问和其他项目自有代码。
使用自定义中间件处理模型调用、工具调用、生命周期钩子、重试、限制和数据处理等跨切面行为。
在 connectors/mcp.ts 或 connectors/mcp.py 中声明远程 MCP 服务器；托管深度代理会在运行时加载这些连接器工具并将它们附加到编写的工具之后。示例和指南，请参阅连接器。
可选地，在 identity.ts 或 identity.py 中声明身份验证，以对调用者进行身份验证并限定线程和记忆的范围。

要在调用敏感工具前暂停以等待人工批准，请在代理定义中设置 interrupt_on。请参阅人在回路中。

添加计划任务

当代理需要按周期性节奏运行时，在 schedules/ 目录下添加托管的 cron 计划。每个计划文件导出一个使用 defineSchedule 或 define_schedule 创建的命名 schedule 声明。示例和计划约束，请参阅计划任务。

配置沙箱

当代理需要隔离的代码执行或文件系统工作时使用沙箱。从 sandbox/index.ts 或 sandbox/__init__.py 导出 sandbox。

from managed_deepagents import define_sandbox
from deepagents.backends import LangSmithSandbox

sandbox = define_sandbox(
    LangSmithSandbox,
    scope="thread",
    idle_ttl_seconds=600,
    default_timeout=600,
)

import { defineSandbox } from "managed-deepagents";
import { LangSmithSandbox } from "deepagents";

export const sandbox = defineSandbox(LangSmithSandbox, {
  scope: "thread",
  idleTtlSeconds: 600,
  defaultTimeout: 600,
});

沙箱作用域控制复用方式：

thread（默认）：每个持久化线程或会话都有自己的沙箱。
agent：代理进程处理的所有线程共享一个沙箱。

如果存在 sandbox/setup.sh，托管深度代理会在配置新的托管沙箱时运行一次该脚本。可以使用它来安装包、播种文件或准备工作区状态。本地开发期间沙箱的作用域和生命周期，请参阅托管深度代理如何工作。

本地运行

运行本地 LangGraph 开发服务器：

mda dev .

mda dev 会编译到 .mda/build 目录，并从该目录启动匹配的 LangGraph 开发服务器。传递 --port、--hostname、--browser 或 --no-reload 来转发本地开发服务器选项。对于本地开发，mda dev 会将项目的 .env 文件暂存到 .mda/build/.env，以便 LangGraph 可以加载模型提供者密钥和连接器令牌。对于 Python 项目，mda dev 要求 PATH 中有 uv，并会自动解析本地 LangGraph 开发服务器。当配置了沙箱时，mda dev 会尝试使用配置的提供者，如果提供者凭据不可用，则回退到本地临时目录沙箱。本地回退仅用于开发目的。所有 mda dev 标志，请参阅 CLI 参考。

部署到 LangSmith

部署本地项目：

mda deploy .

mda deploy 将本地项目输入路由到不同的托管表面：

instructions.md + skills/**  -> Context Hub deploy-owned context
memories/**                  -> ignored; existing Context Hub memory is preserved
.env                         -> deploy auth + non-reserved hosted secrets, not archived
project source files         -> .mda/build source archive -> hosted deployment
schedules/**                 -> LangSmith cron jobs after the deployment is live

当目录名不是您想要的部署名称时，请显式设置部署名称：

mda deploy . --name research-assistant

创建生产部署时使用 --deployment-type prod：

mda deploy . --deployment-type prod

使用 --no-wait 触发构建而不轮询其完成状态：

mda deploy . --no-wait

当设置 --no-wait 时，该次部署调用会跳过计划任务的协调，因为 CLI 在部署到达 DEPLOYED 状态之前就已退出。成功后，CLI 会打印 LangSmith 部署仪表板 URL。完整的部署步骤列表，请参阅 CLI 参考。

密钥和环境变量文件

mda deploy 在读取 shell 环境变量之前会先读取项目 .env 文件的值。使用 .env 存放用于验证部署的 LangSmith API 密钥，以及托管部署所需的运行时密钥：

.env

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>
GITHUB_MCP_TOKEN=<GITHUB_MCP_TOKEN>
DATABASE_URL=<DATABASE_URL>

LANGSMITH_API_KEY、LANGGRAPH_HOST_API_KEY、LANGCHAIN_API_KEY 和其他平台变量是保留的。它们可以用于验证部署，但不会作为用户管理的部署密钥上传。非保留的 .env 条目，例如模型提供者密钥、MCP 令牌、频道密钥和自定义工具凭据，在 mda deploy 创建或更新部署时，会作为托管部署密钥转发。如果配置的模型需要提供者密钥，且该密钥无法从 .env、shell 环境变量或 LangSmith 工作区密钥中获取，部署会在上传前失败。当提供者密钥仅存在于 shell 环境变量中时，mda deploy 会将其作为该次部署的密钥进行转发。当项目声明了 channels/ 时，部署还会预检每个频道清单的 requiredEnv（例如 Slack 或 GitHub App 密钥）——请参阅频道。保留的平台变量、空值、.env 和 .env.* 文件不会被复制到编译后的构建存档中。关于身份验证密钥顺序和保留变量，请参阅 CLI 参考。

部署故障排除

部署故障排除，请参阅 CLI 参考。如果部署达到 BUILD_FAILED 或 DEPLOY_FAILED 状态，请在 LangSmith 中打开打印出的部署 URL 并检查修订日志。

后续步骤

身份验证

对调用者进行身份验证并限定线程和记忆的范围。

连接器

附加 MCP 服务器或受限的 LangSmith 功能。

频道

接收 Slack 事件并配置频道密钥。

计划任务

按托管的 cron 计划运行代理。

自定义工具

将编写的 LangChain 工具添加到代理定义中。

CLI 参考

查阅每个 mda 命令和标志。

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

Agent definition

Build and deploy

前提条件

项目文件

配置指令、技能和记忆

添加工具、连接器和中间件

添加计划任务

配置沙箱

本地运行

部署到 LangSmith

密钥和环境变量文件

部署故障排除

后续步骤

身份验证

连接器

频道

计划任务

自定义工具

CLI 参考

​前提条件

​项目文件

​配置指令、技能和记忆

​添加工具、连接器和中间件

​添加计划任务

​配置沙箱

​本地运行

​部署到 LangSmith

​密钥和环境变量文件

​部署故障排除

​后续步骤

身份验证

连接器

频道

计划任务

自定义工具

CLI 参考

前提条件

项目文件

配置指令、技能和记忆

添加工具、连接器和中间件

添加计划任务

配置沙箱

本地运行

部署到 LangSmith

密钥和环境变量文件

部署故障排除

后续步骤