PromptX的toolx工具实战：从零接入你的第一个API，让AI替你调用外部服务

PromptX的toolx工具实战：从零接入你的第一个API，让AI替你调用外部服务

【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 ｜ PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptX

PromptX 是一款领先的 AI 智能体上下文平台，它的toolx 工具系统让你用一个简单的 JS 文件就能把自己的 API、数据库、任何外部服务接入 AI——写好工具后，AI 会自动发现并替你调用。本文带你从零完成第一个工具接入，全程不到 10 分钟。

一、toolx 是什么？为什么需要它

大模型"聪明"但"手短"：它不能替你查天气、读 PDF、调你公司的接口。toolx 就是 PromptX 的工具执行环境，解决三件事：

1. 让 AI 能干活：你写的每个工具都会自动暴露给 AI，AI 通过 MCP 协议调用；
2. 安全隔离：每个工具跑在独立沙箱里，依赖互相不冲突；
3. 零运维：声明依赖后系统自动安装（pnpm 管理），不用手动npm install。

内置已带 6 个工具可以直接用：filesystem（文件操作）、pdf-reader（PDF 分页阅读）、excel-tool、word-tool、role-creator（创建 AI 角色）、tool-creator（创建新工具），源码见 packages/resource/resources/tool/。

二、准备工作：安装并启动 PromptX

• 需要 Node.js 环境，克隆仓库后进入项目执行pnpm install安装依赖；
• 启动 PromptX 桌面端，在「工具」页面可以查看系统内置工具和用户自定义工具；
• 工具的统一规范定义在 ToolInterface.js，官方使用指南在 docs/toolsandbox.md。

三、4 步写出你的第一个 API 工具

以"查询天气 API"为例，工具只需实现 3 个方法：getMetadata（元信息）、getSchema（参数说明）、execute（执行逻辑）。

第 1 步：确定目录结构

.promptx/resource/tool/ └── weather/ ├── weather.tool.js # 工具实现（必需） └── weather.manual.md # 工具手册（可选，AI 会先读它）

第 2 步：编写工具骨架

// weather.tool.js module.exports = { getMetadata() { return { name: 'weather', version: '1.0.0', description: '查询指定城市的实时天气' }; }, getSchema() { return { type: 'object', properties: { city: { type: 'string', description: '城市名称' } }, required: ['city'] }; }, // 第 3 步：声明依赖，系统自动安装 getDependencies() { return { 'axios': '^1.6.0' }; }, // 第 4 步：执行逻辑 async execute(params) { const axios = await loadModule('axios'); const res = await axios.get(`https://api.weather.com/v1/${params.city}`); return { success: true, data: res.data }; } };

💡 完整可运行示例（含数据库连接、HTTP 桥接）参考 tool-with-bridge.example.js。

getSchema里的description会直接给 AI 看——参数描述写得越清楚，AI 调用就越准确，这是新手最容易忽略的一点。

四、自动依赖安装：声明即用

工具第一次运行时，toolx 会：

• 检测getDependencies()声明的包是否已安装；
• 用 pnpm 自动安装到该工具独立的~/.promptx/toolbox/[工具名]/node_modules/；
• 修改版本号后下次运行自动更新。

每个工具拥有独立的node_modules和package.json，两个工具一个用lodash@3、一个用lodash@4也完全不打架。ES Module 和 CommonJS 包也无需区分，统一用loadModule('包名')加载即可，沙箱实现见 ToolSandbox.js。

五、让 AI 调用你的工具：MCP 一键接入

工具放好后无需任何注册——PromptX 内置了名为toolx的 MCP 工具（实现见 toolx.ts），AI 通过一段 YAML 就能操作任何工具，共 5 种模式：

AI 实际发起的调用长这样：

tool: tool://weather mode: execute parameters: city: 上海

还支持configure模式给工具注入 API Key：

tool: tool://weather mode: configure parameters: API_KEY: sk-xxxx123

工具内通过this.api.environment.get('API_KEY')安全读取，密钥不会出现在对话记录里。

六、进阶：Bridge 模式让工具可测试、可 Mock

如果你的工具依赖数据库、第三方 API 等外部服务，推荐用Bridge 桥接模式：给每个外部操作同时提供real（真实实现）和mock（模拟实现）两份代码。这样：

• 用dryrun模式测试时走mock，不消耗真实 API 配额、不碰生产库；
• 通过getBusinessErrors()定义业务错误（如"连接被拒绝"），AI 会自动识别错误并给出修复建议，而不是把一堆堆栈丢给你。

数据库 + HTTP 双桥接的完整写法在 tool-with-bridge.example.js 中，直接抄作业即可。

七、常见问题（新手避坑清单）

• require 报"这是 ES Module 包"？这是保护机制，改用await loadModule('包名')；
• AI 不调用我的工具？检查description是否清晰、是否提供了manual.md手册；
• 依赖装在哪里？~/.promptx/toolbox/[工具名]/node_modules/；
• 支持私有 npm 源？支持，配置好.npmrc即可。

八、延伸阅读

• 完整沙箱指南：docs/toolsandbox.md
• 工具接口规范：ToolInterface.js
• MCP 工具桥接实现：toolx.ts
• 内置 PDF 阅读工具示例：pdf-reader.tool.js

照着上面的步骤，你现在就可以写一个自己的工具，然后在对话里对 AI 说一句"帮我查一下杭州天气"——它会自己找到你的工具、填好参数、拿到结果。这就是 toolx 的核心价值：把一次性的编码，变成 AI 的长期能力。

【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 ｜ PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptX