Managed Deep Agents 快速入门

无需搭建基础设施即可部署托管的 Deep Agent。本快速入门指南将引导您搭建一个代码优先的项目，在本地运行代理，编辑托管系统提示词，并使用 mda 进行部署。要逐步构建更完整的代理，请参阅教程。有关完整的部署工作流程和所有 CLI 参数，请参阅部署代理和 CLI 参考。

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

前提条件

在开始之前，请确保已准备以下内容：

拥有可访问私有测试权限的组织（适用于托管深度智能体功能）。
LangSmith API 密钥。
针对 Python 项目：安装 Python 及 uv 工具；针对 TypeScript 项目：安装 Node.js 及 npm 工具。
您选择的模型提供商的 API 密钥。

创建并部署代理

安装软件包

为您想要使用的编程语言安装 managed-deepagents。两个软件包都包含 mda CLI。

pip install --pre managed-deepagents

npm install -g managed-deepagents@dev

对于 Python，pip 命令会安装 mda CLI。在搭建项目后，请在该项目目录下运行 uv sync，以从其生成的 pyproject.toml 文件安装依赖项。

创建项目

创建一个 Managed Deep Agents 项目：

mda init research-assistant
cd research-assistant

CLI 会检测当前目录中的 pyproject.toml 或 package.json。如果无法推断出编程语言，它会提示您选择 Python 或 TypeScript。搭建过程会创建以下文件：

文件	用途
`agent.py` 或 `agent.ts`	由 `mda` 编译的命名 `agent` 定义。
`instructions.md`	托管的系统提示词，在本地嵌入，部署时同步到 Context Hub。
`pyproject.toml` 或 `package.json`	包含 `managed-deepagents` 的最小项目清单。
`README.md`	本地项目说明和部署命令。
`.env`	部署认证和运行时密钥。请勿提交真实的密钥。
`.gitignore`	忽略 `.env`、`.env.*`、`.mda/` 和依赖缓存。
`sandbox/`	托管的 LangSmith 沙箱声明。删除此目录可选择退出。
`evals/`	用于 `mda evals compile` 的示例 Harbor 任务。

有关完整的项目布局，请参阅 CLI 项目文件参考。

将 API 密钥添加到 `.env`

打开生成的 .env 文件，添加您的 LangSmith API 密钥以及计划使用的模型的提供商密钥：

.env

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>

LANGSMITH_API_KEY 用于验证 mda deploy。提供商密钥、MCP 令牌、数据库 URL 以及其他非保留的 .env 值，在您部署时会作为密钥发送到托管的部署环境。.env 文件本身不会上传到源代码归档中。CLI 默认目标指向美国 LangSmith Cloud。要使用组织范围的密钥进行部署，请在 .env 中设置 LANGSMITH_TENANT_ID 或向 mda deploy 传递 --tenant-id 参数。

如果请求返回 401 或 403，请确认该密钥属于一个拥有 beta 访问权限的工作区。

编辑代理

打开生成的 agent.py 或 agent.ts，在代码中配置模型、工具、中间件和中断。

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="research-assistant",  # 研究助手
    model="openai:gpt-5.5",
)

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "research-assistant", // 研究助手
  model: "openai:gpt-5.5",
});

name（名称）是必填项。它将作为 LangGraph 助手 ID 和默认的 LangSmith 部署名称。托管运行时负责管理 backend、store、checkpointer、memory、skills 以及系统提示词。请勿在代理定义中设置这些字段。

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

有关完整字段列表，请参阅代理定义参考。生成的模型使用 OpenAI。如果您使用其他提供商，请更改模型标识符，并在 .env、您的 shell 环境或 LangSmith 工作区密钥中设置该提供商所需的 API 密钥。

编辑指令

打开 instructions.md，用您想要的行为替换生成的提示词：

instructions.md

# Research assistant
# 研究助手

You are a careful research assistant. Search for sources, keep notes, and return
concise answers with citations.
你是一个细心的研究助手。搜索资料来源，记录笔记，并返回附带引用的简洁答案。

mda dev 会将此文件嵌入到生成的本地入口模块中。mda deploy 会将其同步到 Context Hub，部署后的运行时将从那里读取它。

在本地运行

安装生成的项目依赖项，然后启动本地 LangGraph 开发服务器：

uv sync
mda dev .

npm install
mda dev .

对于 TypeScript 项目，mda dev 运行 npx --yes @langchain/langgraph-cli dev。对于 Python 项目，它使用 uv 自动解析并运行本地 LangGraph 开发服务器。您无需自己安装 langgraph-cli[inmem]。mda dev 从编译后的本地构建中加载项目的 .env 文件，因此模型提供商密钥和连接器令牌在本地开发期间可用。

部署代理

部署本地项目：

mda deploy .

成功后，CLI 会打印 LangSmith 部署信息中心的 URL：

Deployment live
Deployment dashboard
https://smith.langchain.com/o/<tenant-id>/host/deployments/<deployment-id>
Deployed 'research-assistant' to LangSmith.

在 LangSmith 中打开打印的 URL 以检查构建状态、修订版本和跟踪记录。

后续步骤

教程

从空目录开始，构建一个定时研究智能体。

工作原理

了解编译、部署生命周期和上下文中心。

身份认证

将对话线程和记忆限定于已认证的调用者。

记忆功能

使用上下文中心 /memories 在不同线程间持久化偏好设置。

评估

编译 Harbor 交接流程并运行 Harbor 风格的任务。

自定义工具

从项目源代码中添加自定义的 LangChain 工具。

自定义中间件

在模型和工具调用周围添加内置或自定义的中间件。

连接器

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

消息渠道

接收 Slack 事件并通过消息渠道进行回复。

定时任务

按托管的定时计划运行智能体。

部署智能体

使用 mda 测试和部署托管深度智能体。

示例

探索一个结合了常用功能的完整项目。

CLI 参考

查看 mda init、mda evals、mda dev 和 mda deploy 命令。

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

前提条件

创建并部署代理

后续步骤

教程

工作原理

身份认证

记忆功能

评估

自定义工具

自定义中间件

连接器

消息渠道

定时任务

部署智能体

示例

CLI 参考

​前提条件

​创建并部署代理

​后续步骤

教程

工作原理

身份认证

记忆功能

评估

自定义工具

自定义中间件

连接器

消息渠道

定时任务

部署智能体

示例

CLI 参考

前提条件

创建并部署代理

后续步骤