---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - typescript
  - integrations
  - tools
topic: LangChain JavaScript 工具生态与 Provider 原生工具
sources:
  - https://docs.langchain.com/oss/javascript/integrations/tools
  - https://docs.langchain.com/oss/javascript/integrations/tools/index
  - https://docs.langchain.com/oss/javascript/integrations/tools/anthropic
  - https://docs.langchain.com/oss/javascript/integrations/tools/google
  - https://docs.langchain.com/oss/javascript/integrations/tools/openai
last_verified: 2026-08-11
---
# 工具生态与原生 Provider 工具

## 结论

- Tool 是给模型生成参数、把结果送回模型的受控能力；Toolkit 是一组应协同使用的 Tool。模型“会调用”不等于应用“应执行”，执行授权始终属于宿主系统。
- Anthropic、Google Gemini、OpenAI 都提供服务端原生工具，但对象格式、可组合规则、执行位置和生命周期不同，不能把它们当作通用 LangChain `tool()` 的可互换实现。
- 生产安全边界至少包括：工具 allowlist、参数 schema、身份映射、网络与文件隔离、配额/超时、人工审批、结果截断、审计以及幂等策略。

## 路由去重

`/tools` 与 `/tools/index` 返回完全相同的 Markdown 正文。两条原始路由都保留在 sources 中，但知识只归纳一次。本组共覆盖 5 条路由。

## 三类工具的执行模型

| 类型 | 示例 | 谁执行 | 主要风险 |
|---|---|---|---|
| Provider 托管 | Web search、code interpreter、file search | 模型服务侧 | 数据外发、区域/保留策略、不可见的工具版本变化 |
| Client 回调 | text editor、computer、shell、apply patch | 应用侧 handler | 任意代码/文件/桌面操作、路径穿越、权限扩大 |
| 远程服务 | MCP server、connector | 第三方或自建服务 | OAuth 令牌边界、工具供应链、服务端提示注入 |

LangChain 常用 `bindTools()` 或 `createAgent()` 把工具交给模型。模型只返回调用意图；凡是需要本地 handler 的工具，应用必须自行验证并执行，不能直接把模型参数传给 shell、数据库、浏览器或文件系统。

## Anthropic 原生工具

`@langchain/anthropic` 暴露带版本日期的工具构造器，版本名本身就是协议契约：

- memory：通过应用提供的文件回调持久化跨会话信息；应为每个租户分区、限制目录和容量，不能把“记忆目录”映射到真实工作区。
- web search：服务端实时检索并带引用；需控制最大调用次数、域名和地理配置。
- web fetch：只能读取用户显式提供或先前搜索/抓取产生的 URL。官方仍警告，在不可信输入与敏感数据共存时可能发生外泄。
- tool search：Regex 或 BM25 动态发现大量工具，减少把全部 schema 放入上下文的成本；搜索结果仍要经过服务端 allowlist。
- text editor：`view`、`str_replace`、`create`、`insert` 均由宿主实现，必须校验规范化路径、工作区边界、文件大小和并发版本。
- computer use：截图、坐标点击、键盘、滚动等；只应运行在低权限 VM/容器，关键提交必须 HITL。
- code execution：Provider 沙箱中的 Bash/文件操作，可复用 container id 做多步工作；复用也会延长状态与数据的生命周期。
- bash：由应用提供持久 shell，风险高于托管 code execution；必须隔离、过滤并限制 CPU、内存、网络和时间。
- MCP toolset：Messages API 直接连接远程 MCP，支持 allowlist、denylist、多服务器、OAuth 与 deferred tool search。

## Google Gemini 原生工具

`@langchain/google` 的 native tool 对象传给 `ChatGoogle`。关键限制是：同一次请求不能混合 Gemini native tools 与 Zod-based 标准 LangChain tools。

- Google Search 支持实时 grounding 和时间区间；旧 `googleSearchRetrieval` 仅为兼容，优先 `googleSearch`。
- Code Execution 由 Gemini 生成并执行 Python，结果可从 content blocks 读取。
- URL Context 抓取给定 URL；Google Maps 可返回 grounding metadata，并可启用地图 widget token。
- File Search 依赖预先导入的 file-search store，支持 store names、metadata filter、`topK`。
- Computer Use 面向浏览器环境，`excludedPredefinedFunctions` 可收窄动作空间。
- MCP servers 直接作为 native tool 配置；Vertex AI 模式还能用 Vertex AI Search data store grounding。

生产实现应在启动时验证所选 Gemini 模型是否支持目标 native tool，并把“不能与标准工具混用”作为编排层分支，而不是运行时试错。

## OpenAI 原生工具

`@langchain/openai` 包装 Responses API 的多种工具：

- Web Search：非推理搜索、agentic search、deep research；支持域名过滤、用户位置和 cache-only。领域过滤不是内容安全策略，返回正文仍视为不可信输入。
- MCP：既可连接任意 remote MCP server，也可用 OpenAI connector；远程服务 URL、connector id 与令牌必须独立授权。
- Code Interpreter：托管 Python 容器，支持文件和不同内存规格；容器空闲约 20 分钟后过期，不能充当耐久存储。
- File Search：先上传文件、创建 vector store、关联文件；支持 metadata 比较过滤。上传时的 `purpose`、数据保留和租户隔离需单独治理。
- Image Generation：生成、编辑、流式局部图、多轮修改；应用需要限制尺寸、质量、输出格式和存储成本。
- Computer Use：持续执行“模型动作 → 宿主执行 → 新截图”循环；官方明确只用于沙箱，避免高风险或已认证操作，并对重要决策使用 HITL。
- Local Shell / Shell：前者针对宿主单命令执行，后者可并发多条命令；模型给出的 timeout 只是建议，应用必须强制自己的上限。
- Apply Patch：返回 create/update/delete 操作和结构化 diff；必须做路径白名单、版本校验、备份/回滚和批次原子性决策。

## 生产防线

1. 工具注册表同时保存 owner、风险级别、读写属性、所需身份、超时、速率与审批策略。
2. 模型只看到当前任务最小工具集；动态工具搜索也只能搜索授权后的视图。
3. 参数先过结构 schema，再过业务规则与对象级权限；URL 需防 SSRF，文件路径需规范化，命令不得用字符串拼接。
4. 外部副作用使用 idempotency key、dry-run 或“准备/确认/执行”两阶段协议。
5. 工具输出设字节和 token 上限，剥离隐藏指令并保留来源；网页、MCP 和文件内容都按不可信数据处理。
6. 审计记录 tool name/version、actor、目标资源、参数摘要、结果状态、延迟和审批人，不记录凭据或敏感正文。