主题
定义 Managed Deep Agent
配置 managed deep agent 的模型和核心能力。
agent 定义用于选择 managed deep agent 的模型和核心能力。
NOTE
Managed Deep Agents 处于公开 beta 阶段，仅在 US 区域的 LangSmith Cloud 上可用。
agent 入口位于项目根目录：
text
my-agent/
agent.py有关完整项目布局，请参阅项目结构。
要定义 agent，请使用 define_deep_agent：
python
from managed_deepagents import define_deep_agent
agent = define_deep_agent(
name="research-assistant",
model="openai:gpt-5.5",
)python
from managed_deepagents import define_deep_agent
agent = define_deep_agent(
name="research-assistant",
model="anthropic:claude-sonnet-4-6",
)python
from managed_deepagents import define_deep_agent
agent = define_deep_agent(
name="research-assistant",
model="google_genai:gemini-3.6-flash",
)通过各自的项目文件而非 agent 定义来配置 system prompt、skills、memory、sandbox、identity、channels 和 schedules。请参阅项目结构。
define_deep_agent 不会编译 agent。它返回一个定义，托管运行时会在部署时用 create_deep_agent 编译它。下面的参数是 create_deep_agent 的接口表面，但不包含运行时自己管理的参数。请参阅与 Deep Agents 的关系。
参数
| 参数 | 作用 |
|---|---|
name= | 必需。传入一个以字母开头、仅包含字母、数字、下划线或连字符的静态字符串，例如 "research-assistant"。Managed Deep Agents 会将此名称用作 agent 的 graph ID 和默认的 LangSmith 部署名称，客户端在调用部署时会将其作为 assistant_id 传入。你可以使用 mda deploy --name 覆盖部署名称，而无需更改 agent 定义。 |
model= | 设置 agent 使用的聊天模型。最简单的选项是 provider:model 字符串。将提供商的 API key 添加到 .env，以便模型在本地和部署中都能工作。当你需要在代码中配置模型参数时，可以改为传入 LangChain 聊天模型实例。有关模型选项和支持的提供商，请参阅模型。 要连接 LLM Gateway，请参阅使用 LLM Gateway。 |
tools= | 添加 agent 可以调用的工具。将工具传入 tools 列表，以便 agent 调用应用逻辑或外部服务。在本地模块中定义工具，将它们导入 agent 入口，并添加到定义中。请参阅自定义工具。要从远程 MCP 服务器添加工具而无需将它们导入 agent 入口，请使用 MCP 连接器。 |
middleware= | 在模型调用、工具调用和 agent 生命周期周围添加行为。将中间件传入 middleware 列表。中间件按列表顺序运行。请参阅自定义中间件。 |
subagents= | 定义用于委派任务的专用 agent。当 agent 应委派专用或上下文繁重的工作时，传入 subagent 定义。每个 subagent 可以有自己的 prompt、模型和工具。请参阅Subagents。 |
permissions= | 控制文件系统工具的路径级访问。传入文件系统权限规则，以控制 agent 内置文件系统工具可以读取或写入哪些路径。当项目声明了 sandbox 时，此设置会被清除，因为权限规则会禁用 sandbox 的 execute 工具。请参阅权限。 |
interrupt_on= | 在选定的工具调用之前暂停，等待人工批准。设置 interrupt_on 以在选定的工具调用之前暂停，使人员可以在调用运行前批准、编辑或拒绝它。请参阅Human-in-the-loop。 |
response_format= | 当 agent 必须返回符合 schema 的数据而不是无约束文本响应时设置。请参阅结构化输出。 |
使用 LLM Gateway
你可以使用 LLM Gateway 对模型调用应用速率限制、fallback 和其他策略。
在 gateway 模型 ID 前加上 langsmith:：
python
from managed_deepagents import define_deep_agent
agent = define_deep_agent(
name="my-agent",
model="langsmith:moonshotai/kimi-k3",
)NOTE
Gateway 模型 ID 在提供商和模型之间使用斜杠（langsmith:provider/model-name）。直接调用提供商的模型字符串使用冒号（provider:model-name）。
Gateway 会按模型 ID 路由每个请求。moonshotai/kimi-k3 是由 LangChain 托管的模型，因此不需要提供商 secret，并会使用 Gateway Credits。以 workspace 已配置的提供商开头的模型 ID（例如 anthropic/claude-opus-5）会使用该提供商 secret，并计入你自己的提供商账户。
更多信息请参阅 LLM Gateway。
要创建一个从一开始就使用 Gateway 的项目，请在初始化时传入 --gateway：
bash
mda init my-agent --gateway