Python扩展

使用 Python 工具、中间件和存储路由自定义 dcode

Python 扩展可以在不修改 dcode 本身的情况下自定义 dcode agent 服务器。使用它们来注册模型工具、LangChain 中间件、虚拟存储路由。

Python 扩展需要 DEEPAGENTS_CODE_EXPERIMENTAL=1。这是一个实验性 API，可能会更改或未经通知被移除。

扩展会以您的用户账户权限运行任意 Python 代码。仅从您信任的源加载扩展。扩展工具不会自动添加到人工审批映射中，因此执行敏感操作的扩展必须通过中间件自行执行审批或策略。

创建扩展

扩展的入口文件必须暴露一个异步 extension 设置函数。dcode 会传递一个 ExtensionAPI 注册器，其中包含只读会话上下文和添加功能的方法。

以下扩展将 LangGraph 存储提供给智能体的文件工具，路径为 /memories/：

extension.py

from deepagents.backends import StoreBackend

from deepagents_code.extensions import ExtensionAPI


async def extension(d: ExtensionAPI) -> None:
    d.register_backend_route(
        "/memories/",
        StoreBackend(namespace=lambda _runtime: ("filesystem",)),
    )

使用实验性门控启动 dcode 并加载一次文件：

DEEPAGENTS_CODE_EXPERIMENTAL=1 dcode --extension ./extension.py

重复 -e 或 --extension 以加载多个文件或目录。目录扫描包括直接 *.py 文件和包含 __init__.py 或 extension.py 的直接子目录。加载还需要启用扩展发现（[extensions].enabled 或 DEEPAGENTS_CODE_EXTENSIONS）；当发现被禁用时，Deep Agents Code 会跳过每个源，包括 CLI 路径。

注册功能

扩展 API 支持以下方法：

方法	签名	目的
register_middleware	(class_or_instance)	添加 LangChain AgentMiddleware。中间件类必须有一个零参数构造函数；否则，请传递一个实例。
register_tool	(function_or_tool)	向模型暴露一个可调用对象或 BaseTool。dcode 会将普通可调用对象转换为 LangChain 工具模式。
register_backend_route	(prefix, backend)	在虚拟路径下提供 BackendProtocol 存储提供程序。
on_shutdown	(callback)	当智能体服务器停止时释放会话资源。支持同步和异步回调。

注册器还暴露了以下只读上下文：

• d.cwd: 会话的工作目录。
• d.mode: interactive 或 headless。
• d.has_ui: 会话是否具有交互式终端 UI。
• d.path: 扩展的入口文件。

在模块导入期间不要打开长连接或启动后台任务。如果设置函数打开会话资源，请注册一个 idempotent on_shutdown 回调来释放它。

注册中间件

注册 LangChain 中间件以向智能体添加模型或工具行为。dcode 在构建智能体图时加载中间件。

from langchain.agents.middleware import AgentMiddleware

from deepagents_code.extensions import ExtensionAPI


class ExampleMiddleware(AgentMiddleware):
    name = "example-middleware"


async def extension(d: ExtensionAPI) -> None:
    d.register_middleware(ExampleMiddleware())

在需要配置时使用 AgentMiddleware 实例。您也可以传递一个具有零参数构造函数的中间件类。

注册工具

注册一个可调用对象或 BaseTool 以使其对模型可用。

from deepagents_code.extensions import ExtensionAPI


async def extension(d: ExtensionAPI) -> None:
    def current_directory() -> str:
        """Return the working directory for the current dcode session."""
        return str(d.cwd)

    d.register_tool(current_directory)

dcode 会根据函数签名和 docstring 将普通可调用对象转换为 LangChain 工具。扩展工具可以替换同名的内置工具。在扩展之间，第一个注册的工具名称将生效。

路由虚拟存储

后端路由前缀必须是带首尾斜杠的小写绝对路径，例如 /memories/ 或 /company/knowledge/。dcode 会拒绝无效路径和与其内部工件或对话历史存储重叠的路由。

路由内容可以通过模型的文件工具访问。Shell execute 仍然附加到默认本地或沙盒存储，因此 shell 命令无法访问虚拟路由内容。沙盒化智能体也会拒绝直接由 FilesystemBackend 支持的路由，因为那会在 shell 执行仍处于沙盒的情况下暴露主机存储。

扩展工具和中间件会替换同名的内置工具。在扩展之间，第一个注册的路由前缀或单元名称将生效。

应用运行时更改

启动后注册的工具会在下一个模型请求时出现。中间件和后端路由会更改智能体图构建，需要 /reload。运行 /extensions 以列出注册信息、它们的源路径和作用域、加载失败情况以及是否需要重启。

必须由其操作员重启或重新部署单独管理的远程智能体服务器。

选择扩展源

dcode 按以下顺序加载授权的扩展源，并忽略后续的重复入口路径：

1. ~/.deepagents/extensions/ 中的 Python 文件。
2. [extensions].extra_paths 中的文件和目录。
3. 使用 -e 或 --extension 传递的文件和目录。
4. 启用且版本化的插件中的 Python 扩展。
5. 通过 dcode.extensions Python 入口点组暴露的模块。
6. <project>/.deepagents/extensions/ 中的可信项目扩展。

使用 ~/.deepagents/extensions/ 进行快速用户范围扩展。使用 plugin 进行版本化分发和更新。使用项目扩展来维护一个代码库。

信任项目扩展

<project>/.deepagents/extensions/ 中的项目扩展只有在获得项目信任后才执行。在交互模式下，dcode 会在您允许当前文件一次，记住用于未来会话和编辑的规范项目路径，或跳过它们之间提示您。取消提示（例如，使用 Esc）会中止启动。

对于无头或 CI 运行，为该调用授予权限：

DEEPAGENTS_CODE_EXPERIMENTAL=1 \
  dcode --trust-project-extensions -n "Run the project checks"

使用 [extensions].trust 或 DEEPAGENTS_CODE_EXTENSIONS_TRUST 将默认项目策略设置为 ask、always 或 never。仅在您打开的每个项目都是可信的情况下使用 always。

配置扩展

在 ~/.deepagents/config.toml 中配置发现：

~/.deepagents/config.toml

[extensions]
enabled = true
trust = "ask"
extra_paths = [
    "extensions/policy.py",
    "~/src/company-extensions",
]

设置	默认值	描述
enabled	true	为每个源启用扩展发现，包括 -e / --extension。实验性环境变量仍然需要。
trust	"ask"	将项目扩展信任设置为 ask、always 或 never。
extra_paths	[]	添加用户授权的 Python 文件或目录。相对路径从 dcode 配置目录解析；~ 扩展到您的家目录。

DEEPAGENTS_CODE_EXTENSIONS 覆盖 enabled，DEEPAGENTS_CODE_EXTENSIONS_TRUST 覆盖 trust。两者仍然需要 DEEPAGENTS_CODE_EXPERIMENTAL=1。当 enabled 为 false 时，Deep Agents Code 会跳过每个扩展源。

将扩展打包为插件

版本化的 plugin 是分发扩展的首选方式。在插件清单中，在 Deep Agents Code 命名空间下声明一个入口文件或一个列表：

.claude-plugin/plugin.json

{
  "name": "shared-memory",
  "version": "1.0.0",
  "extensions": {
    "com.langchain.deepagents.code": {
      "pythonExtensions": "./extension.py"
    }
  }
}

每个条目必须以 ./ 开头，并保留在已安装的插件快照中。dcode 拒绝绝对路径、父目录遍历、符号链接逃逸、缺失文件和非 Python 条目。声明 pythonExtensions 的插件必须声明一个非空的 version。安装并启用插件会授权其扩展代码。

安装后，在会话期间启用、禁用、更新或删除插件扩展，请运行 /restart 以重建智能体图。

处理失败

每个扩展设置都是事务性的。如果导入或初始化失败，Deep Agents Code 会移除该扩展的部分注册，在调试日志和 /extensions 中记录失败，并继续加载后续扩展。关闭回调失败也不会阻止其他回调运行。

参见

• 插件和市场
• 命令参考
• 配置文件
• 审批模式

---

官方原文：src/oss/deepagents/code/extensions.mdx · 非官方翻译，译文由 AI 生成，以英文原文为准。