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

PromptX的toolx工具实战从零接入你的第一个API让AI替你调用外部服务【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptXPromptX 是一款领先的 AI 智能体上下文平台它的toolx 工具系统让你用一个简单的 JS 文件就能把自己的 API、数据库、任何外部服务接入 AI——写好工具后AI 会自动发现并替你调用。本文带你从零完成第一个工具接入全程不到 10 分钟。一、toolx 是什么为什么需要它大模型聪明但手短它不能替你查天气、读 PDF、调你公司的接口。toolx 就是 PromptX 的工具执行环境解决三件事让 AI 能干活你写的每个工具都会自动暴露给 AIAI 通过 MCP 协议调用安全隔离每个工具跑在独立沙箱里依赖互相不冲突零运维声明依赖后系统自动安装pnpm 管理不用手动npm install。内置已带 6 个工具可以直接用filesystem文件操作、pdf-readerPDF 分页阅读、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两个工具一个用lodash3、一个用lodash4也完全不打架。ES Module 和 CommonJS 包也无需区分统一用loadModule(包名)加载即可沙箱实现见 ToolSandbox.js。五、让 AI 调用你的工具MCP 一键接入工具放好后无需任何注册——PromptX 内置了名为toolx的 MCP 工具实现见 toolx.tsAI 通过一段 YAML 就能操作任何工具共 5 种模式模式作用使用场景manual读工具手册第一次使用前必做execute执行工具正式调用configure设置环境变量配置 API Key 等密钥dryrun预览不执行安全检查log查看执行日志排查问题AI 实际发起的调用长这样tool: tool://weather mode: execute parameters: city: 上海还支持configure模式给工具注入 API Keytool: 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.jsMCP 工具桥接实现toolx.ts内置 PDF 阅读工具示例pdf-reader.tool.js照着上面的步骤你现在就可以写一个自己的工具然后在对话里对 AI 说一句帮我查一下杭州天气——它会自己找到你的工具、填好参数、拿到结果。这就是 toolx 的核心价值把一次性的编码变成 AI 的长期能力。【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptX创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考