# @agentskit/tools 中文文档

规范地址：https://npmcn.com/package/%40agentskit/tools/

版本：0\.13\.16
npm 元数据更新时间：2026-10-24T15:08:08.758Z
中文译文更新时间：2026-11-06T03:20:56.516Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/tools
原文对照：https://npmcn.com/package/%40agentskit/tools/?lang=original
项目主页：https://www.agentskit.io/docs/reference/packages/tools
源码仓库：https://github.com/AgentsKit-io/agentskit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.5 MB，40 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：5 个
- peer 依赖：better-sqlite3 ^11\.0\.0 \|\| ^12\.0\.0 \|\| ^13\.0\.0
- 首次发布：2026-04-06T11:07:52.125Z
- 最新版本发布：2026-10-24T15:08:08.319Z
- 近 30 天下载量：5790（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

可重复使用的 AgentsKit 代理可执行工具 .

## 安装

```sh
npm install @agentskit/tools
```

也可以使用：`pnpm add @agentskit/tools`、`yarn add @agentskit/tools`、`bun add @agentskit/tools`

## README

# @ agentskit/ 工具

简介 : `major-package`

![AgentsKit](https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg)

赋予你的特工真实世界的能力 不写一个集成.

[![npm version](https://img.shields.io/npm/v/@agentskit/tools?color=blue)](https://www.npmjs.com/package/@agentskit/tools) [![npm downloads](https://img.shields.io/npm/dm/@agentskit/tools)](https://www.npmjs.com/package/@agentskit/tools) [![bundle size](https://img.shields.io/bundlejs/size/@agentskit/tools?label=bundle)](https://bundlejs.com/?q=@agentskit/tools) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/LICENSE) [![stability](https://img.shields.io/badge/stability-beta-yellow)](https://npmcn.com/package/docs/STABILITY.md) [![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)

**标记 :** `ai` • 妇女 `agents` • 妇女 `llm` • 妇女 `agentskit` • 妇女 `ai-agents` • 妇女 `function-calling` • 妇女 `tool-use` • 妇女 `mcp` • 妇女 `web-search` • 妇女 `filesystem`

## 已核实的证据

-   软件包元数据和测试在 `packages/tools/`。 。 。 .
-   软件包指南 : [https://www.agentskit.io/docs/参考文献/packages/工具](https://www.agentskit.io/docs/reference/packages/tools)
-   稳定地图: [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)

## 如何适应生态系统

@ agentskit/tools 给出了代理有用的手:网络取取,搜索,文件系统, shell, SQLite, 集成, 和 MCP 方便的工具定义.

-   **探员Kit**:与本回购中的其他包一起作曲,从可互换的小零件来构建代理.
-   **书记官处**: 查找已使用此图层的即时代理和模板 [登记. agentskit.io](https://registry.agentskit.io/)。 。 。 .
-   **游戏本**: 学习本层背后的生产模式 [游戏本. agentskit.io](https://playbook.agentskit.io/)。 。 。 .

文档 : [软件包指南](https://www.agentskit.io/docs/reference/packages/tools) • 妇女 [代理交接](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt)

## 为什么工具

-   **节省融合工作天数** ——网页搜索,文件系统读取/写入, shell 执行,目录列表准备下架;不需要接线
-   **默认安全** ——文件系统工具被沙箱装入 `basePath`, shell 命令需要明确的许可列表,所以代理无法逃脱边界
-   **可用任何运行时间组成** - 工具只是有计划的物品;它们与 `@agentskit/runtime`, (中文(简体) ), `useChat`循环
-   **无摩擦地延伸** ——作者自定义工具与 `@agentskit/templates` 并且以内置方式登记

## 安装

```bash
npm install @agentskit/tools
```

## 快速实例

```ts
import { createRuntime } from '@agentskit/runtime'
import { openai } from '@agentskit/adapters'
import { webSearch, filesystem, shell } from '@agentskit/tools'

const runtime = createRuntime({
  adapter: openai({ apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }),
  tools: [
    webSearch(),
    ...filesystem({ basePath: './workspace' }),
    shell({ timeout: 10_000, allowed: ['ls', 'cat', 'grep'] }),
  ],
})

const result = await runtime.run('Find the README and summarize it')
console.log(result.content)
```

## 与 `useChat` (浏览器)

工具是简单的 `ToolDefinition` 值 - 在 [`useChat`](https://www.npmjs.com/package/@agentskit/react) 和进来一样 `createRuntime`。 。 。 .

## 正在编写工具 `defineZodTool`

如果您使用 [佐德语Name](https://zod.dev/), (中文(简体) ), `@agentskit/tools` 船舶 `defineZodTool` - 一个工厂:

-   类型 `execute` zod schema( 全类型脚本推论) 的参数
-   通过运行时验证参数 `schema.parse` 在调用函数前
-   通过用户提供将适配器的 Zod schema 转换为 JSON Schema `toJsonSchema` 回调

兹德和 `zod-to-json-schema` 为: **消费者拥有的任择依赖关系**他们是 不是软件包端点,因为 `defineZodTool` 接受结构图和 消费者提供的JSON-Schema转换器.

```bash
npm install zod zod-to-json-schema
```

```ts
import { z } from 'zod'
import { zodToJsonSchema } from 'zod-to-json-schema'
import { defineZodTool } from '@agentskit/tools'
import type { JSONSchema7 } from 'json-schema'

const lookupUser = defineZodTool({
  name: 'lookup_user',
  description: 'Look up a user by ID.',
  schema: z.object({
    userId: z.string().uuid(),
    includeProfile: z.boolean().optional(),
  }),
  toJsonSchema: (s) => zodToJsonSchema(s) as JSONSchema7,
  async execute(args) {
    // args.userId         → string  (UUID-validated by Zod at runtime)
    // args.includeProfile → boolean | undefined
    return await db.users.findById(args.userId, { profile: args.includeProfile })
  },
})
```

对于没有Zod的工具,使用 `defineTool` 从 `@agentskit/core` 和JSON 斯克马 `as const`。 。 。 .

## 特征

### 内建(6)

-   `webSearch()` ——与Serper,Tavily,DuckDuckGo或自定义供应商进行网络直播.
-   `fetchUrl()` ——安全HTTP 与 JSON / 文本处理,大小盖,锅炉板剥取.
-   `filesystem({ basePath })` ——沙箱读取,写出,并列出操作.
-   `shell({ allowed })` —— 有命令允许列表的 shell 执行 + 超时 .
-   `sqliteQueryTool({ path })` ——针对本地的 SQLite 文件只读 SQL. 可选对等程序 : `better-sqlite3`。 。 。 . **说明:** 从不反馈未验证的用户直接提示到 `sql` 字段 – 将输入过滤或使用参数化的帮助器包起来,如果将其暴露于不信任的输入.
-   `slackTool({ webhookUrl })` 贴给一个Slack Incoming Webhook。 对于 Bearer-toke 特性(搜索、频道列表),请使用 `slack()` 一体化.

### 安全出境请求

`safeFetch(input, init?, policy?)` 默认拒绝非公共主机和 重新检查每个方向跳。 地址分类来自 `@agentskit/net`,如此保留,未加说明,多播,CGNAT,IPv4-mapped 私人和其他非独播区 以及私人, 和链接本地地址。 主机名检查使用节点 DNS并失败 如果结果不公开或搜索失败,则关闭.

`isPrivateIPv4` 财务报告和审定财务报表 `isPrivateHost` 保留其遗留的小数处理 零加成点四(`010.0.0.1` 表示 `10.0.0.1`) (中文(简体) ). `safeFetch` 第一个 应用 WHINWG URL Canonicalization; 避免模糊的数字 URL 格式.

对于经过审查的内部目标,通过精确 `allowedHosts` 条目或设置 `allowPrivateHosts: true`;方向调整仍然通过选定的政策. DNS飞行前没有将解析的地址与后来的连接联系起来, 因此它不会阻止 DNS 重新绑定. `webSearch()` 还读取提供者 通过 `@agentskit/net` 有2个 MiB 默认字节限制; 设置 `maxResponseBytes` 来改变它.

### 一体化(20+)

`github`, (中文(简体) ), `linear`, (中文(简体) ), `slack`, (中文(简体) ), `notion`, (中文(简体) ), `discord`, (中文(简体) ), `gmail`, (中文(简体) ), `googleCalendar`, (中文(简体) ), `stripe`, (中文(简体) ), `postgres`, (中文(简体) ), `s3`, (中文(简体) ), `firecrawl`, (中文(简体) ), `reader`, (中文(简体) ), `documentParsers` (PDF / DOCX / XLSX), (中文(简体) ), `openaiImages`, (中文(简体) ), `elevenlabs`, (中文(简体) ), `whisper`, (中文(简体) ), `deepgram`, (中文(简体) ), `maps`, (中文(简体) ), `weather`, (中文(简体) ), `coingecko`, (中文(简体) ), `browserAgent` (普贤行相. 每个集成输出颗粒子工具(如. `githubCreateIssue`, (中文(简体) ), `stripeCreatePaymentIntent`与捆绑在一起 设置.

### 作者+组成

-   `defineZodTool` ——以Zod为基地的工厂有运行时间验证+类型推论.
-   构成,使用 `composeTool` 财务报告和审定财务报表 `wrapToolWithSelfDebug` 从 `@agentskit/core`。 。 。 .
-   用于执行政策 `createMandatorySandbox` 从 `@agentskit/sandbox`。 。 。 .

### MCP桥

-   `createMcpClient` + 键 `toolsFromMcpClient` ——消耗任何MCP服务器的工具.
-   `createMcpServer` 将 AgentsKit 工具发布到支持 文档 `2024-11-05` 工具桥。 标记工具 `requiresConfirmation` 未关闭, 除非 `authorizeToolCall` 返回一个 明确核准。 过 `validateArgs` (例如, `createAjvValidator()`(中文(简体) ) 在处决前执行已公布的计划; 远程错误得到消毒 除非 `exposeErrors: true` 已明确启用可信任的开发.
-   Stdio + 内膜运输. HTTP/SSE适配器为主机自有.

`McpToolDefinition` (从) `@agentskit/tools/mcp`)扩展核心工具 可选形状 `title` 财务报告和审定财务报表 `annotations`数字 : `title`, (中文(简体) ), `readOnlyHint`, (中文(简体) ), `destructiveHint`, (中文(简体) ), `idempotentHint`,以及 `openWorldHint`。服务器列表和 客户端导入保留这些字段,包括明确 `false` 暗示. 导入的标题使用已有的 `maxDescriptionBytes` UTF-8 限制; 错误 元数据被拒绝。 提示仍然是不信任的咨询数据,从未给予过 - 确认或改变执行政策.

这些领域遵循 [MCP 工具元数据规范](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)。 。 。 . 它们是现有 `2024-11-05` 桥; 旧客户可能忽略未知字段。 这不增加谈判或 其他功能来自较新的协议修改.

#### 支持的 MCP 协议矩阵

| 议定书的修订 | 生命周期 | 支助运输 | 支持的方法 | 就在这座桥外 |
| --- | --- | --- | --- | --- |
| `2024-11-05` | `initialize` 进行确切版本的谈判; `tools/list` 财务报告和审定财务报表 `tools/call`; 关闭待拨电话 | 结构、内饰或注入式运输 | `initialize`, (中文(简体) ), `tools/list`, (中文(简体) ), `tools/call` | 资源、提示、抽样、任务、HTTP/WebSocket、认证、限制率和持久性 |

客户端和服务器在 `initialize.params.protocolVersion` 实值 没有 `2024-11-05`。需要省略能力的主机必须围绕 (b) 桥梁并不意味着其支持或孤立 未执行.

所有的工具都尊重 `ToolDefinition` 合同(ADR 0002)——平行 工具调用工作与任何适配器, `@agentskit/runtime`, (中文(简体) ), `useChat`, (中文(简体) ), 或自定义循环.

## 子路径

| 子路径 | 目录 |
| --- | --- |
| `@agentskit/tools/mcp` | `createMcpClient`, (中文(简体) ), `createMcpServer`, (中文(简体) ), `toolsFromMcpClient`, stdio + 内膜运输. [MCP 桥面食谱](https://www.agentskit.io/docs/reference/recipes/mcp-bridge)。 。 。 . |
| `@agentskit/tools/integrations` | `github`, (中文(简体) ), `linear`, (中文(简体) ), `slack`, (中文(简体) ), `notion`, (中文(简体) ), `discord`, (中文(简体) ), `gmail`, (中文(简体) ), `googleCalendar`, (中文(简体) ), `stripe`, (中文(简体) ), `postgres`, (中文(简体) ), `s3`, (中文(简体) ), `firecrawl`, (中文(简体) ), `reader`, (中文(简体) ), `documentParsers`, (中文(简体) ), `openaiImages`, (中文(简体) ), `elevenlabs`, (中文(简体) ), `whisper`, (中文(简体) ), `deepgram`, (中文(简体) ), `maps`, (中文(简体) ), `weather`, (中文(简体) ), `coingecko`, (中文(简体) ), `browserAgent`。 。 。 . [综合食谱](https://www.agentskit.io/docs/agents/tools/integrations) + 键 [更多整合](https://www.agentskit.io/docs/reference/recipes/more-integrations)。 。 。 . |
| `@agentskit/tools/mcp-devtools` | 注入的运行时间检查工具 `RuntimeInspector`; 打开 `@agentskit/tools/mcp`。 。 。 . |
| `@agentskit/tools/validation` | 可选 Ajv 支持 `ArgsValidator` 用于核心和MCP参数执行. |

## 生态系统

| 软件包 | 作用 |
| --- | --- |
| [@ agentskit/ 核心](https://www.npmjs.com/package/@agentskit/core) | `ToolDefinition` 合同 |
| [@ agentskit/ 运行时间](https://www.npmjs.com/package/@agentskit/runtime) | `createRuntime({ tools })` |
| [@ agentskit/ 反应](https://www.npmjs.com/package/@agentskit/react) | `useChat` + UI 中的工具 |
| [@ agentskit/ 模板](https://www.npmjs.com/package/@agentskit/templates) | 脚手架新工具 |

## 贡献者

[![AgentsKit contributors](https://contrib.rocks/image?repo=AgentsKit-io/agentskit)](https://github.com/AgentsKit-io/agentskit/graphs/contributors)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 文档

[完整文档](https://www.agentskit.io/) • 妇女 [GitHub 图像](https://github.com/AgentsKit-io/agentskit)

## 成熟性和相容性

-   稳定性: **β 语录** 看到了吗 [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)
-   **节点.js 20+** 财务报告和审定财务报表 **类型脚本** 严格模式
-   发表于 `@agentskit/tools`

## 捐款

见 [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 单曲 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

### @agentskit/tools 是什么？

可重复使用的 AgentsKit 代理可执行工具 \.

### 如何安装 @agentskit/tools？

在项目目录运行 npm install @agentskit/tools，或使用 pnpm add / yarn add / bun add。

### @agentskit/tools 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentskit/tools 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @agentskit/tools 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agentskit/tools 可以商用吗？

@agentskit/tools 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agentskit/tools 的下载量有多少？

根据 npm 官方下载统计，@agentskit/tools 在 2026/10/05 – 2026/11/03 这 30 天内被下载 5,790 次，日均约 193 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentskit/tools 还在维护吗？

最新版本 0\.13\.16 发布于 2026/10/24（12 天前）；至今共发布 48 个版本，其中过去 12 个月发布了 48 个；首次发布于 2026/04/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。