部署 Managed Deep Agent

使用 mda CLI 测试并部署 Managed Deep Agent。

部署 Managed Deep Agent 会将代码优先项目编译为托管 LangGraph 应用，将部署自有上下文同步到 Context Hub，上传编译后的源代码，并触发 LangSmith 托管部署构建。结果是一个 Agent Server 部署，包括 Agent Server API 和 MCP 端点。

NOTE

Managed Deep Agents 处于公开 beta 阶段，仅在 US 区域的 LangSmith Cloud 上可用。

本页介绍机密路由和部署选项。要在部署前测试 agent，请参阅使用 LangSmith Studio 在本地开发。有关命令标志、部署步骤列表和故障排除，请参阅 CLI 参考。

前置条件

部署前，请确保你拥有：

• 一个具有 Managed Deep Agents 公开测试版访问权限的工作区。

• 该工作区的 LangSmith API 密钥，位于 .env 或 shell 环境中。

• 从 managed-deepagents 安装的 mda CLI。

• 对于生成的 Python 项目，已使用 uv sync 安装项目依赖。

• 模型提供商凭据（例如 OPENAI_API_KEY），位于 .env、shell 环境或 LangSmith 工作区机密中。

CLI 默认面向美国 LangSmith Cloud。

部署到 LangSmith

部署本地项目：

uv run mda deploy

TIP

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

instructions.md + skills/**  -> Context Hub deploy-owned context
.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

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

uv run mda deploy --name research-assistant

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

uv run mda deploy --deployment-type prod

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

uv run mda deploy --no-wait

设置 --no-wait 时，该次部署调用会跳过计划协调，因为 CLI 会在部署达到 DEPLOYED 之前退出。

成功后，CLI 会打印 LangSmith 部署仪表板 URL。有关完整的部署步骤列表，请参阅 CLI 参考。

设置 Python 版本

NOTE

配置 Python 版本需要 managed-deepagents>=0.8.0。

MDA 会在 Python 3.11、3.12、3.13 或 3.14 上构建部署镜像，并默认选择 requires-python 允许的最新版本。要固定版本，请将可选的 [tool.mda] 表添加到 pyproject.toml：

[project]
requires-python = ">=3.11"

[tool.mda]
python-version = "3.14"

设置后，python-version 接受带引号的 major.minor 字符串，不包含补丁版本。MDA 会将解析后的版本写入生成的 langgraph.json 中的 python_version，并选择匹配的 Agent Server 镜像。requires-python 仍是项目自身的兼容性要求。

固定版本可在 MDA 添加对更新 Python 的支持时保持同一次要版本。要为单次构建覆盖该设置，请设置 MDA_PYTHON_VERSION：

MDA_PYTHON_VERSION=3.12 uv run mda deploy

requires-python 排除的目标会导致构建失败。依赖镜像确切补丁版本的目标只会收到警告，因为镜像标签不固定补丁版本。

python-version 仅控制部署镜像。本地构建、mda dev、Harbor 任务镜像和执行沙箱会分别选择其解释器。

机密和环境文件

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

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

仅当项目声明后端身份时，才需要 MDA_INGRESS_SECRET。如果存在该声明但缺少值，部署会在预检时失败。

LANGSMITH_API_KEY、LANGGRAPH_HOST_API_KEY、LANGCHAIN_API_KEY 和其他平台变量是保留变量。它们可以用于验证部署，但不会作为用户管理的部署机密上传。

当 mda deploy 创建或更新部署时，非保留的 .env 条目（例如模型提供商密钥、MCP token 和自定义工具凭据）会作为托管部署机密转发。如果配置的模型需要提供商密钥，而该密钥不在 .env、shell 环境或 LangSmith 工作区机密中，部署会在上传前失败。当提供商密钥仅在 shell 环境中时，mda deploy 会将其作为该次部署的机密转发。

保留的平台变量、空值、.env 和 .env.* 文件不会复制到编译后的构建归档中。

有关身份验证密钥顺序和保留变量，请参阅 CLI 参考。

排查部署问题

有关部署故障排除，请参阅 CLI 参考。

如果部署达到 BUILD_FAILED 或 DEPLOY_FAILED，请在 LangSmith 中打开打印的部署 URL 并检查修订日志。

后续步骤

•Agent Server

探索托管该部署的运行时。

•MCP endpoint

将已部署的 agent 作为工具暴露给 MCP 客户端。

•Identity

对调用者进行身份验证并提供私有线程。

•Schedules

在托管 cron 计划上运行 agent。

•Custom tools

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

▸CLI reference

查找每个 mda 命令和标志。

---