向 Managed Deep Agents 添加自定义工具

为托管 deep agents 项目定义自行编写的工具。

自定义工具是 agent 可以调用的应用代码，用于获取实时数据、查询数据库、执行代码和采取操作。与指令和技能不同，MDA 不会自动发现它们。

要从远程 MCP 服务器加载工具，请参阅连接到 MCP 服务器。

NOTE

Managed Deep Agents 处于公开 beta 阶段，仅在 US 区域的 LangSmith Cloud 上可用。

将自行编写的工具放在 tools/ 下，将它们导入 agent 入口，并传递给 agent 定义：

my-agent/
  agent.py
  tools/
    customer.py

有关完整项目布局，请参阅项目结构。

要在不将工具导入 agent 入口的情况下从远程 MCP 服务器加载工具，请改用 MCP 连接器。

MCP 连接器也声明在 tools/ 下，因此 tools/mcp.py 文件名保留给该声明。

添加工具

对于业务逻辑、私有 API、数据库访问以及其他应属于 agent 项目的代码，请使用自行编写的工具。

Define a tool module

from langchain.tools import tool

@tool(parse_docstring=True)
def lookup_customer(customer_id: str) -> str:
    """Look up a customer record by ID.

    Args:
        customer_id: Customer ID from the CRM.
    """
    return f"Customer {customer_id} is on the enterprise plan."

使用清晰、唯一的工具名称以避免冲突。有关 LangChain 工具定义的更多信息，请参阅工具。

Attach the tool to the agent

将工具导入项目根目录的 agent 入口，并在 tools 列表中传递它：

from managed_deepagents import define_deep_agent

from tools.customer import lookup_customer

agent = define_deep_agent(
    name="support-agent",
    model="openai:gpt-5.5",
    tools=[lookup_customer],
)

你的导入应像在普通本地 Python 项目中一样工作。

Add human-in-the-loop (Optional)

在执行敏感工具调用之前暂停 agent，以便人员批准、编辑或拒绝。

在 agent 定义中设置 interrupt_on，并可选地设置 permissions 以控制工具和文件系统访问：

from managed_deepagents import define_deep_agent

from tools.customer import lookup_customer

agent = define_deep_agent(
    name="support-agent",
    model="openai:gpt-5.5",
    tools=[lookup_customer],
    interrupt_on={"lookup_customer": True},
)

interrupt_on 字段应用与 LangChain 的人机协同中间件相同的中断行为。

有关决策类型（批准、编辑、拒绝）、条件中断和权限规则，请参阅 Deep Agents 的人机协同和权限指南。

要恢复暂停的运行，请参阅响应中断。

如果要改为在你自己的工具发布到 Slack 的表单上暂停，请参阅agent 拥有的中断。

使用密钥和上下文

工具可以从环境变量读取部署密钥。将本地值放在 .env 中供 mda dev 使用；mda deploy 会将非保留的 .env 值作为托管部署密钥转发。

对于每次运行的值（例如请求元数据或功能标志），请使用工具的正常 LangChain 运行时上下文模式。请参阅如何从工具内部访问上下文。

部署

mda dev 和 mda deploy 会将项目文件复制到编译构建中，包括 tools/ 下的模块。工具不会同步到 Context Hub；它们随 agent 代码一起发布。

何时使用工具

概念	类型	如何到达 agent
工具	应用代码	在 agent 定义中导入并传递
MCP 连接器	托管配置	在 tools/ 下的 MCP 模块中声明；不导入 agent 入口
技能	托管上下文	agent 在相关时加载的过程
指令	托管上下文	始终启用的系统提示

更多信息请参阅项目结构。

响应中断

当运行遇到中断时，它会暂停并等待人工响应后再继续。

• 在本地开发期间，mda dev 在 LangSmith Studio 中运行 agent，Studio 会显示中断，以便你检查待处理的工具调用并恢复运行。
• 在已部署的 agent 上，通过 LangGraph server API 使用 Command(resume=...) 负载恢复暂停的运行。请参阅使用服务器 API 进行人机协同。

NOTE

在公开测试期间，Managed Deep Agents 以 CLI 为先，编程式调用尚未记录。要从你自己的应用以编程方式恢复运行，请联系你的 LangChain 团队。

人机协同需要持久线程状态才能暂停和恢复。托管运行时拥有 checkpointer，因此无需额外设置。

使用需要身份验证的工具

如果工具需要 API 密钥或 OAuth token，请使用连接在运行时解析凭据。请参阅管理连接。

访问运行时上下文

对于每次运行的值（例如请求元数据或功能标志），请使用工具的正常 LangChain 运行时上下文模式。请参阅如何从工具内部访问上下文。

要从工具读取或写入线程沙箱中的文件，请使用 runtime.backend。请参阅从代码读写沙箱文件。

---