Managed Deep Agents CLI 参考

mda 命令、项目文件和部署行为的参考。

mda CLI 编译并部署代码优先的 Managed Deep Agents。

它随 managed-deepagents Python 包一同提供。

NOTE

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

最快的端到端路径，参阅快速开始。工作流指导参阅身份、记忆、评估、自定义工具、连接、自定义中间件、沙箱、渠道、计划，以及部署一个 agent。

安装

mda init 把 managed-deepagents 声明为一个项目依赖，因此从项目中运行 mda 二进制。

uvx --from managed-deepagents mda init my-agent
cd my-agent
uv sync
uv run mda --version

该包提供 agent、身份、计划和沙箱编写 API，带蛇形命名，外加 mda 控制台脚本。

身份认证

mda deploy 按此顺序读取 API 密钥：

1. LANGGRAPH_HOST_API_KEY
2. LANGSMITH_API_KEY
3. LANGCHAIN_API_KEY

CLI 先从项目 .env 文件读取那些值，然后从进程环境读取。如果在交互式终端中未找到任何密钥，mda deploy 会提示输入一个 LangSmith API 密钥并把它保存到项目 .env 文件。

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>

要用一个组织作用域的密钥部署，设置 LANGSMITH_WORKSPACE_ID 或向 mda deploy 传入 --workspace-id。

LangSmith API 密钥为部署进行身份验证。agent 的模型提供商在运行时也需要凭据。在 .env 中设置提供商密钥，在你的 shell 中导出它，或把它配置为一个 LangSmith 工作区机密。例如，openai:gpt-5.5 需要 OPENAI_API_KEY。

mda deploy 会把非保留的 .env 条目，例如 OPENAI_API_KEY、MCP 令牌和自定义工具凭据，转发为托管部署机密。保留的平台变量，包括 LANGSMITH_API_KEY、LANGGRAPH_HOST_API_KEY、LANGCHAIN_API_KEY 和 LANGSMITH_WORKSPACE_ID，用于 CLI 身份验证和部署路由，但不会作为用户管理的部署机密上传。

命令概述

命令	用途
mda --help	显示 CLI 帮助。
mda --version	显示已安装的 CLI 版本。
mda init <name>	脚手架一个 Python Managed Deep Agents 项目。
mda build [path]	把一个项目编译为一个托管 LangGraph 应用而不部署。
mda evals …	初始化一个 Harbor 工作区，并在编码 agent 中继续评估编写。
mda dev [path]	编译一个项目并在本地 LangGraph 开发服务器上运行它。
mda connections …	管理工具和 MCP 连接器的身份验证。
mda deploy [path]	编译、同步 Context Hub 上下文、上传并部署到 LangSmith。
mda channels init slack	向当前项目添加一个 Slack 渠道声明。
mda logs [path]	追踪一个已部署 agent 的 Agent Server 日志。
mda delete [path] / mda destroy [path]	删除一个已部署的 agent 及它创建的 LangSmith 资源。

初始化项目

使用 mda init 创建一个新项目目录：

uvx --from managed-deepagents mda init my-agent

参数或标志	用途
name	必需的项目目录名。如果目标已存在，该命令会失败。
--instructions TEXT	写入 instructions.md 的系统提示。
--instructions-file PATH	从一个文件读取 instructions.md 的系统提示，或当设为 - 时从 stdin。
--identity	添加带用户自有线程的托管身份验证。
--memory agent|none	可选地写一个根记忆声明。若省略，不创建记忆文件且持久记忆关闭。
--model SPEC	agent 运行所基于的模型，以 provider:model 形式。
--no-sandbox	省略托管沙箱声明。
--channel slack	用一个 Slack 渠道声明初始化 agent。可重复；--channels 是别名。

要在新项目中包含 Slack：

uvx --from managed-deepagents mda init my-agent --channel slack

脚手架语言来自你运行的包，而非当前目录：PyPI 包总是写一个 Python 项目。一个从 PyPI 安装的 CLI 会拒绝 TypeScript 项目。

脚手架创建：

文件	描述
agent.py	从 define_deep_agent(...) 导出的名为 agent。
instructions.md	托管系统提示。
pyproject.toml	最小语言专属清单。
README.md	本地项目说明。
.env	部署身份验证和运行时机密。不要提交真实机密。
.gitignore	忽略 .env、.env.*、.mda/ 和依赖缓存。

评估任务是选择加入的，不由 mda init 创建。从项目根目录运行 mda evals init -i 以初始化 Harbor 工作区，并在编码 agent 中用 eval-engineering 技能继续。

初始化一个 Slack 渠道

从一个现有托管 deep agent 项目的根目录运行以下命令：

uv run mda channels init slack

该命令在 channels/ 目录中创建一个 Slack 渠道声明。下一次 mda deploy 会设置 agent 在 Slack 中出现所需的资源。完整工作流参阅把一个 Managed Deep Agent 连接到 Slack。

构建项目

使用 mda build 把一个项目编译为一个托管 LangGraph 应用而不部署它：

uv run mda build

参数或标志	用途
path	项目目录。默认为当前目录。
--out OUT	已编译应用的输出目录。默认为 <path>/.mda/build。该目录在构建前被清空，因此它必须不存在、为空，或是一个先前构建写入的目录。

评估项目

使用 mda evals init 初始化一个 Harbor 工作区。使用交互式交接，用编码 agent 和 eval-engineering 技能开发完整的任务。

uv run mda evals init -i

命令或标志	用途
mda evals init	在缺失时创建 evals/harbor-job.json，并在 .mda/evals/ 下生成 Harbor 适配器和运行时设置。从项目根目录运行该命令。
-i、--interactive	用评估-工程提示启动一个检测到的编码 agent，或为另一个 agent 复制该提示。

那个交接会要求编码 agent 安装 eval-engineering 技能、检视托管 agent，并在 evals/<task>/ 下写完整的 Harbor 任务。它还包含一个固定的 Harbor 命令，用于加载 MDA 作业插件和 LangSmith 插件。

mda evals compile 是一个由 Harbor 作业插件使用的内部命令。当一个 Harbor 作业启动时该插件会运行它，因此你无需单独编译评估产物。

工作流指导参阅评估。

本地开发

使用 mda dev 编译一个项目并运行本地 LangGraph 开发服务器：

uv run mda dev

参数或标志	用途
path	项目目录。默认为当前目录。
--port PORT	向 LangGraph 开发服务器转发一个端口。
--hostname HOSTNAME	向 LangGraph 开发服务器转发一个主机。
--no-browser	阻止开发服务器在启动时于浏览器中打开 Studio。
--no-reload	禁用开发服务器的热重载。

mda dev 编译到 .mda/build，然后从那个目录启动语言专属的 LangGraph 开发服务器：

项目语言	开发服务器命令
Python	uv run --with langgraph-cli[inmem]>=0.4.30 langgraph dev

在运行 mda dev 之前安装 uv。CLI 会自动解析本地 LangGraph 开发服务器，因此你无需自己安装 langgraph-cli[inmem]。

当配置了沙箱时，mda dev 会尝试配置的提供商。如果提供商凭据不可用或提供商创建失败，它会回退到一个本地临时目录沙箱并打印所选路径。

对于本地开发，mda dev 会把项目 .env 文件暂存到 .mda/build/.env，以便 LangGraph 能加载模型提供商密钥和其他运行时凭据。

管理连接

一个连接把一个托管 deep agent 链接到一个外部服务。凭据住在 LangSmith 工作区中，因此它能无需重新部署就轮换，而一个用户自有的连接会解析调用 agent 者的凭据。工具和 MCP 连接器在运行时用 connections.get(...) 解析连接。

以三种模式之一创建连接：不透明机密（固定 API 密钥）、通用 OAuth（来自目录或自定义端点的 BYOT 应用），或 MCP OAuth（从一个 MCP 服务器 URL 发现并注册）。用 mda connections 在当前工作区管理这些凭据。

命令	用途
mda connections catalog	列出带预配置 OAuth 设置的服务。
mda connections create <slug>	创建一个不透明机密、通用 OAuth 或 MCP OAuth 连接。
mda connections list	列出工作区的连接元数据。
mda connections get <slug>	显示一个连接的元数据。
mda connections delete <slug>	删除一个连接及其存储的材料。

mda connections create 的第一个参数是一个 slug，它是你为该连接取的名字，也是代码传给 connections.get(...) 的名字。提供商名传给 --oauth。

OAuth 目录免去了查找一个提供商 OAuth 设置的麻烦。当你把一个列出的服务传给 --oauth 时，CLI 会提供它的授权 URL、令牌 URL、令牌端点身份验证方法、授权参数和默认作用域，因此你只需提供你的客户端 ID 和客户端密钥。目录不限制你能使用哪些提供商：对于其他任何东西，传入 --authorize-url 和 --token-url。目录名包括 github、google、linear、slack、atlassian 和 notion-api：

uv run mda connections catalog

为一个自定义 Tavily 工具创建一个 agent 自有的 API 密钥：

uv run mda connections create organization-tavily --secret-from-env TAVILY_API_KEY

以下标志控制连接创建：

标志	用途
--project PATH	设置项目目录。默认为当前目录。
--workspace-id WORKSPACE_ID	覆盖 LANGSMITH_WORKSPACE_ID。
--secret-from-env VAR	从 shell 或项目 .env 读取一个固定值或 OAuth 客户端密钥。
--secret-from-file PATH	从一个文件读取一个固定值或 OAuth 客户端密钥。
--oauth SERVICE	使用 mda connections catalog 中某个服务的预配置设置。
--grant-type GRANT	把 OAuth 授权设为 authorization_code 或 client_credentials。默认为 authorization_code。
--client-id CLIENT_ID	设置 OAuth 客户端 ID。
--auth-method METHOD	把令牌端点方法设为 client_secret_basic、client_secret_post 或 none。
--scope SCOPE	替换提供商的默认作用域。对每个作用域重复。
--allowed-scope SCOPE	设置一个授权流能请求的最大作用域。对每个作用域重复。
--authorization-param KEY=VALUE	添加一个 OAuth 授权查询参数。对每个参数重复。
--token-param KEY=VALUE	向 OAuth 令牌请求添加一个参数。对每个参数重复。
--authorize-url URL	设置一个自定义 OAuth 授权端点。需要 --token-url。
--token-url URL	设置一个自定义 OAuth 令牌端点。对于 authorization_code 授权需要 --authorize-url。
--mcp URL	通过从 MCP 服务器 URL 发现 OAuth 创建一个 MCP OAuth 连接。
--authorize	登录已部署 agent 使用的账户，存储一个 agent 自有的 OAuth 授权。需要 OAuth 标志和一个项目目录。

当没有值标志且没有 --oauth 端点时，如果那个 slug 精确匹配项目中一个用户自有的 MCP 连接，mda connections create <slug> 会推断 MCP OAuth。

与 catalog、list 或 get 一起使用 --json 以获得机器可读的输出。与 delete 一起使用 --yes 以跳过确认提示。

关于凭据所有者、创建模式、调用者身份和运行时示例，参阅管理连接。

部署项目

使用 mda deploy 编译一个项目并部署到 LangSmith：

uv run mda deploy

参数或标志	用途
path	项目目录。默认为当前目录。
--name NAME	部署名。默认为 define_deep_agent 中的 agent name。
--deployment-type dev|prod	创建部署时的部署类型。默认为 dev。
--workspace-id WORKSPACE_ID	要部署入的工作区 ID。覆盖 LANGSMITH_WORKSPACE_ID。
--context-strategy overwrite|keep-hub	当 instructions.md 或 skills/ 自上次同步以来在 Hub 中变更时解决 Context Hub 冲突。在非交互式 shell 中必需。参阅 Context Hub。
--no-wait	触发远程构建并退出，而不轮询部署完成情况。

部署运行这些步骤：

1. 验证项目目录并加载 agent 入口文件。
2. 解析 LangSmith API 密钥和可选的工作区 ID。
3. 收集非保留的 .env 值作为托管部署机密。
4. 验证模型提供商 API 密钥可从 .env、shell 环境或 LangSmith 工作区机密中获得。
5. 把部署自有的上下文同步到 Context Hub。
6. 把项目编译到 .mda/build 并提取可选的 schedules/ 和 channels/ 声明。
7. 按名创建或找到一个 LangSmith 托管部署。
8. 归档构建、上传它并触发一个远程构建。
9. 除非设置了 --no-wait，否则轮询该修订版直到它达到 DEPLOYED。
10. 除非设置了 --no-wait，否则为计划调谐托管的 LangSmith cron 作业。
11. 预配声明的 Slack 渠道。如果需要 Slack 授权或工作区审批，显示该操作并在你完成后继续。

一个带 Slack 渠道的项目不能使用 --no-wait，因为 Slack 预配需要已部署的 Agent Server URL。完整工作流参阅把一个 Managed Deep Agent 连接到 Slack。

成功时，CLI 会打印 LangSmith 部署仪表板 URL。有关机密路由和部署提示，参阅部署一个 agent。

读取部署日志

使用 mda logs 追踪一个已部署 agent 的 Agent Server 日志：

uv run mda logs

参数或标志	用途
path	项目目录。默认为当前目录。
--name NAME	部署名。默认为项目中 agent 的 name。
--lines LINES	要获取的最近日志行数。默认为 1000。
--level LEVEL	只显示等于或高于给定严重度的条目：debug、info、warning、error 或 critical。
--follow	持续流式新日志。这是交互式终端中的默认。
--no-follow	打印最近日志并退出。这是输出被管道时的默认。
--workspace-id WORKSPACE_ID	要从中读取的工作区 ID。覆盖 LANGSMITH_WORKSPACE_ID。

删除部署

使用 mda delete 删除一个已部署的 Managed Deep Agent 及它创建的 LangSmith 资源。mda destroy 是一个别名。

uv run mda delete

参数或标志	用途
path	项目目录。默认为当前目录。
--name NAME	部署名。默认为 define_deep_agent 中的 agent name。
--workspace-id WORKSPACE_ID	部署所在的工作区 ID。覆盖 LANGSMITH_WORKSPACE_ID。
--yes	不经确认就删除。

故障排查

症状	原因与修复
project root ... is not a directory	向 mda dev 或 mda deploy 传入一个目录路径。
no agent entry file found	在项目根目录添加 agent.py。
mda dev 找不到 uv	安装 uv，以便 mda dev 能解析本地 LangGraph 开发服务器。
No LangSmith API key found	设置 LANGSMITH_API_KEY 或把它添加到项目 .env。
部署因 401 或 403 失败	确认该 API 密钥属于一个拥有部署访问权限的工作区。参阅定价方案。
部署报告一个缺失的模型提供商 API 密钥	把提供商密钥（例如 OPENAI_API_KEY）添加到 .env、在你的 shell 中导出它，或把它配置为一个 LangSmith 工作区机密。
部署报告一个 Context Hub 冲突	instructions.md 或 skills/ 自上次同步以来在 Context Hub 中变更，或仓库在同步期间变更。在交互式终端中，回答覆盖提示。在非交互式 shell 中，用 --context-strategy overwrite 或 --context-strategy keep-hub 重新运行。参阅 Context Hub。
构建超过 200 MB	在部署前从项目中移除生成的产物或大文件。
部署达到 BUILD_FAILED 或 DEPLOY_FAILED	在 LangSmith 中打开打印的部署 URL 并检视修订版日志。

---