Managed Deep Agents CLI 参考

mda CLI 用于测试和部署代码优先的 Managed Deep Agents。它包含在 managed-deepagents 的 npm 和 Python 包中。

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

欲了解最快的端到端路径，请参阅快速入门。工作流指南请参阅身份验证、评估、自定义工具、自定义中间件、连接器、计划任务和部署代理。

安装

安装用于编写代理的语言的相应包。两个包都暴露了 mda 二进制文件。对于 npm，可以全局安装或使用 npm exec 运行二进制文件。

pip install --pre managed-deepagents

npm install -g managed-deepagents@dev

对于 Python，pip install --pre managed-deepagents 会安装 mda CLI。由 mda init 生成的 Python 项目有自己的 pyproject.toml；在进行本地开发或部署之前，请在该项目中运行 uv sync 以安装项目依赖项。 TypeScript 包提供了代理、身份验证、连接器、通道、计划任务和沙箱的编写 API。Python 包提供了相同的功能接口（使用蛇形命名法），并额外提供了 mda 控制台脚本。

身份验证

mda deploy 按以下顺序读取 API 密钥：

LANGGRAPH_HOST_API_KEY
LANGSMITH_API_KEY
LANGCHAIN_API_KEY

CLI 首先从项目 .env 文件中读取这些值，然后从进程环境中读取。如果在交互式终端中未找到密钥，mda deploy 将提示输入 LangSmith API 密钥并将其保存到项目 .env 文件中。

.env

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>

要使用组织范围的密钥进行部署，请设置 LANGSMITH_TENANT_ID 或向 mda deploy 传递 --tenant-id 参数。 LangSmith API 密钥用于验证部署。代理的模型提供商在运行时也需要凭据。在 .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_TENANT_ID）用于 CLI 身份验证和部署路由，但不会作为用户管理的部署密钥上传。

命令概览

命令	用途
`mda --help`	显示 CLI 帮助。
`mda --version`	显示已安装的 CLI 版本。
`mda init <name>`	搭建一个 TypeScript 或 Python Managed Deep Agents 项目。
`mda evals …`	搭建 Harbor 风格的评估任务并编译 Harbor 交接。
`mda dev [path]`	编译项目并在本地 LangGraph 开发服务器上运行。
`mda deploy [path]`	编译项目、同步 Context Hub 上下文、上传并部署到 LangSmith。

初始化项目

使用 mda init 创建新的项目目录：

mda init my-agent

参数	用途
`name`	必需的项目目录名。如果目标位置已存在，命令将失败。

该命令根据当前目录检测语言：

当前目录包含	结果
仅 `package.json`	TypeScript 项目模板。
仅 `pyproject.toml`	Python 项目模板。
两者都有或都没有	交互式语言提示。

项目模板创建：

文件	描述
`agent.py` 或 `agent.ts`	从 `define_deep_agent(...)` 或 `defineDeepAgent(...)` 导出的名为 `agent` 的定义。
`instructions.md`	托管的系统提示词。
`pyproject.toml` 或 `package.json`	最小化的特定语言清单。
`README.md`	本地项目说明。
`.env`	部署身份验证和运行时密钥。请勿提交真实的密钥。
`.gitignore`	忽略 `.env`、`.env.*`、`.mda/` 和依赖项缓存。
`evals/`	用于 Harbor 试验的示例 Harbor 风格评估任务。

评估项目

使用 mda evals 来搭建 Harbor 风格的任务并编译 Harbor 交接。Harbor 运行这些试验：

mda evals init
mda evals compile .
# then run the printed `harbor run` command

子命令	用途
`mda evals init [path]`	搭建示例 `evals/` 测试套件，或单个任务目录。
`mda evals compile [path]`	将托管代理编译到 `.mda/evals/` 并打印一个 `harbor run` 命令。

mda evals compile 标志：

标志	用途
`--model <provider:model>`	用于示例 Harbor 作业配置的模型。重复使用以在工件清单中记录矩阵；作业配置使用第一个值。

关于任务布局、验证器、身份验证夹具以及运行 Harbor 的详细信息，请参阅评估。

本地开发

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

mda dev .

参数或标志	用途
`path`	项目目录。默认为当前目录。
`--port PORT`	将端口转发到 LangGraph 开发服务器。
`--hostname HOSTNAME`	将主机名转发到 LangGraph 开发服务器。
`--browser`	当开发服务器启动时打开浏览器。默认不打开浏览器。
`--no-reload`	禁用开发服务器的热重载。

mda dev 编译到 .mda/build，然后从该目录启动特定语言的 LangGraph 开发服务器：

项目语言	开发服务器命令
TypeScript	`npx --yes @langchain/langgraph-cli dev`
Python	`uv run --with langgraph-cli[inmem]>=0.4.30 langgraph dev`

对于 Python 项目，请在运行 mda dev 前安装 uv。CLI 会自动解析本地 LangGraph 开发服务器，因此您无需自己安装 langgraph-cli[inmem]。当配置了沙箱时，mda dev 会尝试使用配置的提供商。如果提供商凭据不可用或提供商创建失败，它会回退到本地临时目录沙箱，并打印所选的路径。对于本地开发，mda dev 会将项目 .env 文件暂存到 .mda/build/.env，以便 LangGraph 可以加载模型提供商密钥和连接器令牌。

部署项目

使用 mda deploy 编译项目并将其部署到 LangSmith：

mda deploy .

参数或标志	用途
`path`	项目目录。默认为当前目录。
`--name NAME`	部署名称。默认为项目目录名称，规范化为小写字母、数字和连字符。
`--deployment-type dev\|prod`	创建部署时的部署类型。默认为 `dev`。
`--tenant-id TENANT_ID`	工作区或租户 ID。覆盖 `LANGSMITH_TENANT_ID`。
`--host-url URL`	主机后端 API URL 覆盖。默认为美国 LangSmith Cloud。
`--no-wait`	触发远程构建后退出，不轮询部署完成状态。

部署运行以下步骤：

验证项目目录并加载代理入口文件。
解析 LangSmith API 密钥和可选的租户 ID。
收集非保留的 .env 值作为托管部署密钥。
验证模型提供商 API 密钥是否可从 .env、shell 环境或 LangSmith 工作区密钥获取。
将部署拥有的上下文同步到 Context Hub。
将项目编译到 .mda/build 并提取可选的 schedules/ 声明。
按名称创建或查找一个 LangSmith 托管部署。
归档构建、上传并触发远程构建。
轮询修订版本直到其状态变为 DEPLOYED，除非设置了 --no-wait。
为计划任务协调托管的 LangSmith cron 作业，除非设置了 --no-wait。

成功时，CLI 会打印 LangSmith 部署仪表板 URL。关于密钥路由和部署提示，请参阅部署代理。

项目文件参考

Managed Deep Agents 项目使用代码优先的布局：

my-agent/
  agent.py | agent.ts | agent.tsx         # Required: exports the named agent
  identity.py | identity.ts               # Optional: caller identity and scoping
  instructions.md                         # Managed system prompt, synced to Context Hub
  pyproject.toml | package.json           # Project dependencies
  .env                                    # Deploy auth and runtime secrets (never archived)
  tools/                                  # Authored LangChain tools the agent imports
  middleware/                             # Authored middleware the agent imports
  connectors/mcp.py | connectors/mcp.ts   # Remote MCP server declarations
  connectors/langsmith.py | langsmith.ts  # Optional: constrained LangSmith capabilities
  connectors/github.py | github.ts        # Optional: GitHub sandbox setup
  channels/slack.py | channels/slack.ts   # Optional: Slack Events ingress
  channels/github.py | channels/github.ts # Optional: GitHub App webhook ingress
  schedules/<name>.py | <name>.ts         # Managed cron schedules
  skills/<name>/SKILL.md                  # Deploy-owned skills, synced to Context Hub
  sandbox/__init__.py | sandbox/index.ts  # Managed sandbox configuration
  sandbox/setup.sh                        # Sandbox provisioning script
  evals/<task>/                           # Harbor-style eval tasks (`mda evals compile` + Harbor)

唯一的必需文件是代理入口：agent.py、agent.ts 或 agent.tsx。它必须导出一个使用 define_deep_agent 或 defineDeepAgent 创建的、名为 agent 的定义。tools/ 和 middleware/ 文件夹是常规做法，并非特殊的注册表：托管的智能代理将普通项目文件组织在内，因此代理导入的任何本地模块都能正常工作。当这些文件夹存在时，命令行工具会将剩余文件视为托管的系统提示（instructions.md）、身份标识（identity.*）、连接器（connectors/**）、消息通道（channels/**）、定时任务（schedules/**）、技能（skills/**）、沙箱配置（sandbox/）以及本地 Harbor 评测任务（evals/）。只需要项目根目录下的 agent.ts、agent.tsx 或 agent.py。CLI 按此顺序检测第一个可用的入口文件。

代理入口

代理入口必须导出一个命名的 agent 定义，该定义使用 define_deep_agent 或 defineDeepAgent 创建。有关最小示例，请参阅快速入门。该定义接受 Deep Agents 的 createDeepAgent 配置接口，但托管的密钥除外。设置托管密钥会导致错误。

自定义工具和中间件

将项目拥有的工具和中间件放在本地模块中（例如 tools/ 和 middleware/），从代理入口导入它们，并通过 tools 和 middleware 字段传递。CLI 会将这些文件复制到编译后的构建中，而不会重写它们。有关示例，请参阅自定义工具和自定义中间件。

身份验证

可以选择从项目根目录下的 identity.ts 或 identity.py 导出一个命名的 identity 声明，该文件使用 defineIdentity / define_identity（或 .preset(...)）创建。如果存在，mda 会生成自定义身份验证处理程序，将其注入编译后的应用程序，并根据该声明限定线程、内存和存储访问范围。没有身份验证的项目保留之前的编译输出。关于预设、入口模式、访客令牌和 runtime.identity，请参阅身份验证。

指令

将系统提示词放在项目根目录代理入口文件旁边的 instructions.md 中。 mda dev 会将提示词嵌入生成的入口中。mda deploy 将提示词同步到 Context Hub，部署的运行时会从那里读取它。

技能

将部署拥有的技能放在项目根目录代理入口文件旁边的 skills/ 下。部署会将 skills/** 下的每个 UTF-8 文件同步到 Context Hub，并删除不再存在于本地的陈旧已部署技能。

记忆

托管的记忆与已部署的指令和技能位于同一个 Context Hub 仓库中。运行时将一个限定范围的树重新挂载为 /memories/user/（热路径 /memories/user/AGENTS.md 加上可选的冷文件）以及可选的组织事实作为 /memories/org/（只读）。部署会在需要时播种代理记忆，并同步 instructions.md 和 skills/**，但不会覆盖现有的 Context Hub memories/** 文件。关于热/冷分层、身份重新挂载、组织记忆和 disableMemory，请参阅记忆。

连接器

将连接器声明为 connectors/ 下的模块。发现机制与名称无关：每个文件都是一个连接器模块（会忽略包的 __init__.py 文件）。

MCP: connectors/mcp.ts 或 connectors/mcp.py 必须导出一个命名的 mcp 声明。支持远程 http 和 sse 服务器；stdio 会被拒绝。如果存在，mda 会注入 @langchain/mcp-adapters 或 langchain-mcp-adapters，并将加载的 MCP 工具附加到自定义工具中。
GitHub: connectors/github.ts 或 connectors/github.py 声明仓库检出、GitHub CLI 安装和托管沙箱的凭据注入。
LangSmith: connectors/langsmith.ts 或 connectors/langsmith.py 为不受信任的调用者声明受限制的 LangSmith 功能。需要身份验证。浏览器端永远不会收到 LANGSMITH_API_KEY。

有关示例和默认值，请参阅连接器。

通道

将消息通道声明为 channels/ 下的模块。每个文件导出一个命名的 channel（例如 defineSlackChannel / defineGitHubChannel）。文件主干部分成为通道名称，并在 Agent Server 上挂载 POST /channels/{name}/events。通道需要根身份验证声明。

Slack: channels/slack.ts 或 channels/slack.py。部署会预检 SLACK_SIGNING_SECRET 和 SLACK_BOT_TOKEN（来自通道清单的 requiredEnv）。
GitHub: channels/github.ts 或 channels/github.py，包含有序的 handlers（on、prompt、可选的 repositories / autoReply）。部署会预检 GITHUB_WEBHOOK_SECRET、GITHUB_APP_ID、GITHUB_APP_PRIVATE_KEY 和 GITHUB_INSTALLATION_ID。

关于处理器、触发器和提供商设置，请参阅通道、Slack 和 GitHub。

计划任务

在 schedules/ 下声明托管的 cron 计划任务。每个直接子计划任务文件必须从 defineSchedule(...) 或 define_schedule(...) 导出一个命名的 schedule 声明。部署从静态字面量、数组、对象和顶层字面量常量中提取计划任务声明。计划任务可以通过 deliver_to / deliverTo 将其最终响应发送到配置的 Slack 通道。部署状态达到 DEPLOYED 后，mda deploy 会将现有的托管 LangSmith cron 作业替换为当前的本地计划任务声明。有关示例和约束，请参阅计划任务。

沙箱

要配置托管沙箱，请从 TypeScript 的 sandbox/index.ts 或 Python 的 sandbox/__init__.py 导出 sandbox。作用域默认为每个线程一个沙箱；scope: "agent" 表示在代理进程中共享一个。如果存在 sandbox/setup.sh，则在配置新的托管沙箱时运行一次。有关配置示例和生命周期行为，请参阅配置沙箱。

评估

将 Harbor 风格的评估任务放在 evals/ 下。每个任务目录包括 instruction.md、task.toml、一个 environment/ 镜像和一个 tests/test.sh 验证器。当项目声明了身份验证时，每个任务还需要 identity.json。 mda init 会在 evals/ 下搭建起始评估任务。对于现有项目，使用 mda evals init。使用 mda evals compile 编译 Harbor 交接，然后用 Harbor 运行试验。工件位于 .mda/evals/ 下，并且不属于部署归档的一部分。关于完整工作流，请参阅评估。

忽略的路径

项目加载器会跳过以下目录：

node_modules, .git, .mda, .deepagents, memories, dist, build

在将文件复制到编译后的构建中时，它也会跳过 .env 和 .env.* 文件。mda dev 仅将根目录下的 .env 暂存到 .mda/build/.env 用于本地开发；部署仍然会将非保留的 .env 条目作为托管密钥转发，而不是归档该文件。

代理定义参考

define_deep_agent 和 defineDeepAgent 接受完整的 Deep Agents create_deep_agent 配置接口，但托管的密钥除外。设置作者拥有的字段以配置行为。

作者设置的字段

字段 (Python / TypeScript)	用途
`name`	必需的代理名称，用作助手 ID 和默认部署名称。
`model`	聊天模型实例或 `{provider}:{model_id}` 标识符。
`tools`	导入到代理入口的自定义工具。
`middleware`	围绕模型和工具调用的有序中间件列表。
`subagents`	代理可以委托给的子代理定义。
`permissions`	工具权限规则。
`interrupt_on` / `interruptOn`	运行前需要人工审核才能执行的工具调用。
`response_format` / `responseFormat`	结构化输出格式。
`context_schema` / `contextSchema`	每次运行的运行时上下文的模式。
`cache`	模型缓存配置。
`debug`	启用调试行为。
`disable_memory` / `disableMemory`	仅禁用托管代理的记忆。

托管的字段

托管运行时负责管理 backend、store、checkpointer、memory、skills 以及系统提示词。请勿在代理定义中设置这些字段。

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

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

故障排除

症状	原因及修复
`project root ... is not a directory`	向 `mda dev` 或 `mda deploy` 传递一个目录路径。
`no agent entry file found`	在项目根目录添加 `agent.ts`、`agent.tsx` 或 `agent.py`。
`mda dev` cannot find `uv`	对于 Python 项目，请安装 `uv`，以便 `mda dev` 可以解析本地 LangGraph 开发服务器。
`No LangSmith API key found`	设置 `LANGSMITH_API_KEY` 或将其添加到项目 `.env` 中。
部署失败，返回 401 或 403	确认 API 密钥属于拥有 beta 访问权限的工作区。
部署报告缺少模型提供商 API 密钥	将提供商密钥（例如 `OPENAI_API_KEY`）添加到 `.env`，在 shell 中导出它，或将其配置为 LangSmith 工作区密钥。
部署报告 Context Hub 冲突	在部署期间 Context Hub 仓库发生了更改。请重新运行 `mda deploy`。
构建超过 200 MB	部署前从项目中删除生成的工件或大文件。
部署达到 `BUILD_FAILED` 或 `DEPLOY_FAILED`	在 LangSmith 中打开打印的部署 URL 并检查修订日志。

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

安装

身份验证

命令概览

初始化项目

评估项目

本地开发

部署项目

项目文件参考

代理入口

自定义工具和中间件

身份验证

指令

技能

记忆

连接器

通道

计划任务

沙箱

评估

忽略的路径

代理定义参考

作者设置的字段

托管的字段

故障排除

​安装

​身份验证

​命令概览

​初始化项目

​评估项目

​本地开发

​部署项目

​项目文件参考

​代理入口

​自定义工具和中间件

​身份验证

​指令

​技能

​记忆

​连接器

​通道

​计划任务

​沙箱

​评估

​忽略的路径

​代理定义参考

​作者设置的字段

​托管的字段

​故障排除

安装

身份验证

命令概览

初始化项目

评估项目

本地开发

部署项目

项目文件参考

代理入口

自定义工具和中间件

身份验证

指令

技能

记忆

连接器

通道

计划任务

沙箱

评估

忽略的路径

代理定义参考

作者设置的字段

托管的字段

故障排除