Python 扩展

用 Python 工具、中间件与存储路由来定制 dcode

Python 扩展无需修改 dcode 本身即可定制 dcode 智能体服务器。可用它们注册模型工具、LangChain 中间件与虚拟存储路由。

NOTE

Python 扩展需要设置 DEEPAGENTS_CODE_EXPERIMENTAL=1。该实验性 API 可能随时变更或被移除，恕不另行通知。

WARNING

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

创建扩展

扩展入口文件必须暴露一个异步的 extension 安装函数。dcode 会传入一个 ExtensionAPI 注册器，其中包含只读的会话上下文，以及用于添加各种能力的方法。

下面的扩展让智能体的文件工具可以通过 /memories/ 访问一个 LangGraph 存储：

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 的工具 schema 推断来转换普通可调用对象。
register_backend_route	(prefix, backend)	让某个 BackendProtocol 存储提供方可在某个虚拟路径下访问。
on_shutdown	(callback)	在智能体服务器停止时释放会话资源。支持同步与异步回调。

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

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

不要在模块导入期间打开长连接或启动后台任务。如果安装过程打开了某个会话资源，请注册一个幂等的 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 推断 schema，把普通可调用对象转换为 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/。需要带版本分发与更新时请使用插件。随某个仓库一同维护的代码请使用项目扩展。

信任项目扩展

<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 中配置发现行为：

[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 会跳过所有扩展来源。

把扩展打包进插件

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

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

每个入口都必须以 ./ 开头，且位于已安装插件的快照之内。dcode 会拒绝绝对路径、上级目录穿越、符号链接逃逸、缺失文件与非 Python 入口。声明了 pythonExtensions 的插件还必须声明非空的 version。安装并启用该插件即表示授权其扩展代码。

在会话进行中安装、启用、禁用、更新或移除某个插件扩展之后，请运行 /restart 以重建智能体图。

处理失败

每次扩展安装都是事务性的。如果导入或初始化失败，Deep Agents Code 会移除该扩展已产生的部分注册，把失败记录到调试日志与 /extensions，并继续加载后续扩展。关闭回调失败同样不会阻止其他回调运行。

另请参阅

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

---