工具与 MCP

Deep Agents 可以接收普通函数、LangChain tools 和 MCP server 提供的 tools。三种来源最终都会 进入 Agent 的工具集合，但工具来源不会自动决定它是否安全，也不会自动缩小凭据权限。

工具设计的四个层次

1. Schema：模型能看到哪些参数和描述。
2. 实现：工具实际读取或修改什么资源。
3. 授权：调用者、租户与资源范围如何校验。
4. 运行边界：超时、网络、sandbox、审计与速率限制。

前端类比

一个 Agent tool 很像 server action 或 RPC endpoint。TypeScript 类型和表单 schema 能帮助调用者 构造参数，但真正的鉴权、租户隔离和数据库权限仍必须在服务端实现。

Deep Agents 原生语义：工具 schema 会进入模型上下文，模型通过 tool call 请求执行。Deep Agents 与 LangChain 负责调度调用；业务工具本身仍要验证输入、权限和资源边界。MCP 只是标准化 工具发现与调用，不是信任协议。

创建一个最小业务工具

下面的工具只读取本地 fixture，便于验证 schema，而不会产生网络费用。

Python

from langchain.tools import tool

DOCUMENTS = {
    "refund": "退款申请需要订单号，并在签收后 7 天内提交。",
    "invoice": "电子发票可在订单完成后从账户中心申请。",
}


@tool
def search_policy(topic: str) -> str:
    """按主题读取教程内置的客服政策。"""
    return DOCUMENTS.get(topic, "没有匹配的本地政策")

TypeScript

import { tool } from 'langchain'
import { z } from 'zod'

const documents: Record<string, string> = {
  refund: '退款申请需要订单号，并在签收后 7 天内提交。',
  invoice: '电子发票可在订单完成后从账户中心申请。',
}

const searchPolicy = tool(({ topic }) => documents[topic] ?? '没有匹配的本地政策', {
  name: 'search_policy',
  description: '按主题读取教程内置的客服政策',
  schema: z.object({
    topic: z.enum(['refund', 'invoice']),
  }),
})

把它传给 Agent：

Python

import os

from deepagents import create_deep_agent

agent = create_deep_agent(
    model=os.environ["DEEPAGENTS_MODEL"],
    tools=[search_policy],
)

TypeScript

import { createDeepAgent } from 'deepagents'

const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')

const agent = createDeepAgent({
  model,
  tools: [searchPolicy],
})

连接 MCP Server

MCP server 可以把数据库、内部 API 或文件服务暴露为标准化 tools。Deep Agents 不需要特殊 MCP runtime；通过 LangChain MCP adapters 取得 tools 后，仍使用 tools 参数注入。

先安装适配器：

Python

pip install langchain-mcp-adapters

TypeScript

npm install @langchain/mcp-adapters

以下示例假设本机已有一个只读测试 server。不要把生产凭据写进配置文件。

Python

import os

from deepagents import create_deep_agent
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "docs": {
            "transport": "http",
            "url": "http://127.0.0.1:8000/mcp",
        }
    }
)
tools = await client.get_tools()

agent = create_deep_agent(
    model=os.environ["DEEPAGENTS_MODEL"],
    tools=tools,
)

TypeScript

import { createDeepAgent } from 'deepagents'

const { MultiServerMCPClient } = await import('@langchain/mcp-adapters')

const client = new MultiServerMCPClient({
  docs: {
    transport: 'http',
    url: 'http://127.0.0.1:8000/mcp',
  },
})
const tools = await client.getTools()

const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')

const agent = createDeepAgent({ model, tools })

Python 方法是 get_tools()，TypeScript 方法是 getTools()。这类命名差异不能通过复制另一种 语言的示例来猜测。

控制工具集合

工具越多并不一定越好：

• schema 会占用模型上下文。
• 名称和描述相似时，模型更容易选错。
• 每个写工具都会扩大攻击面。
• MCP server 可能在运行期间暴露新的工具版本。

推荐按请求、角色或 subagent 构造最小集合。例如研究 subagent 只获得搜索与读取能力，写入 生产数据库的工具只出现在经过审批的专用流程中。

错误与结果边界

业务工具应返回模型可以理解、应用可以审计的结果：

• 对可重试错误返回稳定错误码或结构，不隐藏为成功字符串。
• 对大结果写入文件并返回路径，避免挤满 messages。
• 对外部请求设置 timeout、大小限制和速率限制。
• 对敏感字段在进入 trace 和模型上下文前脱敏。
• 对写操作使用幂等键，并在工具实现中验证租户与资源范围。

MCP 不是 ACP

• MCP 连接 Agent 与工具或数据源。
• ACP 连接 Agent 与编辑器或 IDE 客户端。

两者都使用协议抽象，但通信对象与生命周期不同。后续 ACP 页面会单独介绍编辑器集成。

先修

• Agent Harness 架构与规划
• LangChain MCP

下一步

• 文件系统与 Backends

官方参考

• Deep Agents Tools for Python
• Deep Agents Tools for JavaScript
• LangChain MCP Adapters for Python
• LangChain MCP Adapters for JavaScript