构建深度助手

Overview

MongoDB Atlas Agent Engine SDK 为构建深度代理提供了面向开发者的界面。深度代理是能够执行文件系统操作、 Shell执行和多步推理的AI代理，所有输入和输出都通过平台经过审核的安全层路由。

提示

要学习；了解有关深度助手的更多信息，请参阅 LangChain 文档中的深度助手概述。

助手作者与三个主节点 (primary node in the replica set)SDK 组件交互：

App.deep_agent()：用于定义和连接深度代理的工厂方法。
技能清单：代理可以在运行时发现和调用的指令集。
工具沙箱后端：通过平台的安全执行路径路由所有工具调用的后端。

先决条件

在构建深度代理之前，必须将 deepagents 依赖项添加到 pyproject.toml文件中，并在 agent.yaml文件中启用深度代理功能。

更新依赖项

要创建深度代理，请将 deepagents包添加到项目的 pyproject.toml文件中：

dependencies = [
    "deepagents==0.5.3",
    ... # other dependencies
]

deepagents包是 agent-engine-sdk-langgraph包的可选依赖项。仅当应用调用 App.deep_agent() 函数时，SDK 才会导入 deepagents包，因此您必须在项目中显式声明它。

更新功能标志

通过将以下标志添加到 agent.yaml文件，启用 agent.yaml 中的深度代理功能：

features:
  deep_agent: true
  ... # other features

此标志指示工具沙箱注册深度代理所依赖的内置文件系统和Shell处理程序。

注意

TypeScript 代理使用等效的 app.deepAgent() 工厂方法构建深度代理，这需要相同的 features.deep_agent: true 设置。本页上的示例使用Python。

dark_agent() 方法

App.deep_agent() 方法是代理作者的主节点 (primary node in the replica set)入口点。它创建了一个已编译的 LangChain图表，该图与平台的 gRPC 和 SSE流媒体路径、 MongoDB支持的检查点以及用于沙盒工具执行的 AgentEngineToolSandboxBackend 类集成。

该方法自动执行以下任务：

使用 AgentEngineToolSandboxBackend 类作为默认沙箱
封装顶级 LLM 和 SecureWrappedLLM 类中的所有 SubAgent 模型，以实施平台经审核的 LLM 路径
将MongoDB检查指针线程化以实现持久性执行状态
返回与现有 gRPC/SSE流媒体路径和 POST /api/v1/executions/{execution_id}/resume API请求兼容的已编译图表

参数

App.deep_agent() 方法接受以下参数：

Parameter	类型	必需	说明
`llm`	LLM	是	用作代理主节点 (primary node in the replica set)模型的语言模型实例。平台会自动将其包装在 `SecureWrappedLLM` 类中。
`tools`	名单	No	可供代理使用的与 LangChain 兼容的工具对象列表。要学习；了解有关 LangChain 工具的更多信息，请参阅 LangChain 文档。
`subagents`	名单	No	`SubAgent` 类实例的列表。每个 `SubAgent.model` 属性必须是 LLM实例，而不是字符串。基于字符串的模型引用会绕过 `SecureWrappedLLM` 类，并在验证时被拒绝。
`skills`	list[str]	No	技能目录的路径列表。每个目录必须包含有效的 `SKILL.md`文件。每条路径必须是 `str` 对象，而不是 `pathlib.Path`对象。要学习；了解有关 SKILL.md 文件的更多信息，请参阅“技能清单”部分。
`system_prompt`	字符串	No	深度代理的自定义系统指令。如果省略，代理将使用 `deepagents` 库中的默认提示。
`middleware`	名单	No	附加中间件，在 SDK 的默认中断恢复和持久嵌套中间件之后运行。
`checkpointer`	any	No	用于状态持久性的 LangGraph 检查点。默认为 `app.checkpointer()`。传递 `None` 以禁用检查点，或传递 `BaseCheckpointSaver`实例以使用自定义检查点。
`store`	any	No	用于存储技能和其他共享数据的 LangGraph存储。
`backend`	any	No	文件系统和Shell操作的后端。默认为 `AgentEngineToolSandboxBackend` 类。自定义后端会绕过平台经过审核的 I/O 路径。要学习；了解更多信息，请参阅工具沙盒后端。

创建具有技能的深度助手

要创建调用技能的深度代理，请将技能目录路径列表传递给 App.deep_agent() 方法的 skills 参数。

以下示例修改了 @app.entrypoint-decorated 函数，以使用单个工具和技能目录创建深度代理：

from agent_engine_sdk_langgraph import App
app = App()
@app.entrypoint
def build_agent():
    return app.deep_agent(
        llm=my_llm,
        tools=[my_tool],
        subagents=[],
        skills=["skills/security-review"],
    )

重要

在将 LLM实例传递给 app.deep_agent() 方法之前，请勿使用 app.llm() 方法对其进行包装。 deep_agent() 方法在内部将 LLM 封装在 SecureWrappedLLM 类中。调用 app.llm() 方法会先注册 __default__ LLM ID两次，导致代理无法启动。

安全验证

初始化时，App.deep_agent() 方法会运行以下检查，并在任一检查失败的情况下引发错误：

检查 SubAgent 类中是否有字符串模型引用：每个 SubAgent.model 属性必须是 LLM实例，而不是字符串。字符串模型名称绕过 SecureWrappedLLM 类，平台会拒绝代理。该方法最多检查 10 层嵌套。
检查手动提供的 backend 参数：平台拥有沙箱并强制将 AgentEngineToolSandboxBackend 类作为后端。提供自定义后端会绕过平台的沙箱，平台会拒绝后端。

注意

App.deep_agent() 方法在 LangChain deepagents 库编译代理图表之前运行上述检查。如果其中一项检查失败，则代理不会启动。

除了这些检查之外，在 deepagents 库编译图表之前，App.deep_agent() 方法还会自动包装传递给 llm 参数的 LLM实例以及 SecureWrappedLLM 类中的所有 SubAgent.model 属性。

技能清单

技能是您提供给深度代理的可重用指令集。每项技能都位于自己的子目录中，并由带有 YAML frontmatter 的 SKILL.md文件进行描述。该平台会在代理初创企业时读取 frontmatter，以验证该技能并向 LLM 公开该技能。

技能目录结构

技能位于以下目录结构中，其中目录名称与 frontmatter 中的 name字段匹配：

<workspace-directory>/
└── skills/
    └── <skill-name>/
        └── SKILL.md

传递给 skills 参数的技能路径相对于助手的工作区目录，即包含 agent.yaml文件的目录。

SKILL.md 格式

有效的 SKILL.md文件必须以 YAML frontmatter 开头。以下示例是有效 SKILL.md文件的模板：

---
name: <skill-name>
description: <one-sentence description for LLM discovery>
---
# Skill Title
Detailed instructions or reference material for the agent...

您必须在 YAML frontmatter 中包含以下字段：

字段	必需	说明
`name`	是	技能名称。必须与父目录名称完全匹配。
`description`	是	The LLM uses this short description to decide when to invoke the skill. Skills missing a `description` are skipped by the platform with a warning at agent startup and are not available to the agent.

注意

SKILL.md文件必须仅包含有效的 UTF-8 字符。代理初创企业时会跳过平台无法读取为 UTF-8 的文件，而不会导致崩溃。

将技能传递给助手

以下示例将技能目录路径列表传递给 App.deep_agent() 方法：

agent = app.deep_agent(
    llm=my_llm,
    tools=[],
    skills=["skills/security-review", "skills/style-guide"],
)

工具沙盒后端

AgentEngineToolSandboxBackend 类实施 SandboxBackendProtocol协议。后端使用 SecureToolWrapper 类，通过平台的工具沙箱处理程序路由来自深度代理图表的所有文件系统和Shell工具调用。您无需直接实例化或配置 AgentEngineToolSandboxBackend 类，因为 App.deep_agent() 方法会自动注入该类。

注意

AgentEngineToolSandboxBackend 类是可选依赖项，不会从包根目录中重新导出。如果需要直接引用它，请显式导入。以下示例演示了如何导入该类：

from agent_engine_sdk_langgraph.backends.tool_sandbox import AgentEngineToolSandboxBackend

支持的操作

AgentEngineToolSandboxBackend 类操作由代理在运行时自动调用，而不是由代理作者直接调用。 AgentEngineToolSandboxBackend 类支持以下操作，每个操作作为相应的 filesystem_* 或 shell_execute 工具公开给 LLM：

操作	说明
`ls`	列出给定路径中的文件和目录
`read`	读取文件内容
`write`	将内容写入文件
`edit`	对现有文件应用编辑
`glob`	查找与 glob模式匹配的文件
`grep`	在文件中搜索模式
`execute`	在沙箱中运行Shell命令
`download_files`	将文件从沙箱下载量到调用方

Error Handling

后端先对所有错误进行分类，然后再将错误显示给代理图表，以便代理可以决定是否重试操作。下表显示了可能的错误分类及其原因：

分类	原因示例
可重试	瞬时网络或输入和输出错误，例如 `ConnectionError`、`OSError` 或 `TimeoutError`。
不可重试	`PolicyDeniedException`：操作被平台的安全策略拒绝。代理无法重试此操作。 `RuntimeError`：在有效的代理沙箱上下文之外使用了后端，例如在本地脚本或测试中。此错误可防止配置错误时的无限重试循环。

在将错误消息显示给代理之前，平台会从所有错误消息中去除所有内部工作区路径。

Filesystem Sandbox

深度代理在沙盒文件系统内运行。沙箱包含以下层：

可写工作区 (WORKSPACE_DIR)：默认为 /tmp/agent-workspace目录。在代理沙箱会话期间，沙箱会限制代理对 WORKSPACE_DIR/.sessions/<session-hash>/ 路径的访问权限，以便并发会话保持隔离。对生成的文件使用相对路径或 /tmp目录下的路径。
只读资源根 (READONLY_RESOURCE_ROOTS)：由 AGENTIC_AGENT_WORKDIR 环境变量和 skills/目录填充。该层允许代理读取每个会话工作区内部和外部的 SKILL.md 文件，以便按需加载技能内容。

重要

请勿将 WORKSPACE_DIR 环境变量设立为代理源目录，例如 /app目录。如果您将 WORKSPACE_DIR 变量设立为代理源目录，则代理会使技能文件在运行时无法访问，并引发 Path escapes workspace sandbox 错误。

要更改工作区目录，设立AGENTIC_AGENT_WORKDIR 环境变量：

# .env
AGENTIC_AGENT_WORKDIR=/app
# Do NOT add: WORKSPACE_DIR=/app

后退

在本地运行代理