Executor TypeScript SDK实战：用createExecutor在代码中嵌入AI Agent集成层

Executor TypeScript SDK实战：用createExecutor在代码中嵌入AI Agent集成层

【免费下载链接】executorThe missing integration layer for AI agents. Let them call any OpenAPI / MCP / GraphQL / custom js functions in secure environment.项目地址: https://gitcode.com/gh_mirrors/executor14/executor

Executor 是面向 AI Agent 的开源集成层（Integration Layer），而它的 TypeScript SDK@executor-js/sdk让你可以用几行代码，在自己的 Node.js 应用中直接创建 Executor 实例：通过createExecutor一次性接入 MCP 服务器、OpenAPI 接口、GraphQL API，统一管理密钥与工具策略，并让 AI Agent 在沙箱中安全地调用它们。

为什么需要 Executor 集成层 🧩

大多数 MCP 客户端（Claude Code、Cursor、ChatGPT 等）都要各自重复配置同一套集成：同样的 API Key 粘贴三遍、同一个 MCP 服务器反复接线，而且没有任何共享的权限概念。

Executor 解决的就是这个问题：集成加一次、凭证配一次、策略设一次，所有 Agent 共享同一个工具目录。

它的核心能力：

• 任意集成类型：一等支持 MCP、OpenAPI、GraphQL、Google Discovery
• 策略治理：每个工具可以"总是允许 / 需审批 / 禁用"
• 嵌入即用：通过 TypeScript SDK 直接跑在你自己的代码里，无需依赖任何服务

如何安装 Executor TypeScript SDK

SDK 包名为@executor-js/sdk，支持 npm / bun / pnpm 任选：

npm install @executor-js/sdk # 按需搭配插件 npm install @executor-js/plugin-mcp @executor-js/plugin-openapi @executor-js/plugin-graphql

源码位于 monorepo 的packages/core/sdk/，快速上手示例见examples/promise-sdk/src/main.ts，完整说明见packages/core/sdk/README.md。

💡 SDK 提供两个入口：@executor-js/sdk（Promise 风格，面向使用者）和@executor-js/sdk/core（Effect 风格，面向插件作者）。普通用户只需要前者。

createExecutor：5 行代码创建 AI 集成层

核心 API 只有一个函数：createExecutor。它返回一个基于内存存储的 executor 实例（默认 scope 为default-scope）：

import { createExecutor } from "@executor-js/sdk"; const executor = await createExecutor({ // 工具执行中需要用户输入时如何响应； // "accept-all" 表示自动通过，适合脚本与自动化场景 onElicitation: "accept-all", }); const tools = await executor.tools.list(); console.log(`scope=${executor.scopes[0]!.id} tools=${tools.length}`); await executor.close();

不传插件时，它没有任何工具——但整套 API 面（tools / connections / secrets / scopes）都在，装上插件后即自动生效。

调用工具同样简单：

const target = (await executor.tools.list())[0]; if (target) { const result = await executor.tools.invoke(target.id, { /* 参数 */ }); }

接入 MCP / OpenAPI / GraphQL 三类集成

以官方示例examples/promise-sdk/src/main.ts为蓝本，一个 executor 可以同时挂载三类集成：

import { createExecutor } from "@executor-js/sdk/promise"; import { mcpPlugin } from "@executor-js/plugin-mcp/promise"; import { openApiPlugin } from "@executor-js/plugin-openapi/promise"; import { graphqlPlugin } from "@executor-js/plugin-graphql/promise"; const executor = await createExecutor({ plugins: [mcpPlugin(), openApiPlugin(), graphqlPlugin()], onElicitation: "accept-all", });

MCP 远程服务器——注册后建立连接即可：

await executor.mcp.addServer({ transport: "remote", name: "Context7", endpoint: "https://mcp.context7.com/mcp", slug: "context7", });

OpenAPI 规范——直接通过 URL 加载，凭证按请求时注入而非写死在 spec 里：

await executor.openapi.addSpec({ spec: { kind: "url", url: "https://petstore3.swagger.io/api/v3/openapi.json" }, slug: "petstore", baseUrl: "https://petstore3.swagger.io/api/v3", });

GraphQL——自动完成 schema 内省：

await executor.graphql.addIntegration({ endpoint: "https://graphql.anilist.co", name: "AniList", slug: "anilist", });

三类插件的工具最终汇入同一个目录，用统一的tools.list()/execute()接口访问，工具地址形如tools.<集成>.<工具名>——调用方完全不用关心工具来自哪个协议。

沙箱执行：让 AI 生成的代码安全调用工具

把 executor 交给 LLM 时，最稳妥的方式不是让它直接调用宿主 API，而是把生成的代码丢进沙箱。这正是@executor-js/execution干的事：

import { createExecutionEngine } from "@executor-js/execution"; import { makeQuickJsExecutor } from "@executor-js/runtime-quickjs"; const engine = createExecutionEngine({ executor, codeExecutor: makeQuickJsExecutor({ timeoutMs: 2_000, memoryLimitBytes: 32 * 1024 * 1024, }), }); const result = await engine.execute(` const pets = await tools.petstore.findPetsByStatus({ status: "available" }); return pets.length; `); // { result: 12, logs: [...] }

沙箱内拿到的是一个tools.<命名空间>.<工具名>(...)代理，支持超时与内存限制；遇到 OAuth、审批等需要用户输入的工具时还能暂停（executeWithPause）后恢复。源码在packages/core/execution/，QuickJS 运行时在packages/kernel/runtime-quickjs/。

密钥管理：选一个 Secrets 插件

集成需要 API Token 时，不要让密钥出现在配置文件里——把它存进 Secret Provider，插件按 ID 解析：

用法（以内存/文件方案为例，详见packages/plugins/file-secrets/README.md）：

await executor.secrets.set({ id: "github-token", name: "GitHub Token", value: "ghp_...", scope: executor.scopes[0]!.id, });

下一步：去哪里看更多资料

• SDK 完整 API 说明：packages/core/sdk/README.md
• 端到端可运行示例：examples/promise-sdk/src/main.ts（配合examples/promise-sdk/package.json一键跑通）
• 沙箱执行引擎：packages/core/execution/README.md
• 官方文档站点源码：apps/docs/

Executor SDK 目前处于 pre-1.0 阶段（MIT 协议），API 可能随版本演进。但createExecutor+ 插件化 + 沙箱执行的这套骨架已经非常清晰——想在自己的产品里嵌入一个"AI Agent 集成层"，现在动手正是好时机。🚀

【免费下载链接】executorThe missing integration layer for AI agents. Let them call any OpenAPI / MCP / GraphQL / custom js functions in secure environment.项目地址: https://gitcode.com/gh_mirrors/executor14/executor